Events

The use-agent hook is built on an event-driven architecture. Real-time events are streamed from the server, processed by a state reducer, and used to build the conversation UI incrementally. This document details the events, their purpose, and how you can use them.

Understanding the Event Lifecycle

1. Raw Event Streaming

   A raw message is received from the Inngest realtime websocket connection

2. Mapping

   The raw message is passed to an internal mapToNetworkEvent function, which transforms it into a standardized, strongly-typed AgentKitEvent. Invalid or unrecognized messages are discarded.

3. Dispatch

   The valid AgentKitEvent is dispatched to the internal StreamingEngine.

4. Reduction

   The streaming-reducer processes the event. It uses a sequencing and buffering mechanism to ensure events are applied in the correct order, even if they arrive out of order.

5. State Update

   The reducer applies the event to the state, creating or updating messages and their parts.

6. UI Render

   Your React UI re-renders with the new state.

7. Callbacks

   If configured, onEvent, onStreamEnded, or onToolResult callbacks are fired, allowing you to react to specific events.

Core Events Reference

Run Lifecycle Events

These events manage the overall state of an agent or network execution for a given turn.

run.started

• Description: Marks the beginning of an agent or network execution in response to a user message. This is often the first event in a sequence. It sets the agent’s status to submitted.
• Payload (data):
  • threadId: The ID of the thread this run belongs to.
  • name: The name of the agent or network that started.
  • scope: "network" or "agent".
  • runId, parentRunId, messageId.
• State Impact: Sets runActive: true, agentStatus: 'submitted', and may reset the event processing sequence if it’s the start of a new “epoch”.

run.completed

• Description: Indicates that an agent or network run has finished its logic. This does not mean all streaming is complete. It primarily finalizes any in-flight tool outputs.
• Payload (data): threadId, scope, runId, messageId, name.
• State Impact: Finalizes the state of any tools that were in the executing state, moving them to output-available. The overall agent status is not yet changed to ready.

stream.ended

• Description: The final event in a sequence. It indicates that all streaming for a turn is complete and the agent is now idle.
• Payload (data): threadId, scope, runId, messageId, name.
• State Impact: Sets runActive: false and agentStatus: 'ready'. This signals that the system is ready for new user input.

Content Streaming Events

These events are responsible for building the assistant’s response message part by part.

part.created

• Description: Signals the creation of a new part within an assistant message.
• Payload (data):
  • messageId: The ID of the message this part belongs to.
  • partId: The unique ID for this new part.
  • type: Either "text" or "tool-call".
  • metadata: Optional data, often includes toolName for tool calls.
• State Impact: Adds a new, empty TextUIPart or ToolCallUIPart to the parts array of the corresponding message.

text.delta

• Description: Streams a chunk of text for a TextUIPart.
• Payload (data):
  • messageId, partId.
  • delta: The string of text to append.
• State Impact: Appends the delta content to the specified TextUIPart.

part.completed

• Description: Marks a specific message part as complete. The payload varies based on the part type.
• Payload (data):
  • messageId, partId.
  • type: Can be "text", "tool-call", or "tool-output".
  • finalContent: The complete, final content for the part (e.g., the full text or final tool output).
• State Impact:
  • For "text": Sets the part’s status to complete.
  • For "tool-call": Sets the tool’s state to input-available and populates the final input.
  • For "tool-output": Sets the tool’s state to output-available and populates the final output.

Tool Call Events

These events are specific to the lifecycle of tool calls made by an agent.

tool_call.arguments.delta

• Description: Streams a chunk of the JSON arguments for a tool call.
• Payload (data):
  • messageId, partId.
  • delta: A string chunk of the JSON arguments object.
• State Impact: Appends the delta to the input field of the ToolCallUIPart. The reducer attempts to parse the accumulating string as JSON. Sets the tool’s state to input-streaming.

tool_call.output.delta

• Description: Streams a chunk of the output from a tool execution.
• Payload (data):
  • messageId, partId.
  • delta: A string chunk of the tool’s output.
• State Impact: Appends the delta to the output field of the ToolCallUIPart. Sets the tool’s state to executing.

Consuming Events in Your App

The useAgent hook provides callbacks to tap into this event stream.

onEvent

This is the lowest-level callback. It fires for every single valid AgentKitEvent that the hook processes, giving you full visibility into the streaming process.

useAgent({
  onEvent: (evt, meta) => {
    console.log('Event received:', evt.event, 'for thread:', meta.threadId);
    if (evt.event === 'run.started') {
      // Show a global "thinking" indicator
    }
  }
})

onToolResult

A convenient, strongly-typed callback that fires only when a tool has finished executing and its final output is available (part.completed with type: "tool-output").

useAgent<MyAgentConfig>({
  onToolResult: (result) => {
    if (result.toolName === 'getWeather') {
      const weatherData = result.data; // strongly typed!
      // Display a custom weather component
    }
  }
})

onStreamEnded

Fires when the entire sequence of events for a turn is complete (stream.ended). Useful for triggering actions after the assistant has fully responded.

useAgent({
  onStreamEnded: ({ threadId }) => {
    console.log(`Agent has finished responding in thread ${threadId}.`);
    // Maybe run some analytics or enable the input field
  }
})