useAgentThreadConversation() hook
useAgentThreadConversation() is the live conversation hook behind the agent chat surface. It loads message history, subscribes to streaming updates, tracks pending submissions and approvals, and exposes the send, approval, and execution controls that the chat UI needs.Usage
The following example shows a basic usage of useAgentThreadConversation().
import { useAgentThreadConversation } from '@wacht/nextjs';export default function ThreadConversation({ threadId,}: { threadId: string;}) { const { messages, sendMessage, pendingApprovalRequest, submitApprovalResponse, } = useAgentThreadConversation({ threadId }); return ( <div> <ul> {messages.map((message) => ( <li key={message.id}>{message.content.type}</li> ))} </ul> {pendingApprovalRequest ? ( <button onClick={() => submitApprovalResponse('allow_once', pendingApprovalRequest.request_message_id) } > Approve once </button> ) : null} <button onClick={() => void sendMessage('Continue with the plan')}>Send</button> </div> );}Return value
The hook returns the following fields and methods.
›messages?: ConversationMessage[] | undefined;
messages?: ConversationMessage[] | undefined;Conversation history for the thread, kept sorted by timestamp.
›pendingMessage?: string | null | undefined;
pendingMessage?: string | null | undefined;Optimistic outgoing message text while a send is still in progress.
›pendingFiles?: File[] | null | undefined;
pendingFiles?: File[] | null | undefined;Optimistic outgoing file attachments while a send is still in progress.
›messagesLoading?: boolean | undefined;
messagesLoading?: boolean | undefined;Whether the initial message history is still loading.
›hasMoreMessages?: boolean | undefined;
hasMoreMessages?: boolean | undefined;Whether older history can still be loaded.
›isLoadingMore?: boolean | undefined;
isLoadingMore?: boolean | undefined;Whether older history is currently loading.
›sendMessage?: (message: string, files?: File[]) => Promise<void> | undefined;
sendMessage?: (message: string, files?: File[]) => Promise<void> | undefined;Sends a new user message and optional file attachments into the thread.
›loadMoreMessages?: () => Promise<void> | undefined;
loadMoreMessages?: () => Promise<void> | undefined;Loads older conversation history.
›submitApprovalResponse?: (mode: 'allow_once' | 'allow_always' | 'reject', requestMessageId?: string) => Promise<void> | undefined;
submitApprovalResponse?: (mode: 'allow_once' | 'allow_always' | 'reject', requestMessageId?: string) => Promise<void> | undefined;Responds to the current approval request.
›cancelExecution?: () => Promise<void> | undefined;
cancelExecution?: () => Promise<void> | undefined;Cancels the current execution when the thread is running.
›pendingApprovalRequest?: ThreadPendingApprovalRequestState | null | undefined;
pendingApprovalRequest?: ThreadPendingApprovalRequestState | null | undefined;Current approval request derived from the live execution state when one exists.
›activeApprovalRequestId?: string | null | undefined;
activeApprovalRequestId?: string | null | undefined;Message id for the current approval request.
›hasActiveRun?: boolean | undefined;
hasActiveRun?: boolean | undefined;Whether the thread is currently in an active run state.
›isRunning?: boolean | undefined;
isRunning?: boolean | undefined;Whether the execution state is currently running.
Overview
This hook owns the live conversation state for one thread. It loads the initial message history, listens for streaming updates, merges new conversation messages into the list, tracks optimistic send state, and derives approval and execution state from the thread events it receives.
When to use it
Use
useAgentThreadConversation() when you are building an interactive thread surface, not just a static history viewer. It is the right hook for chat panes, review conversations, and any thread page that needs sending, approvals, or streaming execution status.