Tambo Docs

Reference for TamboProvider and other provider components used to configure Tambo in your React application.

Provider components configure Tambo functionality and make hooks available throughout your component tree.

TamboProvider

The main provider that wraps your application and provides access to the Tambo API. This is the primary way to integrate Tambo into your React app.

import { TamboProvider } from "@tambo-ai/react";

function App() {
  return (
    <TamboProvider
      apiKey={process.env.NEXT_PUBLIC_TAMBO_API_KEY}
      userKey={userId}
      components={myComponents}
      tools={myTools}
    >
      <YourApp />
    </TamboProvider>
  );
}

Props

Prop	Type	Required	Description
`apiKey`	`string`	Yes	Your Tambo API key
`userToken`	`string`	No*	OAuth token for user authentication
`userKey`	`string`	No*	Unique identifier for the current user
`tamboUrl`	`string`	No	Custom Tambo API URL
`environment`	`string`	No	Environment name
`components`	`TamboComponent[]`	No	Components to register
`tools`	`TamboTool[]`	No	Tools to register
`mcpServers`	`(McpServerInfo \| string)[]`	No	MCP servers to connect
`contextHelpers`	`ContextHelpers`	No	Context helper functions
`onCallUnregisteredTool`	`(toolName: string) => void`	No	Callback for unregistered tool calls
`resources`	`ListResourceItem[]`	No	Static resources for MCP
`listResources`	`(query: string) => Promise<ListResourceItem[]>`	No	Dynamic resource listing
`getResource`	`(uri: string) => Promise<ReadResourceResult>`	No	Resource content resolver
`initialMessages`	`InputMessage[]`	No	Messages to seed new threads with, displayed before the first API call
`autoGenerateThreadName`	`boolean`	No	Auto-generate thread names after a message threshold (default: `true`)
`autoGenerateNameThreshold`	`number`	No	Messages before auto-generating a thread name (default: `3`)

*Exactly one of userToken or userKey is required to identify the current user.

userKey vs contextKey

Threads are scoped per user. The user identity comes from either userKey or the user derived from userToken. This replaces contextKey from the current SDK. The userKey is a unique identifier for the user, such as a user ID from your authentication system.

Example with All Options

import { TamboProvider, defineTool } from "@tambo-ai/react";
import { z } from "zod";
import { zodToJsonSchema } from "zod-to-json-schema";

const components = [
  {
    name: "WeatherCard",
    description: "Displays weather information",
    component: WeatherCard,
    propsSchema: zodToJsonSchema(
      z.object({
        city: z.string(),
        temperature: z.number(),
      }),
    ),
  },
];

const tools = [
  defineTool({
    name: "get_weather",
    description: "Fetch weather for a city",
    tool: async ({ city }) => fetchWeather(city),
    inputSchema: z.object({ city: z.string() }),
    outputSchema: z.object({ temperature: z.number() }),
  }),
];

<TamboProvider
  apiKey={process.env.NEXT_PUBLIC_TAMBO_API_KEY}
  userKey={session.user.id}
  components={components}
  tools={tools}
  contextHelpers={{
    currentPage: () => ({ url: window.location.href }),
  }}
>
  <App />
</TamboProvider>;

Provider Hierarchy

TamboProvider internally composes several providers in this order:

TamboClientProvider - API client and authentication
TamboRegistryProvider - Component and tool registration
TamboContextHelpersProvider - Context helper management
TamboContextAttachmentProvider - Context attachment state
TamboInteractableProvider - Interactable component tracking
TamboConfigContext - Configuration (userKey, etc.)
TamboStreamProvider - Streaming state management
TamboThreadInputProvider - Shared input state

TamboStubProvider

A stub provider for testing and development that doesn't require API connectivity.

import { TamboStubProvider } from "@tambo-ai/react";

function TestApp() {
  return (
    <TamboStubProvider
      initialMessages={[
        {
          id: "1",
          role: "assistant",
          content: [
            {
              type: "component",
              id: "comp-1",
              name: "WeatherCard",
              props: { city: "Seattle", temperature: 65 },
            },
          ],
        },
      ]}
      components={myComponents}
    >
      <YourComponent />
    </TamboStubProvider>
  );
}

Props

Prop	Type	Description
`initialMessages`	`TamboMessage[]`	Pre-configured messages
`components`	`TamboComponent[]`	Components to register
`tools`	`TamboTool[]`	Tools to register

TamboThreadInputProvider

Provides shared input state across components. This is included in TamboProvider but can be used standalone for custom setups.

import { TamboThreadInputProvider } from "@tambo-ai/react";

// Usually not needed directly - included in TamboProvider
<TamboThreadInputProvider>
  <InputComponents />
</TamboThreadInputProvider>;

The shared input state allows features like suggestions to update the input field directly, enabling seamless integration between different UI components.

Re-exported Providers

The following providers are re-exported from the base SDK for advanced use cases:

TamboClientProvider

Provides the API client and authentication context.

import { TamboClientProvider } from "@tambo-ai/react";

<TamboClientProvider
  apiKey={process.env.NEXT_PUBLIC_TAMBO_API_KEY}
  tamboUrl="https://api.tambo.co"
>
  <App />
</TamboClientProvider>;

TamboRegistryProvider

Manages component and tool registration.

import { TamboRegistryProvider } from "@tambo-ai/react";

<TamboRegistryProvider
  components={components}
  tools={tools}
  mcpServers={mcpServers}
>
  <App />
</TamboRegistryProvider>;

TamboContextHelpersProvider

Manages context helpers that provide additional information to the AI.

import { TamboContextHelpersProvider } from "@tambo-ai/react";

<TamboContextHelpersProvider
  contextHelpers={{
    currentPage: () => ({ url: window.location.href }),
  }}
>
  <App />
</TamboContextHelpersProvider>;

Configuration Hook

useTamboConfig

Access the configuration from the provider.

import { useTamboConfig } from "@tambo-ai/react";

function MyComponent() {
  const { userKey } = useTamboConfig();

  return <div>User: {userKey}</div>;
}

Return Values

Value	Type	Description
`userKey`	`string`	The user key from the provider

React SDK Providers

TamboProvider

Props

Example with All Options

Provider Hierarchy

TamboStubProvider

Props

TamboThreadInputProvider

Re-exported Providers

TamboClientProvider

TamboRegistryProvider

TamboContextHelpersProvider

Configuration Hook

useTamboConfig

Return Values

On this page