Overview
Thread types define the structure of conversations between users and the AI. Each thread contains messages, streaming state, and metadata.
TamboThread
Represents a conversation thread with the AI.
import type { TamboThread } from '@tambo-ai/react';
Definition
interface TamboThread {
/** Unique thread identifier */
id: string;
/** Thread name */
name?: string;
/** Messages in the thread */
messages: TamboThreadMessage[];
/** Current run status */
status: RunStatus;
/** Thread metadata */
metadata?: Record<string, unknown>;
/** When the thread was created */
createdAt: string;
/** When the thread was last updated */
updatedAt: string;
/** Whether the last run was cancelled (resets to false when a new run starts) */
lastRunCancelled: boolean;
}
Fields
Unique identifier for the thread. Generated by the API when a thread is created. Optional display name for the thread. Useful for thread lists and navigation.name: 'Weather Discussion'
messages
TamboThreadMessage[]
required
Array of messages in the thread. See TamboThreadMessage.Messages are ordered chronologically (oldest first). Current streaming/execution status of the thread. See RunStatus.
"idle" - No active run"waiting" - Run started, waiting for first event"streaming" - Actively receiving AI response
Custom metadata associated with the thread. Use this to store application-specific data.metadata: {
userId: 'user-123',
category: 'support',
tags: ['weather', 'forecast']
}
ISO 8601 timestamp when the thread was created.createdAt: '2024-03-15T10:30:00Z'
ISO 8601 timestamp when the thread was last updated.updatedAt: '2024-03-15T11:45:00Z'
Indicates if the most recent run was cancelled. Resets to false when a new run starts. RunStatus
Indicates the current state of the thread’s run lifecycle.
import type { RunStatus } from '@tambo-ai/react';
type RunStatus = "idle" | "waiting" | "streaming";
Values
No active run. The thread is waiting for user input.
A run has started but the first event hasn’t been received yet.
Actively streaming the AI’s response. Content is being received and processed.
Error information is tracked separately in StreamingState.error, not in the run status.
StreamingState
Tracks the progress of an active run. This is React-specific state management.
import type { StreamingState } from '@tambo-ai/react';
Definition
interface StreamingState {
/** Current streaming status */
status: RunStatus;
/** Active run ID (if streaming) */
runId?: string;
/** Active message ID being streamed */
messageId?: string;
/** When the current run started (timestamp in ms) */
startTime?: number;
/** When reasoning started (for duration calculation, timestamp in ms) */
reasoningStartTime?: number;
/** Error information if run failed */
error?: {
message: string;
code?: string;
};
}
Fields
Unique identifier for the active run. Only present during waiting or streaming status. ID of the message currently being streamed. Only present during streaming status. JavaScript timestamp (milliseconds since epoch) when the run started. Timestamp when the AI began reasoning. Used to calculate reasoning duration.reasoningStartTime: 1710500401000
error
{ message: string; code?: string }
Error information if the run failed.error: {
message: 'Rate limit exceeded',
code: 'rate_limit_error'
}
Thread API Response Types
Types returned by the Tambo API for thread operations.
ThreadCreateResponse
Response when creating a new thread.
import type { ThreadCreateResponse } from '@tambo-ai/react';
ThreadRetrieveResponse
Response when fetching an existing thread.
import type { ThreadRetrieveResponse } from '@tambo-ai/react';
ThreadListResponse
Response when listing threads.
import type { ThreadListResponse } from '@tambo-ai/react';
These types are re-exported from @tambo-ai/typescript-sdk. Refer to the SDK documentation for detailed field definitions.
Usage Examples
Accessing Thread State
import { useTambo } from '@tambo-ai/react';
import type { TamboThread } from '@tambo-ai/react';
function ThreadInfo() {
const { thread } = useTambo();
if (!thread) {
return <div>No active thread</div>;
}
return (
<div>
<h3>{thread.name || 'Untitled Thread'}</h3>
<p>Status: {thread.status}</p>
<p>Messages: {thread.messages.length}</p>
<p>Created: {new Date(thread.createdAt).toLocaleString()}</p>
</div>
);
}
Monitoring Streaming State
import { useTambo } from '@tambo-ai/react';
import type { StreamingState } from '@tambo-ai/react';
function StreamingIndicator() {
const { streamingState } = useTambo();
if (streamingState.status === 'idle') {
return null;
}
if (streamingState.error) {
return (
<div className="error">
Error: {streamingState.error.message}
</div>
);
}
return (
<div className="streaming">
{streamingState.status === 'waiting' && 'Starting...'}
{streamingState.status === 'streaming' && 'AI is responding...'}
</div>
);
}
Thread List Management
import { useTamboThreadList } from '@tambo-ai/react';
import type { TamboThread } from '@tambo-ai/react';
function ThreadList() {
const { threads, isLoading, error } = useTamboThreadList();
if (isLoading) return <div>Loading threads...</div>;
if (error) return <div>Error: {error.message}</div>;
return (
<ul>
{threads.map((thread: TamboThread) => (
<li key={thread.id}>
<h4>{thread.name || 'Untitled'}</h4>
<span>{thread.messages.length} messages</span>
<time>{new Date(thread.updatedAt).toLocaleString()}</time>
</li>
))}
</ul>
);
}
Creating a Thread
import { useTamboThreadInput } from '@tambo-ai/react';
import type { TamboThread } from '@tambo-ai/react';
function CreateThread() {
const { submit } = useTamboThreadInput();
const handleCreate = async () => {
const result = await submit({
message: 'Hello, AI!',
threadName: 'New Conversation',
metadata: {
category: 'general',
source: 'web-app'
}
});
console.log('Created thread:', result.threadId);
};
return <button onClick={handleCreate}>Start New Thread</button>;
}
Type Imports
import type {
TamboThread,
RunStatus,
StreamingState,
ThreadCreateResponse,
ThreadRetrieveResponse,
ThreadListResponse,
} from '@tambo-ai/react';
See Also