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:
BaseEvent
from ag_ui.core import BaseEvent
All events inherit from the BaseEvent class, which provides common properties
shared across all event types.
metadata is open by key: any JSON value is allowed under a key, including
None. The object may be absent, but a present one is never None — an
explicit null is read back as absent, so a plain model_dump_json()
round-trips. EventEncoder uses exclude_none=True, so an absent object is
omitted from the wire rather than emitted as null. The ag-ui key is reserved
for AG-UI’s own use.
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.
TokenUsage
from ag_ui.core import TokenUsage
A reusable, numeric-only token usage summary carried on terminal run events.
It intentionally contains only provider/model labels and token counts — no
prompts, completions, messages, or identifiers. The counts follow the
protocol’s accounting: the input
and output counts are totals, and the cache and reasoning counts are parts of
them, never additions.
RunFinishedEvent
from ag_ui.core import RunFinishedEvent
Signals the successful completion of an agent run.
RunErrorEvent
from ag_ui.core import RunErrorEvent
Signals an error during an agent run.
StepStartedEvent
from ag_ui.core import StepStartedEvent
Signals the start of a step within an agent run.
StepFinishedEvent
from ag_ui.core import StepFinishedEvent
Signals the completion of a step within an agent run.
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.
TextMessageContentEvent
from ag_ui.core import TextMessageContentEvent
Represents a chunk of content in a streaming text message.
TextMessageEndEvent
from ag_ui.core import TextMessageEndEvent
Signals the end of a text message.
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.
ToolCallArgsEvent
from ag_ui.core import ToolCallArgsEvent
Represents a chunk of argument data for a tool call.
ToolCallEndEvent
from ag_ui.core import ToolCallEndEvent
Signals the end of a tool call.
ToolCallResultEvent
from ag_ui.core import ToolCallResultEvent
Provides the result of a tool call execution.
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.
StateDeltaEvent
from ag_ui.core import StateDeltaEvent
Provides a partial update to an agent’s state using JSON Patch.
MessagesSnapshotEvent
from ag_ui.core import MessagesSnapshotEvent
Provides a snapshot of all messages in a conversation.
ActivitySnapshotEvent
from ag_ui.core import ActivitySnapshotEvent
Delivers a complete snapshot of an activity message.
ActivityDeltaEvent
from ag_ui.core import ActivityDeltaEvent
Provides incremental updates to an activity snapshot using JSON Patch.
Special Events
RawEvent
from ag_ui.core import RawEvent
Used to pass through events from external systems.
CustomEvent
from ag_ui.core import CustomEvent
Used for application-specific custom events.
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, creatingReasoningMessage objects that persist in the message
history with the role "reasoning".
ReasoningStartEvent
from ag_ui.core import ReasoningStartEvent
Signals the start of a reasoning phase. This is a pass-through event that
notifies subscribers but does not create messages.
ReasoningMessageStartEvent
from ag_ui.core import ReasoningMessageStartEvent
Signals the start of a reasoning message. Creates a new ReasoningMessage in
the message history.
ReasoningMessageContentEvent
from ag_ui.core import ReasoningMessageContentEvent
Represents a chunk of content in a streaming reasoning message.
ReasoningMessageEndEvent
from ag_ui.core import ReasoningMessageEndEvent
Signals the end of a reasoning message.
ReasoningMessageChunkEvent
from ag_ui.core import ReasoningMessageChunkEvent
Convenience event for complete reasoning messages without manually emitting
ReasoningMessageStart/ReasoningMessageEnd.
- Convenience: Some consumers (e.g., the JS/TS client) expand chunk events into the standard start/content/end sequence automatically.
- First chunk requirements: The first chunk for a given message must include
message_id. - Streaming: Subsequent chunks with the same
message_idcorrespond to content pieces; completion triggers an implied end in clients that perform expansion.
ReasoningEndEvent
from ag_ui.core import ReasoningEndEvent
Signals the end of a reasoning phase. This is a pass-through event that notifies
subscribers but does not modify messages.
ReasoningEncryptedValueEvent
from ag_ui.core import ReasoningEncryptedValueEvent
Attaches an encrypted value to a message or tool call. When this event is
emitted, it finds the referenced entity by entity_id and sets its
encrypted_value field.
Subagent Events
These events report that the agent delegated work to a child agent, so a frontend can attribute output to the subagent that produced it. Attribution itself travels as an optionalsubagent_run_id on most other event types.
subagent_run_id identifies one invocation, not a reusable subagent
definition — the same subagent run twice yields two different values. See
Subagents for the full model.
Field names are snake_case in Python and serialize to camelCase on the wire, so
subagent_run_id appears as subagentRunId in JSON.
SubagentStartedEvent
from ag_ui.core import SubagentStartedEvent
Announces a new subagent invocation and names it for display.
SubagentFinishedEvent
from ag_ui.core import SubagentFinishedEvent
Marks a subagent invocation as complete.
SubagentErrorEvent
from ag_ui.core import SubagentErrorEvent
Marks a subagent invocation as failed.
Attribution on other events
Most event types accept an optionalsubagent_run_id. An event without it
belongs to the parent agent, so a stream that never sets the field behaves
exactly as it did before subagents existed.
RunStartedEvent, RunFinishedEvent and RunErrorEvent are not attributable —
they describe the run as a whole. MessagesSnapshotEvent carries attribution
per-message instead.
StateSnapshotEvent and StateDeltaEvent are attributable, but attribution on
them is provenance rather than ownership — it records which subagent produced the
update. State stays run-scoped, so an attributed snapshot or delta is applied to
the run’s one state document just as an unattributed one is.
Deprecated Events
Thinking Events (Deprecated)
The following event types are deprecated:
See Reasoning Migration
for detailed migration guidance.
Event Discrimination
from ag_ui.core import Event
The SDK uses Pydantic’s discriminated unions for event validation:
TextMessageChunkEvent
Convenience event for complete text messages without manually emittingTextMessageStart/TextMessageEnd.
- Convenience: Some consumers (e.g., the JS/TS client) expand chunk events into the standard start/content/end sequence automatically, allowing producers to omit explicit start/end events when using chunks.
- First chunk requirements: The first chunk for a given message must include
message_id. - Streaming: Subsequent chunks with the same
message_idcorrespond to content pieces; completion triggers an implied end in clients that perform expansion.
ToolCallChunkEvent
Convenience event for tool calls without manually emittingToolCallStart/ToolCallEnd.
- Convenience: Consumers may expand chunk sequences into the standard start/args/end triad (the JS/TS client does this automatically).
- First chunk requirements: Include both
tool_call_idandtool_call_nameon the first chunk. - Streaming: Subsequent chunks with the same
tool_call_idcorrespond to args pieces; completion triggers an implied end in clients that perform expansion.