Core Types - Tambo AI

Overview

Core types exported by @tambo-ai/client for thread management, messages, streaming, and tool execution.

Installation

npm install @tambo-ai/client

Thread Types

TamboThread

Represents a conversation with the AI.

import type { TamboThread } from "@tambo-ai/client";

interface TamboThread {
  id: string;
  name?: string;
  messages: TamboThreadMessage[];
  status: RunStatus;
  metadata?: Record<string, unknown>;
  createdAt: string;
  updatedAt: string;
  lastRunCancelled: boolean;
}

string

Unique thread identifier

name

string

Thread name (optional)

messages

TamboThreadMessage[]

Messages in the thread

status

RunStatus

Current run status: "idle", "waiting", or "streaming"

metadata

Record<string, unknown>

Thread metadata (optional)

createdAt

string

ISO timestamp when thread was created

updatedAt

string

ISO timestamp when thread was last updated

lastRunCancelled

boolean

Whether the last run was cancelled (resets to false when a new run starts)

RunStatus

Run status indicates the current state of the thread’s run lifecycle.

type RunStatus = "idle" | "waiting" | "streaming";

"idle" - No active run
"waiting" - Run is waiting (e.g., for tool execution)
"streaming" - Run is actively streaming

StreamingState

Tracks the progress of an active run (used internally by TamboClient).

interface StreamingState {
  status: RunStatus;
  runId?: string;
  messageId?: string;
  startTime?: number;
  reasoningStartTime?: number;
  error?: {
    message: string;
    code?: string;
  };
}

Message Types

TamboThreadMessage

A message in a thread.

import type { TamboThreadMessage } from "@tambo-ai/client";

interface TamboThreadMessage {
  id: string;
  role: MessageRole;
  content: Content[];
  createdAt?: string;
  metadata?: Record<string, unknown>;
  parentMessageId?: string;
  reasoning?: string[];
  reasoningDurationMS?: number;
}

string

Unique message identifier

role

MessageRole

Message role: "user", "assistant", or "system"

content

Content[]

Content blocks in the message (text, tool calls, components, etc.)

createdAt

string

ISO timestamp when message was created (optional for historical messages)

metadata

Record<string, unknown>

Message metadata (optional)

parentMessageId

string

ID of the parent message, if this was created during generation of another message (e.g., MCP sampling)

reasoning

string[]

Reasoning content from the model (transient - only during streaming, not persisted)

reasoningDurationMS

number

Duration of the reasoning phase in milliseconds

MessageRole

type MessageRole = "user" | "assistant" | "system";

Content

Union type of all content block types.

type Content =
  | TextContent
  | TamboToolUseContent
  | ToolResultContent
  | TamboComponentContent
  | ResourceContent;

TextContent

Text content block.

interface TextContent {
  type: "text";
  text: string;
}

TamboToolUseContent

Tool call content block with computed state properties.

interface TamboToolUseContent {
  type: "tool_use";
  id: string;
  name: string;
  input: Record<string, unknown>;
  hasCompleted?: boolean;
  statusMessage?: string;
  tamboDisplayProps?: TamboToolDisplayProps;
}

type

'tool_use'

Content type discriminator

string

Unique tool call identifier

name

string

Tool name

input

Record<string, unknown>

Tool input parameters (internal _tambo_* properties removed)

hasCompleted

boolean

Whether this tool call has completed (computed by useTambo)

statusMessage

string

The status message to display (computed by useTambo)

tamboDisplayProps

TamboToolDisplayProps

Extracted Tambo display properties (computed by useTambo)

TamboToolDisplayProps

Special display properties that can be included in tool input.

interface TamboToolDisplayProps {
  _tambo_statusMessage?: string;
  _tambo_completionStatusMessage?: string;
}

ToolResultContent

Tool result content block.

interface ToolResultContent {
  type: "tool_result";
  tool_use_id: string;
  content: string | Array<TextContent | ResourceContent>;
  is_error?: boolean;
}

TamboComponentContent

Component content block with streaming state.

interface TamboComponentContent {
  type: "component";
  id: string;
  name: string;
  props: Record<string, unknown>;
  state?: Record<string, unknown>;
  streamingState?: ComponentStreamingState;
}

type

'component'

Content type discriminator

string

Unique component identifier

name

string

Component name

props

Record<string, unknown>

Component props

state

Record<string, unknown>

Component state (optional)

streamingState

ComponentStreamingState

Current streaming state: "started", "streaming", or "done"

ComponentStreamingState

type ComponentStreamingState = "started" | "streaming" | "done";

ResourceContent

Resource content block (e.g., images, files).

interface ResourceContent {
  type: "resource";
  resource: {
    type: string;
    [key: string]: unknown;
  };
}

InputMessage

Message format for sending to the API.

interface InputMessage {
  role: "user";
  content: Array<TextContent | ResourceContent>;
}

Event Types

StreamEvent

Event yielded by TamboStream’s async iterator.

import type { StreamEvent } from "@tambo-ai/client";

interface StreamEvent {
  event: BaseEvent;
  snapshot: TamboThread;
}

event

BaseEvent

The raw AG-UI event

snapshot

TamboThread

A snapshot of the thread state after this event was processed

Custom Events

Tambo emits custom events during streaming:

RunAwaitingInputEvent

interface RunAwaitingInputEvent {
  type: "custom";
  name: "tambo.run.awaiting_input";
  data: {
    pendingToolCalls: Array<{
      id: string;
      name: string;
      input: Record<string, unknown>;
    }>;
  };
}

MessageParentEvent

interface MessageParentEvent {
  type: "custom";
  name: "tambo.message.parent";
  data: {
    messageId: string;
  };
}

ComponentStartEvent

interface ComponentStartEvent {
  type: "custom";
  name: "tambo.component.start";
  data: {
    componentId: string;
    componentName: string;
  };
}

Tool Types

TamboTool

Represents a tool that can be called by the AI.

import type { TamboTool } from "@tambo-ai/client";

interface TamboTool {
  name: string;
  description: string;
  inputSchema: JSONSchemaLite | SupportedSchema;
  execute: (params: Record<string, unknown>) => unknown | Promise<unknown>;
}

name

string

Tool name

description

string

Tool description

inputSchema

JSONSchemaLite | SupportedSchema

Input schema (JSON Schema or supported schema library like Zod)

execute

(params: Record<string, unknown>) => unknown | Promise<unknown>

Tool execution function

ToolChoice

Controls how the model selects tools.

type ToolChoice =
  | { type: "auto" }
  | { type: "any" }
  | { type: "tool"; name: string };

{ type: "auto" } - Model decides whether to use tools
{ type: "any" } - Model must use at least one tool
{ type: "tool", name: string } - Model must use the specified tool

Auth Types

TamboAuthState

Auth state computed from client configuration.

import type { TamboAuthState } from "@tambo-ai/client";

type TamboAuthState =
  | { status: "unauthenticated" }
  | { status: "identified"; source: "userKey" }
  | { status: "exchanging" }
  | { status: "invalid" };

MCP Types

McpServerInfo

Configuration for an MCP server.

import type { McpServerInfo } from "@tambo-ai/client";

interface McpServerInfo {
  url: string;
  transport: MCPTransport;
  customHeaders?: Record<string, string>;
}

url

string

MCP server URL

transport

MCPTransport

Transport type: "sse" or "stdio"

customHeaders

Record<string, string>

Custom HTTP headers for SSE transport

MCPTransport

enum MCPTransport {
  SSE = "sse",
  STDIO = "stdio"
}

Utility Functions

isTamboCustomEvent()

Type guard to check if an event is a Tambo custom event.

import { isTamboCustomEvent } from "@tambo-ai/client";

if (isTamboCustomEvent(event)) {
  console.log(event.name); // "tambo.*"
}

asTamboCustomEvent()

Narrowing function to cast an event to a Tambo custom event.

import { asTamboCustomEvent } from "@tambo-ai/client";

const customEvent = asTamboCustomEvent(event);
if (customEvent?.name === "tambo.run.awaiting_input") {
  console.log(customEvent.data.pendingToolCalls);
}

React SDK

Client

CLI

Types

Documentation Index

​Overview

​Installation

​Thread Types

​TamboThread

​RunStatus

​StreamingState

​Message Types

​TamboThreadMessage

​MessageRole

​Content

​TextContent

​TamboToolUseContent

​TamboToolDisplayProps

​ToolResultContent

​TamboComponentContent

​ComponentStreamingState

​ResourceContent

​InputMessage

​Event Types

​StreamEvent

​Custom Events

​RunAwaitingInputEvent

​MessageParentEvent

​ComponentStartEvent

​Tool Types

​TamboTool

​ToolChoice

​Auth Types

​TamboAuthState

​MCP Types

​McpServerInfo

​MCPTransport

​Utility Functions

​isTamboCustomEvent()

​asTamboCustomEvent()

Build docs developers (and LLMs) love

Overview

Installation

Thread Types

TamboThread

RunStatus

StreamingState

Message Types

TamboThreadMessage

MessageRole

Content

TextContent

TamboToolUseContent

TamboToolDisplayProps

ToolResultContent

TamboComponentContent

ComponentStreamingState

ResourceContent

InputMessage

Event Types

StreamEvent

Custom Events

RunAwaitingInputEvent

MessageParentEvent

ComponentStartEvent

Tool Types

TamboTool

ToolChoice

Auth Types

TamboAuthState

MCP Types

McpServerInfo

MCPTransport

Utility Functions

isTamboCustomEvent()

asTamboCustomEvent()