Upgrading from 0.0.x? See the 0.1.0 migration guide — schemas moved to a new subpath and zod is now an optional peer dependency.

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

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 validation

@ag-ui/core ships TypeScript types for every event but does not bundle a runtime schema validator in its main entry. The zod schemas live on an opt-in subpath:

import { EventSchemas } from "@ag-ui/core/schemas";

const result = EventSchemas.safeParse(incoming);
if (result.success) {
  // result.data is typed as the discriminated AGUIEvent union
} else {
  console.error(result.error);
}

zod is an optional peer dependency of @ag-ui/core/schemas. Install it explicitly if you import from this module:

npm install zod
# or pnpm/yarn — zod 3.25.18+ and all of zod 4 are supported

If you’d rather use a different validation library, define your own schemas locally using your library of choice. The TypeScript types from @ag-ui/core are the contract.

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

​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

​Special Events

​RawEvent

​CustomEvent

​Deprecated Events

​Thinking Events (Deprecated)

​Event validation

​ToolCallChunkEvent

Events

EventType Enum

BaseEvent

Lifecycle Events

RunStartedEvent

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

Special Events

RawEvent

CustomEvent

Deprecated Events

Thinking Events (Deprecated)

Event validation

ToolCallChunkEvent