Configuration

Context helpers are most commonly configured at the app root using TamboProvider. You provide a plain object where each key is the context name and each value is a function that returns the context value (or null/undefined to skip).

Basic Configuration (recommended)

Configure prebuilt context helpers at the root:

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

function AppRoot({ children }: { children: React.ReactNode }) {
  return (
    <TamboProvider
      apiKey={process.env.NEXT_PUBLIC_TAMBO_API_KEY!}
      contextHelpers={{
        userTime: currentTimeContextHelper,
        userPage: currentPageContextHelper,
      }}
    >
      {children}
    </TamboProvider>
  );
}

Notes:

• Each helper is a function that returns a value to include, or null/undefined to skip.
• The object key becomes the context name sent to the model.
• Helpers can be synchronous or asynchronous.

When NOT passing at the root: use the Context Helpers Provider

If you don’t want to pass contextHelpers at the root (or you need to scope helpers per page/layout), use TamboContextHelpersProvider where needed. This is useful for route-specific helpers or experiments without changing the root.

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

function Page() {
  return (
    <TamboContextHelpersProvider
      contextHelpers={{
        userPage: currentPageContextHelper,
      }}
    >
      {/* Components that send messages (e.g., MessageThreadFull, inputs, etc.) */}
    </TamboContextHelpersProvider>
  );
}

Notes:

• This pattern is intended for cases where you are NOT passing contextHelpers at the root, or you want page-specific registration.
• You still need TamboProvider somewhere higher in your app to enable message sending (typically in your app root).
• If helpers with the same key are registered at different times, the most recently mounted registration takes effect while it’s mounted.

Message Context Structure

When helpers resolve, they are merged into the message context keyed by your helper names:

<TamboProvider
  contextHelpers={{
    userTime: currentTimeContextHelper,
    session: async () => ({
      sessionId: "abc123",
      userId: "user456",
    }),
  }}
>

Example merged context:

{
  "userTime": {
    "timestamp": "2025-01-15T20:30:00.000Z"
  },
  "session": {
    "sessionId": "abc123",
    "userId": "user456"
  }
}