Events

The Agent User Interaction Protocol SDK uses a streaming event-based architecture. Events are the fundamental units of communication between agents and the frontend. This section documents the event types and their properties.

EventType Enum

The EventType enum defines all possible event types in the system:

enum EventType {
  TEXT_MESSAGE_START = "TEXT_MESSAGE_START",
  TEXT_MESSAGE_CONTENT = "TEXT_MESSAGE_CONTENT",
  TEXT_MESSAGE_END = "TEXT_MESSAGE_END",
  TOOL_CALL_START = "TOOL_CALL_START",
  TOOL_CALL_ARGS = "TOOL_CALL_ARGS",
  TOOL_CALL_END = "TOOL_CALL_END",
  TOOL_CALL_RESULT = "TOOL_CALL_RESULT",
  STATE_SNAPSHOT = "STATE_SNAPSHOT",
  STATE_DELTA = "STATE_DELTA",
  MESSAGES_SNAPSHOT = "MESSAGES_SNAPSHOT",
  ACTIVITY_SNAPSHOT = "ACTIVITY_SNAPSHOT",
  ACTIVITY_DELTA = "ACTIVITY_DELTA",
  RAW = "RAW",
  CUSTOM = "CUSTOM",
  RUN_STARTED = "RUN_STARTED",
  RUN_FINISHED = "RUN_FINISHED",
  RUN_ERROR = "RUN_ERROR",
  STEP_STARTED = "STEP_STARTED",
  STEP_FINISHED = "STEP_FINISHED",
  REASONING_START = "REASONING_START",
  REASONING_MESSAGE_START = "REASONING_MESSAGE_START",
  REASONING_MESSAGE_CONTENT = "REASONING_MESSAGE_CONTENT",
  REASONING_MESSAGE_END = "REASONING_MESSAGE_END",
  REASONING_MESSAGE_CHUNK = "REASONING_MESSAGE_CHUNK",
  REASONING_END = "REASONING_END",
  REASONING_ENCRYPTED_VALUE = "REASONING_ENCRYPTED_VALUE",
  SUBAGENT_STARTED = "SUBAGENT_STARTED",
  SUBAGENT_FINISHED = "SUBAGENT_FINISHED",
  SUBAGENT_ERROR = "SUBAGENT_ERROR",
}

BaseEvent

All events inherit from the BaseEvent type, which provides common properties shared across all event types.

type BaseEvent = {
  type: EventType // Discriminator field
  timestamp?: number
  rawEvent?: any
  metadata?: Record<string, any>
}

Property	Type	Description
`type`	`EventType`	The type of event (discriminator field for the union)
`timestamp`	`number` (optional)	Timestamp when the event was created
`rawEvent`	`any` (optional)	Original event data if this event was transformed
`metadata`	`Record<string, any>` (optional)	Extra information attached to the event

metadata is open by key: any JSON value is allowed under a key, including null. The object may be absent, but a present one is never null — an explicit null parses as absent. The ag-ui key is reserved for AG-UI’s own use. Use mergeMetadata from @ag-ui/core to fold event metadata into a message; see Metadata.

Lifecycle Events

These events represent the lifecycle of an agent run.

RunStartedEvent

Signals the start of an agent run.

type RunStartedEvent = BaseEvent & {
  type: EventType.RUN_STARTED
  threadId: string
  runId: string
  parentRunId?: string
  input?: RunAgentInput
}

Property	Type	Description
`threadId`	`string`	ID of the conversation thread
`runId`	`string`	ID of the agent run
`parentRunId`	`string` (optional)	(Optional) Lineage pointer for branching/time travel. If present, refers to a prior run within the same thread
`input`	`RunAgentInput` (optional)	(Optional) The exact agent input payload sent to the agent for this run. May omit messages already in history

TokenUsage

A reusable, numeric-only token usage summary carried on terminal run events. It intentionally contains only provider/model labels and token counts — no prompts, completions, messages, or identifiers. The counts follow the protocol’s accounting: the input and output counts are totals, and the cache and reasoning counts are parts of them, never additions.

type TokenUsage = {
  provider?: string
  model?: string
  inputTokens?: number
  outputTokens?: number
  totalTokens?: number
  reasoningTokens?: number
  cachedInputTokens?: number
  cacheWriteInputTokens?: number
}

Property	Type	Description
`provider`	`string` (optional)	Provider that reported the usage (e.g. `openai`)
`model`	`string` (optional)	Model that produced the usage
`inputTokens`	`number` (optional)	All input tokens, cache reads and writes included
`outputTokens`	`number` (optional)	All output tokens, reasoning included
`totalTokens`	`number` (optional)	`inputTokens` plus `outputTokens`
`reasoningTokens`	`number` (optional)	Output tokens spent on reasoning; part of `outputTokens`
`cachedInputTokens`	`number` (optional)	Input tokens read from a prompt cache; part of `inputTokens`
`cacheWriteInputTokens`	`number` (optional)	Input tokens written to a prompt cache; part of `inputTokens`

RunFinishedEvent

Signals the successful completion of an agent run.

type RunFinishedEvent = BaseEvent & {
  type: EventType.RUN_FINISHED
  threadId: string
  runId: string
  result?: any
  usage?: TokenUsage[]
}

Property	Type	Description
`threadId`	`string`	ID of the conversation thread
`runId`	`string`	ID of the agent run
`result`	`any` (optional)	Result data from the agent run
`usage`	`TokenUsage[]` (optional)	Per-(provider, model) token usage for the run, when reported

RunErrorEvent

Signals an error during an agent run.

type RunErrorEvent = BaseEvent & {
  type: EventType.RUN_ERROR
  message: string
  code?: string
  usage?: TokenUsage[]
}

Property	Type	Description
`message`	`string`	Error message
`code`	`string` (optional)	Error code
`usage`	`TokenUsage[]` (optional)	Partial token usage from model calls that completed

StepStartedEvent

Signals the start of a step within an agent run.

type StepStartedEvent = BaseEvent & {
  type: EventType.STEP_STARTED
  stepName: string
}

Property	Type	Description
`stepName`	`string`	Name of the step

StepFinishedEvent

Signals the completion of a step within an agent run.

type StepFinishedEvent = BaseEvent & {
  type: EventType.STEP_FINISHED
  stepName: string
}

Property	Type	Description
`stepName`	`string`	Name of the step

Text Message Events

These events represent the lifecycle of text messages in a conversation.

TextMessageStartEvent

Signals the start of a text message.

type TextMessageStartEvent = BaseEvent & {
  type: EventType.TEXT_MESSAGE_START
  messageId: string
  role: "assistant"
}

Property	Type	Description
`messageId`	`string`	Unique identifier for the message
`role`	`"assistant"`	Role is always “assistant”

TextMessageContentEvent

Represents a chunk of content in a streaming text message.

type TextMessageContentEvent = BaseEvent & {
  type: EventType.TEXT_MESSAGE_CONTENT
  messageId: string
  delta: string // Non-empty string
}

Property	Type	Description
`messageId`	`string`	Matches the ID from TextMessageStartEvent
`delta`	`string`	Text content chunk (non-empty)

TextMessageEndEvent

Signals the end of a text message.

type TextMessageEndEvent = BaseEvent & {
  type: EventType.TEXT_MESSAGE_END
  messageId: string
}

Property	Type	Description
`messageId`	`string`	Matches the ID from TextMessageStartEvent

TextMessageChunkEvent

Convenience event that expands to TextMessageStart → TextMessageContent → TextMessageEnd automatically in the JS/TS client.

type TextMessageChunkEvent = BaseEvent & {
  type: EventType.TEXT_MESSAGE_CHUNK
  messageId?: string // required on the first chunk for a message
  role?: "developer" | "system" | "assistant" | "user"
  delta?: string
}

Behavior

Omit start/end: The client transforms chunk sequences into the standard start/content/end triad, so you don’t need to emit them manually.
First chunk requirements: The first chunk for a message must include messageId. When role is omitted, it defaults to assistant.
Streaming: Subsequent chunks with the same messageId emit TextMessageContent events. TextMessageEnd is emitted automatically when a different message starts or when the stream completes.

Tool Call Events

These events represent the lifecycle of tool calls made by agents.

ToolCallStartEvent

Signals the start of a tool call.

type ToolCallStartEvent = BaseEvent & {
  type: EventType.TOOL_CALL_START
  toolCallId: string
  toolCallName: string
  parentMessageId?: string
}

Property	Type	Description
`toolCallId`	`string`	Unique identifier for the tool call
`toolCallName`	`string`	Name of the tool being called
`parentMessageId`	`string` (optional)	ID of the parent message

ToolCallArgsEvent

Represents a chunk of argument data for a tool call.

type ToolCallArgsEvent = BaseEvent & {
  type: EventType.TOOL_CALL_ARGS
  toolCallId: string
  delta: string
}

Property	Type	Description
`toolCallId`	`string`	Matches the ID from ToolCallStartEvent
`delta`	`string`	Argument data chunk

ToolCallEndEvent

Signals the end of a tool call.

type ToolCallEndEvent = BaseEvent & {
  type: EventType.TOOL_CALL_END
  toolCallId: string
}

Property	Type	Description
`toolCallId`	`string`	Matches the ID from ToolCallStartEvent

ToolCallResultEvent

Provides the result of a tool call execution.

type ToolCallResultEvent = BaseEvent & {
  type: EventType.TOOL_CALL_RESULT
  messageId: string
  toolCallId: string
  content: string
  role?: "tool"
}

Property	Type	Description
`messageId`	`string`	ID of the conversation message this result belongs to
`toolCallId`	`string`	Matches the ID from the corresponding ToolCallStartEvent
`content`	`string`	The actual result/output content from the tool execution
`role`	`"tool"` (optional)	Optional role identifier, typically “tool” for tool results

State Management Events

These events are used to manage agent state.

StateSnapshotEvent

Provides a complete snapshot of an agent’s state.

type StateSnapshotEvent = BaseEvent & {
  type: EventType.STATE_SNAPSHOT
  snapshot: any // StateSchema
}

Property	Type	Description
`snapshot`	`any`	Complete state snapshot

StateDeltaEvent

Provides a partial update to an agent’s state using JSON Patch.

type StateDeltaEvent = BaseEvent & {
  type: EventType.STATE_DELTA
  delta: any[] // JSON Patch operations (RFC 6902)
}

Property	Type	Description
`delta`	`any[]`	Array of JSON Patch operations

MessagesSnapshotEvent

Provides a snapshot of all messages in a conversation.

type MessagesSnapshotEvent = BaseEvent & {
  type: EventType.MESSAGES_SNAPSHOT
  messages: Message[]
}

Property	Type	Description
`messages`	`Message[]`	Array of message objects

ActivitySnapshotEvent

Delivers a complete snapshot of an activity message.

type ActivitySnapshotEvent = BaseEvent & {
  type: EventType.ACTIVITY_SNAPSHOT
  messageId: string
  activityType: string
  content: Record<string, any>
  replace?: boolean
}

Property	Type	Description
`messageId`	`string`	Identifier for the target `ActivityMessage`
`activityType`	`string`	Activity discriminator such as `"PLAN"` or `"SEARCH"`
`content`	`Record<string, any>`	Structured payload describing the full activity state
`replace`	`boolean` (optional)	Defaults to `true`; when `false` the snapshot is ignored if a message with the same ID already exists

ActivityDeltaEvent

Provides incremental updates to an activity snapshot using JSON Patch.

type ActivityDeltaEvent = BaseEvent & {
  type: EventType.ACTIVITY_DELTA
  messageId: string
  activityType: string
  patch: any[] // RFC 6902 JSON Patch operations
}

Property	Type	Description
`messageId`	`string`	Identifier for the target `ActivityMessage`
`activityType`	`string`	Activity discriminator mirroring the most recent snapshot
`patch`	`any[]`	JSON Patch operations applied to the structured activity payload

Reasoning Events

These events represent the lifecycle of reasoning/thinking processes within an agent. Reasoning events allow agents to expose their internal thought process to the frontend, creating ReasoningMessage objects that persist in the message history with the role "reasoning".

ReasoningStartEvent

Signals the start of a reasoning phase. This is a pass-through event that notifies subscribers but does not create messages.

type ReasoningStartEvent = BaseEvent & {
  type: EventType.REASONING_START
  messageId: string
}

Property	Type	Description
`messageId`	`string`	Identifier for the reasoning phase

ReasoningMessageStartEvent

Signals the start of a reasoning message. Creates a new ReasoningMessage in the message history.

type ReasoningMessageStartEvent = BaseEvent & {
  type: EventType.REASONING_MESSAGE_START
  messageId: string
  role: "reasoning"
}

Property	Type	Description
`messageId`	`string`	Unique identifier for the message
`role`	`"reasoning"`	Role is always “reasoning”

ReasoningMessageContentEvent

Represents a chunk of content in a streaming reasoning message.

type ReasoningMessageContentEvent = BaseEvent & {
  type: EventType.REASONING_MESSAGE_CONTENT
  messageId: string
  delta: string
}

Property	Type	Description
`messageId`	`string`	Matches the ID from ReasoningMessageStartEvent
`delta`	`string`	Reasoning content chunk

ReasoningMessageEndEvent

Signals the end of a reasoning message.

type ReasoningMessageEndEvent = BaseEvent & {
  type: EventType.REASONING_MESSAGE_END
  messageId: string
}

Property	Type	Description
`messageId`	`string`	Matches the ID from ReasoningMessageStartEvent

ReasoningMessageChunkEvent

Convenience event that expands to ReasoningMessageStart → ReasoningMessageContent → ReasoningMessageEnd automatically in the JS/TS client.

type ReasoningMessageChunkEvent = BaseEvent & {
  type: EventType.REASONING_MESSAGE_CHUNK
  messageId?: string // required on the first chunk for a message
  delta?: string
}

Behavior

Omit start/end: The client transforms chunk sequences into the standard start/content/end triad.
First chunk requirements: The first chunk for a message must include messageId.
Streaming: Subsequent chunks with the same messageId emit ReasoningMessageContent events. ReasoningMessageEnd is emitted automatically when a different message starts or when the stream completes.

ReasoningEndEvent

Signals the end of a reasoning phase. This is a pass-through event that notifies subscribers but does not modify messages.

type ReasoningEndEvent = BaseEvent & {
  type: EventType.REASONING_END
  messageId: string
}

Property	Type	Description
`messageId`	`string`	Identifier for the reasoning phase

ReasoningEncryptedValueEvent

Attaches an encrypted value to a message or tool call. When this event is emitted, it finds the referenced entity by entityId and sets its encryptedValue field.

type ReasoningEncryptedValueEvent = BaseEvent & {
  type: EventType.REASONING_ENCRYPTED_VALUE
  subtype: "tool-call" | "message"
  entityId: string
  encryptedValue: string
}

Property	Type	Description
`subtype`	`"tool-call" \| "message"`	The type of entity this value belongs to
`entityId`	`string`	ID of the tool call or message to attach the value
`encryptedValue`	`string`	The encrypted value to attach to the entity

Subagent Events

These events report that the agent delegated work to a child agent, so a frontend can attribute output to the subagent that produced it. Attribution itself travels as an optional subagentRunId on most other event types. subagentRunId identifies one invocation, not a reusable subagent definition — the same subagent run twice yields two different values. See Subagents for the full model.

SubagentStartedEvent

Announces a new subagent invocation and names it for display.

type SubagentStartedEvent = BaseEvent & {
  type: EventType.SUBAGENT_STARTED
  subagentRunId: string
  name: string
  description?: string
  parentSubagentRunId?: string
  parentToolCallId?: string
  parentMessageId?: string
}

Property	Type	Description
`subagentRunId`	`string`	Opaque identifier for this invocation
`name`	`string`	Declared subagent name or type, for display
`description`	`string`	Optional description
`parentSubagentRunId`	`string`	Optional enclosing subagent, when nesting
`parentToolCallId`	`string`	Optional tool call that spawned this subagent
`parentMessageId`	`string`	Optional message holding that tool call

SubagentFinishedEvent

Marks a subagent invocation as complete.

type SubagentFinishedEvent = BaseEvent & {
  type: EventType.SUBAGENT_FINISHED
  subagentRunId: string
  result?: any
  outcome?: { type: "success" } | { type: "suspended"; interruptIds?: string[] }
}

Property	Type	Description
`subagentRunId`	`string`	Matches the id from `SubagentStartedEvent`
`result`	`any`	Optional payload, mirroring `RunFinishedEvent.result`
`outcome`	`SubagentFinishedOutcome`	Optional discriminated union; omitted means success (the legacy reading). `{ type: "suspended", interruptIds?: string[] }` says the subagent is checkpointed awaiting outside input; `interruptIds` names the run-level interrupts whose answers resume it.

SubagentErrorEvent

Marks a subagent invocation as failed.

type SubagentErrorEvent = BaseEvent & {
  type: EventType.SUBAGENT_ERROR
  subagentRunId: string
  message: string
  code?: string
}

Property	Type	Description
`subagentRunId`	`string`	Matches the id from `SubagentStartedEvent`
`message`	`string`	Human-readable error message
`code`	`string`	Optional error code

Attribution on other events

Most event types accept an optional subagentRunId. An event without it belongs to the parent agent, so a stream that never sets the field behaves exactly as it did before subagents existed. RunStartedEvent, RunFinishedEvent and RunErrorEvent are not attributable — they describe the run as a whole. MessagesSnapshotEvent carries attribution per-message instead, since one snapshot mixes messages from several producers. StateSnapshotEvent and StateDeltaEvent are attributable, but attribution on them is provenance rather than ownership — it records which subagent produced the update. State stays run-scoped, so an attributed snapshot or delta is applied to the run’s one state document just as an unattributed one is. There is no per-subagent state. Subscribers can react to the lifecycle directly via onSubagentStartedEvent, onSubagentFinishedEvent and onSubagentErrorEvent.

Special Events

RawEvent

Used to pass through events from external systems.

type RawEvent = BaseEvent & {
  type: EventType.RAW
  event: any
  source?: string
}

Property	Type	Description
`event`	`any`	Original event data
`source`	`string` (optional)	Source of the event

CustomEvent

Used for application-specific custom events.

type CustomEvent = BaseEvent & {
  type: EventType.CUSTOM
  name: string
  value: any
}

Property	Type	Description
`name`	`string`	Name of the custom event
`value`	`any`	Value associated with the event

Deprecated Events

The THINKING_* events are deprecated and will be removed in version 1.0.0. New implementations should use REASONING_* events instead.

Thinking Events (Deprecated)

The following event types are deprecated:

Deprecated Event	Replacement
`THINKING_START`	`REASONING_START`
`THINKING_END`	`REASONING_END`
`THINKING_TEXT_MESSAGE_START`	`REASONING_MESSAGE_START`
`THINKING_TEXT_MESSAGE_CONTENT`	`REASONING_MESSAGE_CONTENT`
`THINKING_TEXT_MESSAGE_END`	`REASONING_MESSAGE_END`

See Reasoning Migration for detailed migration guidance.

Event Schemas

The SDK uses Zod schemas to validate events:

const EventSchemas = z.discriminatedUnion("type", [
  TextMessageStartEventSchema,
  TextMessageContentEventSchema,
  TextMessageEndEventSchema,
  ToolCallStartEventSchema,
  ToolCallArgsEventSchema,
  ToolCallEndEventSchema,
  ToolCallResultEventSchema,
  StateSnapshotEventSchema,
  StateDeltaEventSchema,
  MessagesSnapshotEventSchema,
  ActivitySnapshotEventSchema,
  ActivityDeltaEventSchema,
  RawEventSchema,
  CustomEventSchema,
  RunStartedEventSchema,
  RunFinishedEventSchema,
  RunErrorEventSchema,
  StepStartedEventSchema,
  StepFinishedEventSchema,
  ReasoningStartEventSchema,
  ReasoningMessageStartEventSchema,
  ReasoningMessageContentEventSchema,
  ReasoningMessageEndEventSchema,
  ReasoningMessageChunkEventSchema,
  ReasoningEndEventSchema,
  ReasoningEncryptedValueEventSchema,
])

This allows for runtime validation of events and provides TypeScript type inference.

ToolCallChunkEvent

Convenience event that expands to ToolCallStart → ToolCallArgs → ToolCallEnd automatically in the JS/TS client.

type ToolCallChunkEvent = BaseEvent & {
  type: EventType.TOOL_CALL_CHUNK
  toolCallId?: string // required on the first chunk for a tool call
  toolCallName?: string // required on the first chunk for a tool call
  parentMessageId?: string
  delta?: string
}

Behavior

Omit start/end: The client transforms chunk sequences into the standard start/args/end triad.
First chunk requirements: The first chunk must include both toolCallId and toolCallName; parentMessageId is propagated to ToolCallStart if given.
Streaming: Subsequent chunks with the same toolCallId emit ToolCallArgs. ToolCallEnd is emitted automatically when the tool call changes or when the stream completes.

​Events

​EventType Enum

​BaseEvent

​Lifecycle Events

​RunStartedEvent

​TokenUsage

​RunFinishedEvent

​RunErrorEvent

​StepStartedEvent

​StepFinishedEvent

​Text Message Events

​TextMessageStartEvent

​TextMessageContentEvent

​TextMessageEndEvent

​TextMessageChunkEvent

​Tool Call Events

​ToolCallStartEvent

​ToolCallArgsEvent

​ToolCallEndEvent

​ToolCallResultEvent

​State Management Events

​StateSnapshotEvent

​StateDeltaEvent

​MessagesSnapshotEvent

​ActivitySnapshotEvent

​ActivityDeltaEvent

​Reasoning Events

​ReasoningStartEvent

​ReasoningMessageStartEvent

​ReasoningMessageContentEvent

​ReasoningMessageEndEvent

​ReasoningMessageChunkEvent

​ReasoningEndEvent

​ReasoningEncryptedValueEvent

​Subagent Events

​SubagentStartedEvent

​SubagentFinishedEvent

​SubagentErrorEvent

​Attribution on other events

​Special Events

​RawEvent

​CustomEvent

​Deprecated Events

​Thinking Events (Deprecated)

​Event Schemas

​ToolCallChunkEvent

Events

EventType Enum

BaseEvent

Lifecycle Events

RunStartedEvent

TokenUsage

RunFinishedEvent

RunErrorEvent

StepStartedEvent

StepFinishedEvent

Text Message Events

TextMessageStartEvent

TextMessageContentEvent

TextMessageEndEvent

TextMessageChunkEvent

Tool Call Events

ToolCallStartEvent

ToolCallArgsEvent

ToolCallEndEvent

ToolCallResultEvent

State Management Events

StateSnapshotEvent

StateDeltaEvent

MessagesSnapshotEvent

ActivitySnapshotEvent

ActivityDeltaEvent

Reasoning Events

ReasoningStartEvent

ReasoningMessageStartEvent

ReasoningMessageContentEvent

ReasoningMessageEndEvent

ReasoningMessageChunkEvent

ReasoningEndEvent

ReasoningEncryptedValueEvent

Subagent Events

SubagentStartedEvent

SubagentFinishedEvent

SubagentErrorEvent

Attribution on other events

Special Events

RawEvent

CustomEvent

Deprecated Events

Thinking Events (Deprecated)

Event Schemas

ToolCallChunkEvent