Documentation for the events used in the Agent User Interaction Protocol SDK
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.
The EventType
enum defines all possible event types in the system:
All events inherit from the BaseEvent
type, which provides common properties
shared across all event types.
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 |
These events represent the lifecycle of an agent run.
Signals the start of an agent run.
Property | Type | Description |
---|---|---|
threadId | string | ID of the conversation thread |
runId | string | ID of the agent run |
Signals the successful completion of an agent run.
Property | Type | Description |
---|---|---|
threadId | string | ID of the conversation thread |
runId | string | ID of the agent run |
Signals an error during an agent run.
Property | Type | Description |
---|---|---|
message | string | Error message |
code | string (optional) | Error code |
Signals the start of a step within an agent run.
Property | Type | Description |
---|---|---|
stepName | string | Name of the step |
Signals the completion of a step within an agent run.
Property | Type | Description |
---|---|---|
stepName | string | Name of the step |
These events represent the lifecycle of text messages in a conversation.
Signals the start of a text message.
Property | Type | Description |
---|---|---|
messageId | string | Unique identifier for the message |
role | "assistant" | Role is always “assistant” |
Represents a chunk of content in a streaming text message.
Property | Type | Description |
---|---|---|
messageId | string | Matches the ID from TextMessageStartEvent |
delta | string | Text content chunk (non-empty) |
Signals the end of a text message.
Property | Type | Description |
---|---|---|
messageId | string | Matches the ID from TextMessageStartEvent |
These events represent the lifecycle of tool calls made by agents.
Signals the start of a tool call.
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 |
Represents a chunk of argument data for a tool call.
Property | Type | Description |
---|---|---|
toolCallId | string | Matches the ID from ToolCallStartEvent |
delta | string | Argument data chunk |
Signals the end of a tool call.
Property | Type | Description |
---|---|---|
toolCallId | string | Matches the ID from ToolCallStartEvent |
These events are used to manage agent state.
Provides a complete snapshot of an agent’s state.
Property | Type | Description |
---|---|---|
snapshot | any | Complete state snapshot |
Provides a partial update to an agent’s state using JSON Patch.
Property | Type | Description |
---|---|---|
delta | any[] | Array of JSON Patch operations |
Provides a snapshot of all messages in a conversation.
Property | Type | Description |
---|---|---|
messages | Message[] | Array of message objects |
Used to pass through events from external systems.
Property | Type | Description |
---|---|---|
event | any | Original event data |
source | string (optional) | Source of the event |
Used for application-specific custom events.
Property | Type | Description |
---|---|---|
name | string | Name of the custom event |
value | any | Value associated with the event |
The SDK uses Zod schemas to validate events:
This allows for runtime validation of events and provides TypeScript type inference.