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;
}
Current run status: "idle", "waiting", or "streaming"
Thread metadata (optional)
ISO timestamp when thread was created
ISO timestamp when thread was last updated
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;
}
Unique message identifier
Message role: "user", "assistant", or "system"
Content blocks in the message (text, tool calls, components, etc.)
ISO timestamp when message was created (optional for historical messages)
Message metadata (optional)
ID of the parent message, if this was created during generation of another message (e.g., MCP sampling)
Reasoning content from the model (transient - only during streaming, not persisted)
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;
}
Content type discriminator
Unique tool call identifier
Tool input parameters (internal _tambo_* properties removed)
Whether this tool call has completed (computed by useTambo)
The status message to display (computed by useTambo)
Extracted Tambo display properties (computed by useTambo)
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;
}
Content type discriminator
Unique component identifier
Component state (optional)
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;
};
}
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;
}
A snapshot of the thread state after this event was processed
Custom Events
Tambo emits custom events during streaming:
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;
};
}
import type { TamboTool } from "@tambo-ai/client";
interface TamboTool {
name: string;
description: string;
inputSchema: JSONSchemaLite | SupportedSchema;
execute: (params: Record<string, unknown>) => unknown | Promise<unknown>;
}
inputSchema
JSONSchemaLite | SupportedSchema
Input schema (JSON Schema or supported schema library like Zod)
execute
(params: Record<string, unknown>) => unknown | Promise<unknown>
Tool execution function
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>;
}
Transport type: "sse" or "stdio"
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);
}