​
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",
  RAW = "RAW",
  CUSTOM = "CUSTOM",
  RUN_STARTED = "RUN_STARTED",
  RUN_FINISHED = "RUN_FINISHED",
  RUN_ERROR = "RUN_ERROR",
  STEP_STARTED = "STEP_STARTED",
  STEP_FINISHED = "STEP_FINISHED",
}

​
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
}
PropertyTypeDescription
typeEventTypeThe type of event (discriminator field for the union)
timestampnumber (optional)Timestamp when the event was created
rawEventany (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
}
PropertyTypeDescription
threadIdstringID of the conversation thread
runIdstringID of the agent run

​
RunFinishedEvent

Signals the successful completion of an agent run. 
type RunFinishedEvent = BaseEvent & {
  type: EventType.RUN_FINISHED
  threadId: string
  runId: string
  result?: any
}
PropertyTypeDescription
threadIdstringID of the conversation thread
runIdstringID of the agent run
resultany (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
}
PropertyTypeDescription
messagestringError message
codestring (optional)Error code

​
StepStartedEvent

Signals the start of a step within an agent run. 
type StepStartedEvent = BaseEvent & {
  type: EventType.STEP_STARTED
  stepName: string
}
PropertyTypeDescription
stepNamestringName of the step

​
StepFinishedEvent

Signals the completion of a step within an agent run. 
type StepFinishedEvent = BaseEvent & {
  type: EventType.STEP_FINISHED
  stepName: string
}
PropertyTypeDescription
stepNamestringName 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"
}
PropertyTypeDescription
messageIdstringUnique 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
}
PropertyTypeDescription
messageIdstringMatches the ID from TextMessageStartEvent
deltastringText content chunk (non-empty)

​
TextMessageEndEvent

Signals the end of a text message. 
type TextMessageEndEvent = BaseEvent & {
  type: EventType.TEXT_MESSAGE_END
  messageId: string
}
PropertyTypeDescription
messageIdstringMatches the ID from TextMessageStartEvent

​
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
}
PropertyTypeDescription
toolCallIdstringUnique identifier for the tool call
toolCallNamestringName of the tool being called
parentMessageIdstring (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
}
PropertyTypeDescription
toolCallIdstringMatches the ID from ToolCallStartEvent
deltastringArgument data chunk

​
ToolCallEndEvent

Signals the end of a tool call. 
type ToolCallEndEvent = BaseEvent & {
  type: EventType.TOOL_CALL_END
  toolCallId: string
}
PropertyTypeDescription
toolCallIdstringMatches 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"
}
PropertyTypeDescription
messageIdstringID of the conversation message this result belongs to
toolCallIdstringMatches the ID from the corresponding ToolCallStartEvent
contentstringThe 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
}
PropertyTypeDescription
snapshotanyComplete 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)
}
PropertyTypeDescription
deltaany[]Array of JSON Patch operations

​
MessagesSnapshotEvent

Provides a snapshot of all messages in a conversation. 
type MessagesSnapshotEvent = BaseEvent & {
  type: EventType.MESSAGES_SNAPSHOT
  messages: Message[]
}
PropertyTypeDescription
messagesMessage[]Array of message objects

​
Special Events

​
RawEvent

Used to pass through events from external systems. 
type RawEvent = BaseEvent & {
  type: EventType.RAW
  event: any
  source?: string
}
PropertyTypeDescription
eventanyOriginal event data
sourcestring (optional)Source of the event

​
CustomEvent

Used for application-specific custom events. 
type CustomEvent = BaseEvent & {
  type: EventType.CUSTOM
  name: string
  value: any
}
PropertyTypeDescription
namestringName of the custom event
valueanyValue associated with the event

​
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,
  RawEventSchema,
  CustomEventSchema,
  RunStartedEventSchema,
  RunFinishedEventSchema,
  RunErrorEventSchema,
  StepStartedEventSchema,
  StepFinishedEventSchema,
])
This allows for runtime validation of events and provides TypeScript type inference.