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

Warning

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.