Events

The Agent User Interaction Protocol Python 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

from ag_ui.core import EventType The EventType enum defines all possible event types in the system:

class EventType(str, Enum):
    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"
    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

from ag_ui.core import BaseEvent All events inherit from the BaseEvent class, which provides common properties shared across all event types.

class BaseEvent(ConfiguredBaseModel):
    type: EventType
    timestamp: Optional[int] = None
    raw_event: Optional[Any] = None

Property	Type	Description
`type`	`EventType`	The type of event (discriminator field for the union)
`timestamp`	`Optional[int]`	Timestamp when the event was created
`raw_event`	`Optional[Any]`	Original event data if this event was transformed

Lifecycle Events

These events represent the lifecycle of an agent run.

RunStartedEvent

from ag_ui.core import RunStartedEvent Signals the start of an agent run.

class RunStartedEvent(BaseEvent):
    type: Literal[EventType.RUN_STARTED]
    thread_id: str
    run_id: str

Property	Type	Description
`thread_id`	`str`	ID of the conversation thread
`run_id`	`str`	ID of the agent run

RunFinishedEvent

from ag_ui.core import RunFinishedEvent Signals the successful completion of an agent run.

class RunFinishedEvent(BaseEvent):
    type: Literal[EventType.RUN_FINISHED]
    thread_id: str
    run_id: str

Property	Type	Description
`thread_id`	`str`	ID of the conversation thread
`run_id`	`str`	ID of the agent run

RunErrorEvent

from ag_ui.core import RunErrorEvent Signals an error during an agent run.

class RunErrorEvent(BaseEvent):
    type: Literal[EventType.RUN_ERROR]
    message: str
    code: Optional[str] = None

Property	Type	Description
`message`	`str`	Error message
`code`	`Optional[str]`	Error code

StepStartedEvent

from ag_ui.core import StepStartedEvent Signals the start of a step within an agent run.

class StepStartedEvent(BaseEvent):
    type: Literal[EventType.STEP_STARTED]
    step_name: str

Property	Type	Description
`step_name`	`str`	Name of the step

StepFinishedEvent

from ag_ui.core import StepFinishedEvent Signals the completion of a step within an agent run.

class StepFinishedEvent(BaseEvent):
    type: Literal[EventType.STEP_FINISHED]
    step_name: str

Property	Type	Description
`step_name`	`str`	Name of the step

Text Message Events

These events represent the lifecycle of text messages in a conversation.

TextMessageStartEvent

from ag_ui.core import TextMessageStartEvent Signals the start of a text message.

class TextMessageStartEvent(BaseEvent):
    type: Literal[EventType.TEXT_MESSAGE_START]
    message_id: str
    role: Literal["assistant"]

Property	Type	Description
`message_id`	`str`	Unique identifier for the message
`role`	`Literal["assistant"]`	Role is always “assistant”

TextMessageContentEvent

from ag_ui.core import TextMessageContentEvent Represents a chunk of content in a streaming text message.

class TextMessageContentEvent(BaseEvent):
    type: Literal[EventType.TEXT_MESSAGE_CONTENT]
    message_id: str
    delta: str  # Non-empty string

    def model_post_init(self, __context):
        if len(self.delta) == 0:
            raise ValueError("Delta must not be an empty string")

Property	Type	Description
`message_id`	`str`	Matches the ID from TextMessageStartEvent
`delta`	`str`	Text content chunk (non-empty)

TextMessageEndEvent

from ag_ui.core import TextMessageEndEvent Signals the end of a text message.

class TextMessageEndEvent(BaseEvent):
    type: Literal[EventType.TEXT_MESSAGE_END]
    message_id: str

Property	Type	Description
`message_id`	`str`	Matches the ID from TextMessageStartEvent

Tool Call Events

These events represent the lifecycle of tool calls made by agents.

ToolCallStartEvent

from ag_ui.core import ToolCallStartEvent Signals the start of a tool call.

class ToolCallStartEvent(BaseEvent):
    type: Literal[EventType.TOOL_CALL_START]
    tool_call_id: str
    tool_call_name: str
    parent_message_id: Optional[str] = None

Property	Type	Description
`tool_call_id`	`str`	Unique identifier for the tool call
`tool_call_name`	`str`	Name of the tool being called
`parent_message_id`	`Optional[str]`	ID of the parent message

ToolCallArgsEvent

from ag_ui.core import ToolCallArgsEvent Represents a chunk of argument data for a tool call.

class ToolCallArgsEvent(BaseEvent):
    type: Literal[EventType.TOOL_CALL_ARGS]
    tool_call_id: str
    delta: str

Property	Type	Description
`tool_call_id`	`str`	Matches the ID from ToolCallStartEvent
`delta`	`str`	Argument data chunk

ToolCallEndEvent

from ag_ui.core import ToolCallEndEvent Signals the end of a tool call.

class ToolCallEndEvent(BaseEvent):
    type: Literal[EventType.TOOL_CALL_END]
    tool_call_id: str

Property	Type	Description
`tool_call_id`	`str`	Matches the ID from ToolCallStartEvent

State Management Events

These events are used to manage agent state.

StateSnapshotEvent

from ag_ui.core import StateSnapshotEvent Provides a complete snapshot of an agent’s state.

class StateSnapshotEvent(BaseEvent):
    type: Literal[EventType.STATE_SNAPSHOT]
    snapshot: State

Property	Type	Description
`snapshot`	`State`	Complete state snapshot

StateDeltaEvent

from ag_ui.core import StateDeltaEvent Provides a partial update to an agent’s state using JSON Patch.

class StateDeltaEvent(BaseEvent):
    type: Literal[EventType.STATE_DELTA]
    delta: List[Any]  # JSON Patch (RFC 6902)

Property	Type	Description
`delta`	`List[Any]`	Array of JSON Patch operations

MessagesSnapshotEvent

from ag_ui.core import MessagesSnapshotEvent Provides a snapshot of all messages in a conversation.

class MessagesSnapshotEvent(BaseEvent):
    type: Literal[EventType.MESSAGES_SNAPSHOT]
    messages: List[Message]

Property	Type	Description
`messages`	`List[Message]`	Array of message objects

Special Events

RawEvent

from ag_ui.core import RawEvent Used to pass through events from external systems.

class RawEvent(BaseEvent):
    type: Literal[EventType.RAW]
    event: Any
    source: Optional[str] = None

Property	Type	Description
`event`	`Any`	Original event data
`source`	`Optional[str]`	Source of the event

CustomEvent

from ag_ui.core import CustomEvent Used for application-specific custom events.

class CustomEvent(BaseEvent):
    type: Literal[EventType.CUSTOM]
    name: str
    value: Any

Property	Type	Description
`name`	`str`	Name of the custom event
`value`	`Any`	Value associated with the event

Event Discrimination

from ag_ui.core import Event The SDK uses Pydantic’s discriminated unions for event validation:

Event = Annotated[
    Union[
        TextMessageStartEvent,
        TextMessageContentEvent,
        TextMessageEndEvent,
        ToolCallStartEvent,
        ToolCallArgsEvent,
        ToolCallEndEvent,
        StateSnapshotEvent,
        StateDeltaEvent,
        MessagesSnapshotEvent,
        RawEvent,
        CustomEvent,
        RunStartedEvent,
        RunFinishedEvent,
        RunErrorEvent,
        StepStartedEvent,
        StepFinishedEvent,
    ],
    Field(discriminator="type")
]

This allows for runtime validation of events and type checking at development time.

​Events

​EventType Enum

​BaseEvent

​Lifecycle Events

​RunStartedEvent

​RunFinishedEvent

​RunErrorEvent

​StepStartedEvent

​StepFinishedEvent

​Text Message Events

​TextMessageStartEvent

​TextMessageContentEvent

​TextMessageEndEvent

​Tool Call Events

​ToolCallStartEvent

​ToolCallArgsEvent

​ToolCallEndEvent

​State Management Events

​StateSnapshotEvent

​StateDeltaEvent

​MessagesSnapshotEvent

​Special Events

​RawEvent

​CustomEvent

​Event Discrimination