useAgentContext
The useAgentContext hook manages real-time AI agent chat sessions using Server-Sent Events (SSE) for streaming responses.
Return Value
List of conversation messages
Suggested quick questions the user can ask
The message currently being generated
Images currently being processed
Files currently being processed
The current connection state
Whether the SSE connection is active
Whether the agent is currently executing
The current execution status
Whether the agent is waiting for user input
Whether there are more messages to load
Whether more messages are being loaded
Show Send a message to the agent
The message content to send
Optional file attachments
Resolves when the message is sent
Show Submit user input when requested
Resolves when the input is submitted
Show Load more messages from history
Resolves when more messages are loaded
Show Cancel the current execution
Resolves when the execution is cancelled
Show Manually connect the SSE stream
Show Manually disconnect the SSE stream
import { useAgentContext } from "@wacht/tanstack-router";
function AgentChat({ contextId, agentName }: { contextId: string; agentName: string }) {
const {
messages,
pendingMessage,
isConnected,
isExecuting,
sendMessage,
} = useAgentContext({
contextId,
agentName,
});
return (
<div>
<ConnectionStatus connected={isConnected} />
<MessageList messages={messages} />
<PendingMessage message={pendingMessage} />
<InputForm onSend={sendMessage} />
</div>
);
}
Parameters
The context ID for the agent conversation
Platform adapter for platform events and functions
Show Callback for user input requests
The user input request containing the question and input type
Show Function to call with the user's response
The user’s response value
Data Structures
interface ConversationMessage {
id: string;
role: "user" | "assistant" | "system";
content: ConversationContent;
timestamp: string;
metadata?: {
message_type: MessageType;
};
}
interface ImageData {
mime_type: string;
url?: string;
data?: string;
size_bytes?: number;
}
Show UserInputRequestContent
interface UserInputRequestContent {
type: "user_input_request";
question: string;
context: string;
input_type: "text" | "number" | "select" | "multiselect" | "boolean" | "date";
options?: string[];
default_value?: string;
placeholder?: string;
}
Examples
Basic Chat Interface
import { useAgentContext } from "@wacht/tanstack-router";
function ChatInterface() {
const { messages, sendMessage, isConnected } = useAgentContext({
contextId: "ctx_123",
agentName: "assistant",
});
return (
<div>
{!isConnected && <p>Connecting...</p>}
<MessageList messages={messages} />
<Input
placeholder="Type a message..."
onSend={(msg) => sendMessage(msg)}
/>
</div>
);
}
With File Upload
import { useAgentContext } from "@wacht/tanstack-router";
function FileUploadChat() {
const { sendMessage, pendingFiles } = useAgentContext({
contextId: "ctx_123",
agentName: "assistant",
});
const handleSend = async (message: string, files: FileList) => {
await sendMessage(message, [], Array.from(files));
};
return (
<div>
<input type="file" onChange={(e) => handleSend("Hi", e.target.files)} />
{pendingFiles && <p>Uploading {pendingFiles.length} files...</p>}
</div>
);
}
Cancel Execution
import { useAgentContext } from "@wacht/tanstack-router";
function ChatWithCancel() {
const { isExecuting, cancelExecution } = useAgentContext({
contextId: "ctx_123",
agentName: "assistant",
});
return (
<div>
{isExecuting && (
<button onClick={() => cancelExecution()}>
Cancel
</button>
)}
</div>
);
}
Load More Messages
import { useAgentContext } from "@wacht/tanstack-router";
function InfiniteScrollChat() {
const { messages, hasMoreMessages, isLoadingMore, loadMoreMessages } = useAgentContext({
contextId: "ctx_123",
agentName: "assistant",
});
return (
<div>
<MessageList messages={messages} />
{hasMoreMessages && (
<button onClick={loadMoreMessages} disabled={isLoadingMore}>
Load More
</button>
)}
</div>
);
}
SSE Connection
The hook establishes an SSE connection to:
https://{backend_host}/realtime/agent/stream?context_id={contextId}
- Automatic reconnection with exponential backoff
- Platform event and user input request support
- Ping/pong for connection health
- Session-based authentication
