Tambo AI Generative vs Interactable Components: A Complete Developer's Guide

Tambo AI distinguishes generative components that render once per assistant message from interactable components that persist across conversation turns and support read-write operations via automatic tool calls.

Tambo AI is an open-source React SDK that enables AI agents to render dynamic UI components. Understanding the distinction between generative and interactable components is essential for building responsive AI-driven interfaces. This guide examines the architectural differences, implementation patterns, and source code structure behind these two component types in the tambo-ai/tambo repository.

What Are Generative Components in Tambo AI?

Generative components render UI elements once in response to a single assistant message. They are ideal for displaying static content like charts, summaries, or maps that do not require subsequent modification by the agent.

Lifecycle and Rendering

According to the source code in react-sdk/src/v1/components/v1-component-renderer.tsx, generative components are created when the LLM invokes a tool call supplying the component name and initial props payload. The ComponentRenderer looks up the component by name, validates props against the Zod schema if present, and returns the element wrapped in ComponentContentProvider.

After rendering, the component remains static until a new message replaces it. The lifecycle is tightly bound to the message thread, with each generative component existing as a ComponentContent block within a TamboThreadMessage.

Registration

Register generative components by declaring them in the components array passed to TamboProvider. Each entry requires a name, component reference, optional description, and optional propsSchema for validation. No higher-order component wrapper is necessary.

What Are Interactable Components in Tambo AI?

Interactable components persist across multiple conversation turns, enabling the agent to read and write props or state without generating new messages. These components support dynamic applications like editable notes, shopping carts, or spreadsheets.

Lifecycle and State Management

As implemented in react-sdk/src/hoc/with-tambo-interactable.tsx, interactable components are wrapped with the withTamboInteractable higher-order component. This HOC registers the component in the TamboInteractableProvider upon mounting, generating a unique interactableId.

The provider exposes two automatic tools: update_component_props and update_component_state. When the agent invokes these tools with the component's ID and new values, the provider updates the serialized props or internal state without creating a new thread message. The component re-renders with the updated data while maintaining its position in the UI.

Registration Pattern

Unlike generative components, interactable components require the withTamboInteractable HOC wrapper. The configuration object includes componentName, description, and propsSchema. The wrapper handles registration with the interactables context and wires the component to receive updates from the agent's tool calls.

Key Differences Between Generative and Interactable Components

The architectural distinction between these component types determines their suitability for different AI interaction patterns:

Feature	Generative Components	Interactable Components
Rendering Pattern	Once per assistant message	Persistent across turns
Agent Interaction	Read-only after initial render	Read-write via tool calls
Registration Method	Array entry in TamboProvider	withTamboInteractable HOC
Lifecycle Management	Bound to message thread	Managed by TamboInteractableProvider
Update Mechanism	New message replaces component	update_component_props or update_component_state tools
Source Files	v1-component-renderer.tsx	with-tambo-interactable.tsx, tambo-interactable-provider.tsx

Generative components excel at presenting computed results, while interactable components enable collaborative editing workflows where the agent and user manipulate shared state.

Implementation Examples

Creating a Generative Component

Define a standard React component and register it with the provider:

// components/Graph.tsx
export const Graph: React.FC<{ data: any; type: "line" | "bar" | "pie" }> = ({
  data,
  type,
}) => {
  // Render chart implementation
  return <div>{/* Chart visualization */}</div>;
};

// App.tsx
import { Graph } from "./components/Graph";
import { TamboProvider } from "@tambo-ai/react";
import { z } from "zod";

<TamboProvider
  apiKey={process.env.NEXT_PUBLIC_TAMBO_API_KEY!}
  components={[
    {
      name: "Graph",
      description: "Displays data as charts",
      component: Graph,
      propsSchema: z.object({
        data: z.array(z.object({ name: z.string(), value: z.number() })),
        type: z.enum(["line", "bar", "pie"]),
      }),
    },
  ]}>
  <Chat />
</TamboProvider>

When the LLM decides to show a line chart, it invokes the generated tool, and the ComponentRenderer in v1-component-renderer.tsx creates the element with validated props.

Creating an Interactable Component

Wrap your component with the withTamboInteractable HOC to enable persistent state:

// components/Note.tsx
export const Note: React.FC<{ title: string; content: string }> = ({
  title,
  content,
}) => (
  <div className="note">
    <h3>{title}</h3>
    <p>{content}</p>
  </div>
);

// Wrap with HOC
import { withTamboInteractable } from "@tambo-ai/react";
import { z } from "zod";

export const InteractableNote = withTamboInteractable(Note, {
  componentName: "Note",
  description: "A note that can be edited by the AI",
  propsSchema: z.object({
    title: z.string(),
    content: z.string(),
  }),
});

// Use it anywhere in the UI
<InteractableNote title="My Note" content="Start typing…" />

The HOC registers the component in TamboInteractableProvider and creates the interactableId. The agent can subsequently update the note without generating a new message.

Agent-Side Tool Calls for Interactable Updates

When the agent needs to modify an interactable component, it invokes the automatically registered tools:

{
  "name": "update_component_props",
  "arguments": {
    "id": "Note-abc123",
    "props": { "content": "Edited by the AI!" }
  }
}

After execution, the TamboInteractableProvider updates the serialized props, and the InteractableNote component re-renders with the new content.

Core Source Files

Understanding the implementation requires examining these specific files in the tambo-ai/tambo repository:

• react-sdk/src/v1/components/v1-component-renderer.tsx – Renders generative components by looking up registered components, validating props, and wrapping them in ComponentContentProvider.

• react-sdk/src/hoc/with-tambo-interactable.tsx – Higher-order component that transforms standard React components into interactable ones, handling registration and lifecycle management.

• react-sdk/src/providers/tambo-interactable-provider.tsx – Context provider that maintains the registry of interactable components and implements the update_component_props and update_component_state tools.

• react-sdk/src/providers/tambo-registry-provider.tsx – Manages the registry of generative components passed to TamboProvider.

• README.md (lines 89-115) – Canonical documentation defining both component types and their use cases.

These files together implement the two complementary component models that power Tambo AI's generative UI toolkit.

Summary

• Generative components render once per assistant message through the ComponentRenderer in v1-component-renderer.tsx, requiring only registration in the TamboProvider components array.

• Interactable components persist across conversation turns and support read-write operations via the withTamboInteractable HOC and TamboInteractableProvider.

• The agent updates interactable components through automatically exposed tools (update_component_props, update_component_state) without generating new thread messages.

• Choose generative components for static displays (charts, summaries) and interactable components for collaborative, stateful UI elements (forms, carts, editors).

Frequently Asked Questions

What is the main difference between generative and interactable components in Tambo AI?

Generative components render once in response to a single assistant message and remain static thereafter, while interactable components persist across multiple conversation turns and allow the AI agent to read and modify their props or state through tool calls.

How do I register a generative component with Tambo AI?

Register generative components by adding them to the components array in your TamboProvider configuration, specifying the component name, description, component reference, and optional Zod schema for props validation. No special wrapper is required.

What tools does Tambo AI provide for updating interactable components?

Tambo AI automatically exposes update_component_props and update_component_state tools for every interactable component wrapped with withTamboInteractable. The agent invokes these tools with the component's interactableId and new values to trigger re-renders without creating new messages.

When should I use an interactable component instead of a generative component?

Use interactable components when building collaborative interfaces where the AI needs to modify UI state across multiple turns, such as shopping carts, editable notes, or spreadsheets. Use generative components for one-time displays like charts, summaries, or maps that do not require subsequent AI modification.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}