Skip to main content

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, creating ReasoningMessage 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.
Behavior
  • 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_id correspond 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 optional subagent_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 optional subagent_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

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: 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:
This allows for runtime validation of events and type checking at development time.

TextMessageChunkEvent

Convenience event for complete text messages without manually emitting TextMessageStart/TextMessageEnd.
Behavior
  • 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_id correspond to content pieces; completion triggers an implied end in clients that perform expansion.

ToolCallChunkEvent

Convenience event for tool calls without manually emitting ToolCallStart/ToolCallEnd.
Behavior
  • 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_id and tool_call_name on the first chunk.
  • Streaming: Subsequent chunks with the same tool_call_id correspond to args pieces; completion triggers an implied end in clients that perform expansion.