Events ↗

ag-ui guide intermediate agents architecture

Summary: Documentation for the events used in the Agent User Interaction Protocol SDK

Original Documentation

Documentation Index#
Fetch the complete documentation index at: https://docs.ag-ui.com/llms.txt Use this file to discover all available pages before exploring further.

Documentation for the events used in the Agent User Interaction Protocol SDK

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",
}

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
}

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

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

RunFinishedEvent#

Signals the successful completion of an agent run.

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

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

RunErrorEvent#

Signals an error during an agent run.

type RunErrorEvent = BaseEvent & {
  type: EventType.RUN_ERROR
  message: string
  code?: string
}

Property	Type	Description
`message`	`string`	Error message
`code`	`string` (optional)	Error code

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: "assistant"
}

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

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

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.

Link last verified June 7, 2026. View original ↗

Source: AG-UI Protocol

Link last verified: 2026-02-26