Tambo AI Documentation

Add visual context badges that automatically provide AI with focused information about what users are working on.

Context attachments enable you to display visual badges above the message input that automatically provide the AI with additional context. This helps the AI understand what the user is focused on and provide more relevant responses.

Overview

Context attachments appear as removable badges above the message input. When present, they automatically send contextual information to the AI, helping it:

Focus on specific files, components, or pages the user is viewing
Understand which part of your application the user is working on
Provide more targeted and relevant responses
Enable visual feedback showing what context is active

The feature also supports custom suggestions, allowing you to override Tambo's auto-generated suggestions with your own contextual suggestions.

Basic Usage

The useTamboContextAttachment hook provides methods to manage context attachments:

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

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

  const handleSelectFile = () => {
    addContextAttachment({
      name: file.name,
      icon: <FileIcon />,
      metadata: {
        filePath: file.path,
        type: file.type,
      },
    });
  };

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

Context Attachment Structure

Each context attachment has the following structure:

interface ContextAttachment {
  id: string; // Auto-generated unique identifier
  name: string; // Display name shown in the badge
  icon?: React.ReactNode; // Optional icon to display
  metadata?: Record<string, unknown>; // Additional data for the AI
}

Hook API

The useTamboContextAttachment hook returns:

const {
  attachments, // Array of active context attachments
  addContextAttachment, // Add a new context attachment
  removeContextAttachment, // Remove by ID
  clearContextAttachments, // Remove all attachments
  customSuggestions, // Current custom suggestions
  setCustomSuggestions, // Set custom suggestions
} = useTamboContextAttachment();

Adding Context Attachments

Add a context attachment by calling addContextAttachment with a name and optional metadata:

const { addContextAttachment } = useTamboContextAttachment();

// Simple text context
addContextAttachment({
  name: "Dashboard Page",
});

// With icon and metadata
addContextAttachment({
  name: "Button.tsx",
  icon: <FileIcon />,
  metadata: {
    filePath: "/src/components/Button.tsx",
    lineNumber: 42,
  },
});

The id field is automatically generated. If you add a context with the same name as an existing one, it will be ignored to prevent duplicates.

Removing Context Attachments

Remove a specific context attachment by its ID:

const { removeContextAttachment } = useTamboContextAttachment();

removeContextAttachment(contextId);

Or clear all attachments at once:

const { clearContextAttachments } = useTamboContextAttachment();

clearContextAttachments();

Displaying Active Attachments

Display the current attachments as badges:

const { attachments, removeContextAttachment } = useTamboContextAttachment();

return (
  <div>
    {attachments.map((attachment) => (
      <div key={attachment.id}>
        {attachment.icon}
        <span>{attachment.name}</span>
        <button onClick={() => removeContextAttachment(attachment.id)}>
          ×
        </button>
      </div>
    ))}
  </div>
);

Customizing Context Data

By default, context attachments send a standard structure to the AI. You can customize this by providing a getContextHelperData function to TamboProvider:

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

<TamboProvider
  apiKey="your-api-key"
  getContextHelperData={(context) => ({
    selectedFile: {
      name: context.name,
      path: context.metadata?.filePath,
      instruction: "Focus on this file when responding",
      // Add any custom fields
      language: context.metadata?.language,
      lastModified: context.metadata?.lastModified,
    },
  })}
>
  <App />
</TamboProvider>;

The function can be async to fetch additional data:

<TamboProvider
  apiKey="your-api-key"
  getContextHelperData={async (context) => {
    const fileContent = await fetchFileContent(context.metadata?.filePath);
    return {
      selectedFile: {
        name: context.name,
        content: fileContent,
        instruction: "Use this file content to help the user",
      },
    };
  }}
>
  <App />
</TamboProvider>

Custom Suggestions

Context attachments can be combined with custom suggestions to override Tambo's auto-generated suggestions:

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

function ComponentSelector({ component }) {
  const { addContextAttachment, setCustomSuggestions } =
    useTamboContextAttachment();

  const handleSelectComponent = () => {
    addContextAttachment({
      name: component.name,
      metadata: { componentId: component.id },
    });

    setCustomSuggestions([
      {
        id: "1",
        title: "Edit this component",
        detailedSuggestion: `Modify the ${component.name} component`,
        messageId: "",
      },
      {
        id: "2",
        title: "Add a feature",
        detailedSuggestion: `Add a new feature to ${component.name}`,
        messageId: "",
      },
    ]);
  };

  return <button onClick={handleSelectComponent}>Select Component</button>;
}

To clear custom suggestions and return to auto-generated ones:

setCustomSuggestions(null);

Complete Example

Here's a complete example showing context attachments in a file browser:

import { useTamboContextAttachment } from "@tambo-ai/react";
import { FileIcon, XIcon } from "lucide-react";

function FileBrowser({ files }) {
  const {
    attachments,
    addContextAttachment,
    removeContextAttachment,
    setCustomSuggestions,
  } = useTamboContextAttachment();

  const handleFileClick = (file) => {
    addContextAttachment({
      name: file.name,
      icon: <FileIcon className="w-4 h-4" />,
      metadata: {
        filePath: file.path,
        language: file.language,
      },
    });

    setCustomSuggestions([
      {
        id: "1",
        title: "Explain this file",
        detailedSuggestion: `Explain what ${file.name} does`,
        messageId: "",
      },
      {
        id: "2",
        title: "Suggest improvements",
        detailedSuggestion: `Suggest improvements to ${file.name}`,
        messageId: "",
      },
    ]);
  };

  return (
    <div>
      {/* Active Context Badges */}
      {attachments.length > 0 && (
        <div>
          {attachments.map((attachment) => (
            <div key={attachment.id}>
              {attachment.icon}
              <span>{attachment.name}</span>
              <button onClick={() => removeContextAttachment(attachment.id)}>
                <XIcon className="w-3 h-3" />
              </button>
            </div>
          ))}
        </div>
      )}

      {/* File List */}
      <div>
        {files.map((file) => (
          <button key={file.id} onClick={() => handleFileClick(file)}>
            <FileIcon />
            {file.name}
          </button>
        ))}
      </div>
    </div>
  );
}

How It Works

When you add a context attachment:

The attachment is added to the attachments array and displayed as a badge
A context helper is automatically registered with TamboContextHelpersProvider
The context data is sent along with every message until the attachment is removed
When removed, the context helper is automatically unregistered

This automatic synchronization means you don't need to manually manage context helpers—just add and remove attachments as needed.

Integration with Existing Context

Context attachments work alongside other context helpers:

Prebuilt helpers like currentTimeContextHelper continue to work
Custom helpers from contextHelpers prop are still sent
Manual context via additionalContext is merged with attachment context
All context sources are combined when sending messages

Use Cases

Context attachments are particularly useful for:

Code editors: Focus on specific files or functions
Dashboards: Indicate which widget or section is active
Forms: Show which field or step is being worked on
Multi-page apps: Display the current page or route
Component libraries: Highlight selected components

Context Attachments

On this page