Additional Context

Additional Context helps you add information that will be sent along with the user's message. You can include prebuilt helpers, create custom helpers, or send per-message context to provide more relevant AI responses.

How additional context works

When configured, context helpers automatically add metadata to messages without extra code in your components. This contextual information helps the AI:

• Provide time-aware responses (e.g., "Good morning" at the right time)
• Understand what page or section the user is currently viewing
• Give location-specific recommendations
• Provide more relevant help based on the user's current context
• Access custom business logic and application state

How to Add Context

There are four ways to add additional context to messages:

1. Prebuilt Context Helpers

Tambo provides prebuilt helper functions that can be passed to the provider:

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

<TamboProvider
  contextHelpers={{
    userTime: currentTimeContextHelper,
    userPage: currentPageContextHelper,
  }}
/>;

You can also wrap parts of your app with TamboContextHelpersProvider to declare helpers in-place. This is useful when you don't want to set contextHelpers at the root, or when you need page/layout-specific helpers that only apply while that page is mounted:

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

export default function DashboardPage() {
  return (
    <TamboContextHelpersProvider
      contextHelpers={{
        // Registers only while this page is mounted
        userPage: currentPageContextHelper,
      }}
    >
      {/* Components that send messages (e.g., MessageThreadFull, inputs, etc.) */}
    </TamboContextHelpersProvider>
  );
}

This is equivalent to passing the same helpers via TamboProvider’s contextHelpers prop. If the same key is registered in multiple places at different times, the most recently mounted registration takes effect while it’s mounted.

2. Custom Context Helpers

Create your own helpers to automatically include application-specific data. Each helper is a function that returns a value, or null to skip.

// Define helpers outside components
const profileHelper = async () => ({
  userId: getCurrentUserId(),
  role: getUserRole(),
  preferences: await getUserPreferences(),
});

<TamboProvider
  contextHelpers={{
    // The key becomes the context name
    userProfile: profileHelper,

    // Or define inline
    appState: async () => ({
      theme: getTheme(),
      version: getAppVersion(),
    }),
  }}
/>;

3. Manual Context via Message Functions

Add custom context on a per-message basis using the additionalContext parameter:

// Using useTamboThreadInput hook
const { submit } = useTamboThreadInput();

await submit({
  streamResponse: true,
  additionalContext: {
    customData: "specific to this message",
    userPreferences: { theme: "dark" },
  },
});

4. Context Attachments

Stage context pieces that will be automatically included in the next user message. Context attachments are registered as a context helper (key: contextAttachments) and are automatically cleared after submission (one-time use).

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

function FileViewer({ file }) {
  const { addContextAttachment } = useTamboContextAttachment();

  const handleSelectFile = () => {
    // Stage file content for the next message
    addContextAttachment({
      context: file.content,
      displayName: file.name,
      type: "file",
    });
  };

  return <button onClick={handleSelectFile}>Focus on {file.name}</button>;
}

All four methods can be used together—context from helpers, context attachments, and manual context are merged when sending messages.

When to Use Each Method

Available Prebuilt Context Helpers (On by Default)

These helpers are automatically enabled when using the corresponding provider. You can disable them by overriding them with a function that returns null.

currentTimeContextHelper

Provides the user's current time and timezone information.

Example result:

{
  "timestamp": "2025-01-15T20:30:00.000Z"
}

currentPageContextHelper

Provides information about the current page or route.

Example result:

{
  "url": "/dashboard/analytics",
  "title": "Analytics Dashboard"
}

currentInteractablesContextHelper

Automatically enabled when using TamboInteractableProvider. Provides information about all interactable components currently on the page that the AI can read and modify.

We found this to be the most effective way to provide the AI with information about the current page and the components on the page. It's easy to disable or customize as needed.

Example result:

{
  "description": "These are the interactable components currently visible on the page...",
  "components": [
    {
      "id": "Note-abc123",
      "componentName": "Note",
      "description": "A simple note",
      "props": { "title": "My Note", "content": "Hello world" },
      "propsSchema": "Available - use component-specific update tools"
    }
  ]
}

See Interactable Components for details on customizing or disabling this helper.

Notes:

• Helpers are plain functions. Return a value to include it, or null/undefined to skip.
• The helper key becomes the context name in messages.

Learn more about Context Attachments.