TamboClient - Tambo AI

Overview

The TamboClient class is the main entry point for the @tambo-ai/client package. It manages threads, tool registration, streaming, and state without any React dependencies. Compatible with useSyncExternalStore for React integration via client.getState() and client.subscribe().

Installation

npm install @tambo-ai/client

Constructor

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

const client = new TamboClient(options);

options

TamboClientOptions

required

Configuration object for the client

options.apiKey

string

required

API key for authentication with Tambo

options.tamboUrl

string

Custom Tambo API URL. Conflicts with environment

options.environment

'production' | 'staging'

Environment preset. Conflicts with tamboUrl

options.userKey

string

User key for identifying the user

options.userToken

string

User token for token-based auth

options.tools

TamboTool[]

Tools to register on creation

options.mcpServers

McpServerInfo[]

MCP servers to connect on initialization

options.beforeRun

(context: BeforeRunContext) => void | Promise<void>

Callback invoked before each run starts

Core Methods

run()

Start a new run with a message. Returns a TamboStream immediately.

const stream = client.run(message, options);

message

string | InputMessage

required

The message to send (string or InputMessage object)

options

RunOptions

Configuration for the run

options.threadId

string

Thread ID to run on. If omitted, creates a new thread

options.autoExecuteTools

boolean

default:"true"

Whether to auto-execute tools when the model requests them

options.maxSteps

number

default:"10"

Max tool execution rounds

options.toolChoice

ToolChoice

How the model should select tools

options.debug

boolean

default:"false"

Enable debug logging

options.additionalContext

Record<string, unknown>

Additional context merged into the message

options.signal

AbortSignal

AbortSignal for cancellation

options.userMessageText

string

User message text for optimistic display

stream

TamboStream

A TamboStream for observing the response. See TamboStream for details

Usage Patterns

Async Iteration (Stream Mode)

const stream = client.run("Hello, AI!");

for await (const { event, snapshot } of stream) {
  console.log(event.type);
  console.log(snapshot.messages);
}

Promise Mode

const stream = client.run("Hello, AI!");
const thread = await stream.thread;
console.log(thread.messages);

getState()

Get the current client state snapshot. Compatible with useSyncExternalStore.

const state = client.getState();

state

ClientState

Current client state

state.threadMap

Record<string, ThreadState>

Map of thread ID to thread state

state.currentThreadId

string

Currently active thread ID

Subscribe to state changes. Compatible with useSyncExternalStore.

const unsubscribe = client.subscribe(listener);

listener

() => void

required

Callback invoked on state change

unsubscribe

() => void

Function to unsubscribe from state changes

React Integration Example

import { useSyncExternalStore } from "react";
import { TamboClient } from "@tambo-ai/client";

const client = new TamboClient({ apiKey: "your-api-key" });

function MyComponent() {
  const state = useSyncExternalStore(
    client.subscribe.bind(client),
    client.getState.bind(client)
  );

  return <div>{state.currentThreadId}</div>;
}

Thread Management

switchThread()

Switch to an existing thread. Fetches thread data from the API.

await client.switchThread(threadId);

threadId

string

required

The thread ID to switch to

startNewThread()

Start a new thread. Returns the new thread ID.

const threadId = client.startNewThread();

threadId

string

The new placeholder thread ID

getThread()

Get a thread from local state.

const thread = client.getThread(threadId);

threadId

string

required

The thread ID

thread

TamboThread | undefined

The thread, or undefined if not found

listThreads()

List all threads from the API.

const threads = await client.listThreads();

threads

TamboThread[]

Array of TamboThread objects

fetchThread()

Fetch a thread from the API and hydrate it into local state.

const thread = await client.fetchThread(threadId);

threadId

string

required

The thread ID to fetch

thread

TamboThread

The fetched thread

Tool Registration

registerTool()

client.registerTool(tool);

tool

TamboTool

required

The tool to register

registerTools()

client.registerTools(tools);

tools

TamboTool[]

required

The tools to register

registerComponent()

client.registerComponent(name, component);

name

string

required

Component name

component

ComponentRegistry[string]

required

The registered component

Run Control

cancelRun()

Cancel the active run on a thread.

await client.cancelRun(threadId);

threadId

string

The thread whose run to cancel. Defaults to current thread

Thread Naming

updateThreadName()

Update a thread’s name via the API.

await client.updateThreadName(threadId, name);

threadId

string

required

The thread ID

name

string

required

The new name

generateThreadName()

Generate a thread name via the API.

const name = await client.generateThreadName(threadId);

threadId

string

required

The thread ID

name

string

The generated name

MCP Integration

connectMcpServer()

Connect to an MCP server.

const mcpClient = await client.connectMcpServer(serverInfo);

serverInfo

McpServerInfo

required

The MCP server configuration

mcpClient

MCPClient

The connected MCPClient

disconnectMcpServer()

Disconnect from an MCP server.

await client.disconnectMcpServer(serverKey);

serverKey

string

required

The server key (from getMcpServerUniqueKey)

getMcpClients()

Get all connected MCP clients.

const clients = client.getMcpClients();

clients

Record<string, MCPClient>

Record of server key to MCPClient

getMcpToken()

Get an MCP token for a context key.

const token = await client.getMcpToken(contextKey, threadId);

contextKey

string

The context key

threadId

string

Optional thread ID for session-bound tokens

token

{ mcpAccessToken?: string; expiresAt?: number; hasSession?: boolean }

The MCP access token response

Suggestions

listSuggestions()

List suggestions for a message.

const suggestions = await client.listSuggestions(messageId, threadId);

messageId

string

required

The message ID

threadId

string

required

The thread ID

suggestions

Suggestion[]

Array of suggestions

generateSuggestions()

Generate suggestions for a message.

const suggestions = await client.generateSuggestions(messageId, threadId, {
  maxSuggestions: 3
});

messageId

string

required

The message ID

threadId

string

required

The thread ID

options

{ maxSuggestions?: number }

Generation options

suggestions

Suggestion[]

Array of generated suggestions

Context Helpers

addContextHelper()

Add a context helper that provides additional context on each run.

client.addContextHelper(name, fn);

name

string

required

Unique name for the helper

ContextHelperFn

required

Function returning context data

removeContextHelper()

Remove a context helper.

client.removeContextHelper(name);

name

string

required

The helper name to remove

Advanced

getAuthState()

Compute and return the current auth state.

const authState = client.getAuthState();

authState

TamboAuthState

The current auth state

getSdkClient()

Get the underlying SDK client (for advanced use cases).

const sdkClient = client.getSdkClient();

sdkClient

TamboAI

The TamboAI SDK client

Types

TamboClientOptions

interface TamboClientOptions {
  apiKey: string;
  tamboUrl?: string;
  environment?: "production" | "staging";
  userKey?: string;
  userToken?: string;
  tools?: TamboTool[];
  mcpServers?: McpServerInfo[];
  beforeRun?: (context: BeforeRunContext) => void | Promise<void>;
}

RunOptions

interface RunOptions {
  threadId?: string;
  autoExecuteTools?: boolean;
  maxSteps?: number;
  toolChoice?: ToolChoice;
  debug?: boolean;
  additionalContext?: Record<string, unknown>;
  signal?: AbortSignal;
  userMessageText?: string;
}

ClientState

interface ClientState {
  threadMap: Record<string, ThreadState>;
  currentThreadId: string;
}

BeforeRunContext

interface BeforeRunContext {
  threadId: string | undefined;
  message: InputMessage;
  tools: Readonly<Record<string, TamboTool>>;
}

ContextHelperFn

type ContextHelperFn = () =>
  | Record<string, unknown>
  | Promise<Record<string, unknown>>;

React SDK

Client

CLI

Types

​Overview

​Installation

​Constructor

​Core Methods

​run()

​Usage Patterns

​getState()

​subscribe()

​React Integration Example

​Thread Management

​switchThread()

​startNewThread()

​getThread()

​listThreads()

​fetchThread()

​Tool Registration

​registerTool()

​registerTools()

​registerComponent()

​Run Control

​cancelRun()

​Thread Naming

​updateThreadName()

​generateThreadName()

​MCP Integration

​connectMcpServer()

​disconnectMcpServer()

​getMcpClients()

​getMcpToken()

​Suggestions

​listSuggestions()

​generateSuggestions()

​Context Helpers

​addContextHelper()

​removeContextHelper()

​Advanced

​getAuthState()

​getSdkClient()

​Types

​TamboClientOptions

​RunOptions

​ClientState

​BeforeRunContext

​ContextHelperFn

Build docs developers (and LLMs) love

Overview

Installation

Constructor

Core Methods

run()

Usage Patterns

getState()

subscribe()

React Integration Example

Thread Management

switchThread()

startNewThread()

getThread()

listThreads()

fetchThread()

Tool Registration

registerTool()

registerTools()

registerComponent()

Run Control

cancelRun()

Thread Naming

updateThreadName()

generateThreadName()

MCP Integration

connectMcpServer()

disconnectMcpServer()

getMcpClients()

getMcpToken()

Suggestions

listSuggestions()

generateSuggestions()

Context Helpers

addContextHelper()

removeContextHelper()

Advanced

getAuthState()

getSdkClient()

Types

TamboClientOptions

RunOptions

ClientState

BeforeRunContext

ContextHelperFn