The useAgent hook is the core of the @inngest/use-agent package. It’s a comprehensive, client-side hook for React that manages real-time, multi-threaded conversations with an AgentKit network. It encapsulates the entire lifecycle of agent interactions, including sending messages, receiving streaming events, handling out-of-order event sequences, and managing connection state. 
import { useAgent, AgentProvider } from '@inngest/use-agent';

function App() {
  return (
    <AgentProvider userId="user-123">
      <ChatComponent />
    </AgentProvider>
  );
}

function ChatComponent() {
  const { messages, sendMessage, status, currentThreadId, switchToThread } = useAgent();
  
  // UI to switch threads and display messages...
  
  return <ChatUI messages={messages} onSend={sendMessage} status={status} />;
}

​
Configuration

The useAgent hook accepts a configuration object with the following properties.

​
Identity & Connection

​
userId
string
A unique identifier for the current user. This is used for personalizing agent interactions and routing real-time events. If not provided, it will be inherited from the AgentProvider.
​
channelKey
string
A key for targeting subscriptions, enabling collaborative sessions. If not provided, it defaults to the userId.
​
transport
IClientTransport
An optional transport instance to override the default HTTP transport provided by AgentProvider. This allows you to customize how the hook communicates with your backend.

​
Initial State

​
initialThreadId
string
The ID of the conversation thread to load when the hook is first mounted.
​
state
() => TState
A function that returns the current client-side UI state. This state is captured and sent with each user message, allowing agents to have context about what the user is seeing. It can also be used to restore the UI when revisiting a message.

​
Data Fetching & Caching

​
fetchThreads
function
A function to fetch a paginated list of conversation threads for the user. If not provided, the hook uses the default transport method.
​
fetchHistory
function
A function to fetch the message history for a specific thread. If not provided, the hook uses the default transport method.
​
threadsPageSize
number
default:"20"
The number of threads to fetch per page in pagination requests.

​
Callbacks

​
onEvent
(event, meta) => void
A low-level callback invoked for every real-time event processed by the hook. This is useful for building custom UI that reacts to specific agent activities, like showing a “thinking” indicator when a run.started event is received.
​
onStreamEnded
(args) => void
A callback fired when a terminal stream event (stream.ended or run.completed) is received for a thread, indicating the agent has finished its turn.
​
onToolResult
(result) => void
A strongly-typed callback that fires when a tool call completes and returns its final output. This is useful for observing or reacting to the data returned by agents’ tools.
​
onStateRehydrate
(state, messageId) => void
A callback invoked when rehydrateMessageState is called. It receives the client state that was captured when the original message was sent, allowing you to restore the UI to its previous state.
​
onThreadNotFound
(threadId) => void
A callback that is triggered if switchToThread is called with a threadId that cannot be found.

​
Behavior

​
debug
boolean
default:"false"
Enables detailed logging to the console for debugging the hook’s internal state and event flow.
​
requireProvider
boolean
default:"false"
If true, the hook will throw an error if it’s not used within an AgentProvider. When false, it creates a local fallback instance.
​
enableThreadValidation
boolean
default:"true"
If true, the hook will automatically re-fetch a thread’s history if it detects a mismatch between the local message count and the server’s message count, ensuring data consistency.

​
Return Values

The useAgent hook returns an object containing state and actions to manage conversations.

​
Core Agent State

​
messages
ConversationMessage[]
An array of messages for the currently active thread. Each message contains structured parts that are updated in real-time as events are received.
​
status
AgentStatus
The current activity status of the agent for the active thread. Possible values are: "ready", "submitted", "streaming", or "error".
​
error
AgentError
An object containing details about the last error that occurred. It’s undefined if there is no error.
​
clearError
() => void
A function to clear the current error state.
​
isConnected
boolean
Returns true if the client is currently connected to the real-time event stream.

​
Core Actions

​
sendMessage
(message, options) => Promise<void>
Sends a message to the currently active thread.
​
cancel
() => Promise<void>
Sends a request to the backend to cancel the current agent run for the active thread.
​
approveToolCall
(toolCallId, reason) => Promise<void>
Approves a tool call that is awaiting human-in-the-loop (HITL) confirmation.
​
denyToolCall
(toolCallId, reason) => Promise<void>
Denies a tool call that is awaiting human-in-the-loop (HITL) confirmation.

​
Thread Management State

​
threads
Thread[]
An array of all conversation threads loaded for the user.
​
currentThreadId
string | null
The ID of the currently active thread.
​
threadsLoading
boolean
true while the initial list of threads is being fetched.
​
threadsHasMore
boolean
true if there are more pages of threads to be loaded.
​
threadsError
string | null
Contains an error message if fetching threads failed.
​
isLoadingInitialThread
boolean
true only while the selected thread’s history has not yet been loaded.

​
Thread Management Actions

​
switchToThread
(threadId) => Promise<void>
Switches the active conversation to a different thread, loading its history.
​
setCurrentThreadId
(threadId) => void
Immediately changes the currentThreadId without fetching history. Useful for optimistic UI updates before switchToThread completes.
​
createNewThread
() => string
Creates a new, empty thread locally and returns its generated UUID.
​
deleteThread
(threadId) => Promise<void>
Deletes a thread from the backend and removes it from the local state.
​
loadMoreThreads
() => Promise<void>
Fetches the next page of threads.
​
refreshThreads
() => Promise<void>
Refetches the first page of threads to get the latest list.

​
Advanced Actions

​
sendMessageToThread
(threadId, message, options) => Promise<void>
Sends a message to a specific thread, which may not be the currently active one.
​
loadThreadHistory
(threadId) => Promise<ConversationMessage[]>
Manually fetches the message history for a specific thread.
​
clearThreadMessages
(threadId) => void
Clears all messages from a specific thread’s local state.
​
replaceThreadMessages
(threadId, messages) => void
Replaces all messages in a specific thread’s local state. Useful for manually populating history.
​
rehydrateMessageState
(messageId) => void
Triggers the onStateRehydrate callback with the client state associated with a specific message. Useful for UI features like “edit message” where you need to restore the UI to how it was when the message was sent.