Tambo AI Documentation

The @tambo-ai/react package exports TypeScript types and interfaces to help you build type-safe AI applications.

TamboTool

The TamboTool interface defines the structure for registering tools with Tambo.

interface TamboTool {
  name: string;
  description: string;
  tool: (params: Record<string, unknown>) => unknown;
  inputSchema: z.ZodObject | JSONSchema7;
  outputSchema: z.ZodTypeAny | JSONSchema7;
  transformToContent?: (
    result: any,
  ) => Promise<ChatCompletionContentPart[]> | ChatCompletionContentPart[];
  maxCalls?: number;
}

Properties

name

The unique identifier for the tool. This is how Tambo references the tool internally.

name: string;

description

A clear description of what the tool does. This helps the AI understand when to use the tool.

description: string;

tool

The function that implements the tool's logic. Receives a single object with named parameters.

tool: (params: Record<string, unknown>) => unknown;

inputSchema

A Zod schema that defines the tool's input parameters. Can also be a JSON Schema object. Use z.object({}) (or an equivalent empty object schema) for no-parameter tools.

inputSchema: z.ZodObject | JSONSchema7;

Example:

inputSchema: z.object({
  city: z.string().describe("The city name"),
  units: z.enum(["celsius", "fahrenheit"]).optional(),
});

outputSchema

A Zod schema that defines the tool's return type. Can also be a JSON Schema object.

outputSchema: z.ZodTypeAny | JSONSchema7;

Example:

outputSchema: z.object({
  temperature: z.number(),
  condition: z.string(),
});

transformToContent (optional)

A function that transforms the tool's return value into an array of content parts. Use this when your tool needs to return rich content like images or audio.

transformToContent?: (result: any) => Promise<ChatCompletionContentPart[]> | ChatCompletionContentPart[];

By default, tool responses are stringified and wrapped in a text content part. The transformToContent function allows you to return rich content including images, audio, or mixed media.

Example:

transformToContent: (result) => [
  { type: "text", text: result.description },
  { type: "image_url", image_url: { url: result.imageUrl } },
];

Learn more about returning rich content from tools.

TamboComponent

The TamboComponent interface defines the structure for registering React components with Tambo.

interface TamboComponent {
  name: string;
  description: string;
  component: ComponentType<any>;
  propsSchema?: z.ZodTypeAny | JSONSchema7;
  propsDefinition?: any;
  loadingComponent?: ComponentType<any>;
  associatedTools?: TamboTool[];
}

Properties

name

The unique identifier for the component.

name: string;

description

A clear description of what the component displays or does. This helps the AI understand when to use the component.

description: string;

component

The React component to render.

component: ComponentType<any>;

propsSchema (recommended)

A Zod schema that defines the component's props.

propsSchema?: z.ZodTypeAny | JSONSchema7;

propsDefinition (deprecated)

A JSON object defining the component's props. Use propsSchema instead.

propsDefinition?: any;

loadingComponent (optional)

A component to display while the main component is loading.

loadingComponent?: ComponentType<any>;

associatedTools (optional)

An array of tools that are associated with this component.

associatedTools?: TamboTool[];

ChatCompletionContentPart

Content parts that can be sent to or received from the AI.

interface ChatCompletionContentPart {
  type: "text" | "image_url" | "input_audio";
  text?: string;
  image_url?: { url: string; detail?: "auto" | "high" | "low" };
  input_audio?: { data: string; format: "wav" | "mp3" };
}

This type is used in the transformToContent function to define rich content responses.

TamboThreadMessage

A message in a Tambo thread.

interface TamboThreadMessage {
  id: string;
  role: "user" | "assistant" | "system" | "tool";
  content: ChatCompletionContentPart[];
  createdAt: string;
  renderedComponent?: React.ReactNode;
  component?: {
    componentName: string;
    props: any;
  };
  actionType?: string;
  error?: string;
}

TamboThread

A Tambo conversation thread.

interface TamboThread {
  id: string;
  messages: TamboThreadMessage[];
  contextKey?: string;
  createdAt: string;
  updatedAt: string;
}

GenerationStage

The current stage of AI response generation.

enum GenerationStage {
  IDLE = "IDLE",
  CHOOSING_COMPONENT = "CHOOSING_COMPONENT",
  FETCHING_CONTEXT = "FETCHING_CONTEXT",
  HYDRATING_COMPONENT = "HYDRATING_COMPONENT",
  STREAMING_RESPONSE = "STREAMING_RESPONSE",
  COMPLETE = "COMPLETE",
  ERROR = "ERROR",
}

ContextAttachment

Represents a context attachment that will be sent with the next user message.

interface ContextAttachment {
  id: string; // Auto-generated unique identifier
  displayName?: string; // Optional display name for UI rendering
  context: string; // The context value that will be used in additionalContext
  type?: string; // Optional type identifier for grouping/rendering
}

Properties

id

Unique identifier for the attachment. Auto-generated when adding a context attachment.

id: string;

displayName

Display name for UI rendering.

displayName: string;

context

The context value that will be used in additionalContext when the next message is sent.

context: string;

type

Optional type identifier for grouping/rendering multiple contexts of the same type.

type?: string;

ContextAttachmentState

The state interface returned by the useTamboContextAttachment hook.

interface ContextAttachmentState {
  attachments: ContextAttachment[];
  addContextAttachment: (
    contextAttachment: Omit<ContextAttachment, "id">,
  ) => ContextAttachment;
  removeContextAttachment: (id: string) => void;
  clearContextAttachments: () => void;
}

Properties

attachments

Array of active context attachments that will be included in additionalContext when the next message is sent.

attachments: ContextAttachment[];

Function to add a new context attachment. The id is automatically generated. All attachments are automatically registered together as a single merged context helper (key: contextAttachments) that returns an array of all active attachments.

addContextAttachment: (contextAttachment: Omit<ContextAttachment, "id">) =>
  ContextAttachment;

removeContextAttachment

Function to remove a specific context attachment by its ID. The context helper automatically updates to reflect the change.

removeContextAttachment: (id: string) => void;

clearContextAttachments

Function to remove all active context attachments. The context helper automatically updates to reflect the change. Context attachments are automatically cleared after message submission (one-time use), so you typically don't need to call this manually.

clearContextAttachments: () => void;

StreamStatus

Global stream status flags for a component during streaming. Returned by useTamboStreamStatus.

interface StreamStatus {
  isPending: boolean; // No tokens received yet, generation not active
  isStreaming: boolean; // Active streaming - generation or props still streaming
  isSuccess: boolean; // Complete - all props finished without error
  isError: boolean; // Fatal error occurred
  streamError?: Error; // First error encountered (if any)
}

PropStatus

Streaming status flags for individual component props. Returned by useTamboStreamStatus.

interface PropStatus {
  isPending: boolean; // No tokens received for this prop yet
  isStreaming: boolean; // Prop has partial content, still updating
  isSuccess: boolean; // Prop finished streaming successfully
  error?: Error; // Error during streaming (if any)
}

TamboInteractableComponent

Represents a component instance that can be interacted with by Tambo. Extends TamboComponent.

interface TamboInteractableComponent<
  Props = Record<string, unknown>,
  State = Record<string, unknown>,
> extends TamboComponent {
  id: string; // Unique identifier for this instance
  props: Props; // Current props
  isSelected?: boolean; // Whether selected for interaction
  state?: State; // Current component state
  stateSchema?: SupportedSchema<State>; // Optional state validation schema
}

InteractableConfig

Configuration for the withInteractable HOC.

interface InteractableConfig<
  Props = Record<string, unknown>,
  State = Record<string, unknown>,
> {
  componentName: string; // Name used for identification
  description: string; // Description for LLM understanding
  propsSchema?: SupportedSchema<Props>; // Optional props validation
  stateSchema?: SupportedSchema<State>; // Optional state validation
}

WithTamboInteractableProps

Props injected by withInteractable HOC.

interface WithTamboInteractableProps {
  interactableId?: string; // Optional custom ID
  onInteractableReady?: (id: string) => void; // Called when registered
  onPropsUpdate?: (newProps: Record<string, unknown>) => void; // Called on prop updates
}

InteractableMetadata

Metadata about an interactable component.

interface InteractableMetadata {
  id: string;
  componentName: string;
  description: string;
}

ToolAnnotations

Annotations describing a tool's behavior, aligned with the MCP specification.

type ToolAnnotations = MCPToolAnnotations & {
  tamboStreamableHint?: boolean; // Safe to call repeatedly during streaming
};

The tamboStreamableHint property indicates that the tool is safe to be called repeatedly while a response is being streamed. This is typically used for read-only tools that do not cause side effects.

SupportedSchema

A schema type that accepts either a Standard Schema compliant validator or a raw JSON Schema object.

type SupportedSchema<Shape = unknown> =
  | StandardSchemaV1<Shape, Shape>
  | JSONSchema7;

Standard Schema is a specification that provides a unified interface for TypeScript validation libraries. Libraries like Zod, Valibot, and ArkType implement this spec.

StagedImage

Represents an image staged for upload in message input.

interface StagedImage {
  id: string; // Unique identifier
  name: string; // File name
  dataUrl: string; // Base64 data URL
  file: File; // Original File object
  size: number; // File size in bytes
  type: string; // MIME type
}

AdditionalContext

Interface for additional context that can be added to messages.

interface AdditionalContext {
  name: string; // Name of the context type
  context: unknown; // The context data
}

ContextHelperFn

A function that returns context data to include in messages.

type ContextHelperFn = () =>
  | unknown
  | null
  | undefined
  | Promise<unknown | null | undefined>;

Return null or undefined to skip including the context.

ContextHelpers

A collection of context helpers keyed by their context name.

type ContextHelpers = Record<string, ContextHelperFn>;

The key becomes the AdditionalContext.name sent to the model.

TypeScript Types

On this page