Events
AG-UI uses a streaming event-based architecture. Events are the units of communication from an agent backend to a frontend UI. In .NET, every protocol event derives fromBaseEvent and has a type discriminator.
Event Type Constants
AGUIEventTypes defines the SCREAMING_SNAKE_CASE wire discriminators:
BaseEvent
All events inherit fromBaseEvent.
Metadata is open by key: any JSON value is allowed under a key, including
null. The object may be absent, but a present one is never null — an
explicit null is read back as absent, and an absent object is omitted from the
wire rather than serialized as null. AGUIMetadata.ReservedKey ("ag-ui") is
reserved for AG-UI’s own use.
Lifecycle Events
Lifecycle events represent the run and step lifecycle.RunStartedEvent
Signals the start of an agent run.RunFinishedEvent
Signals the completion of an agent run.RunFinishedOutcome is a polymorphic value with type: "success" or
type: "interrupt". RunFinishedInterruptOutcome carries interrupts, an
IList<AGUIInterrupt>.
Usage is described under TokenUsage.
RunErrorEvent
Signals an error during an agent run.TokenUsage
Provider-reported token usage, carried by both terminal run events. One entry per(provider, model) pair, so a run that invokes several models keeps them separate;
consumers that only need totals can sum across the entries.
Every field is optional. A null count means the provider did not report it, which is
distinct from a reported zero — so
usage never fabricates a count the provider
withheld. The type is numeric-only by design: it carries no prompts, completions,
messages, tool arguments, or thread/run/user identifiers.
When hosting with AGUI.Server, usage reported by Microsoft.Extensions.AI as
UsageContent is accumulated automatically and attached to the terminal event.
ModelId supplies the model label; set the provider label with
AGUIStreamOptions.WithUsageProvider("openai").
StepStartedEvent
Signals the start of a named step.StepFinishedEvent
Signals the completion of a named step.Text Message Events
Text message events stream assistant text as a start/content/end sequence.TextMessageStartEvent
TextMessageContentEvent
TextMessageEndEvent
Tool Call Events
Tool call events stream tool invocation arguments and optional server-side results.ToolCallStartEvent
ToolCallArgsEvent
ToolCallEndEvent
ToolCallResultEvent
State Management Events
State events synchronize frontend state and message history.StateSnapshotEvent
Provides a complete state snapshot.StateDeltaEvent
Provides incremental state changes, commonly as JSON Patch operations.MessagesSnapshotEvent
Replaces the frontend conversation history with the server’s view.Reasoning Events
Reasoning events expose a model or agent reasoning stream. They can create and updateAGUIReasoningMessage entries in message history.
ReasoningStartEvent
ReasoningMessageStartEvent
ReasoningMessageContentEvent
ReasoningMessageEndEvent
ReasoningMessageChunkEvent
Compact reasoning message chunk event with optional fields.ReasoningEndEvent
ReasoningEncryptedValueEvent
Attaches an encrypted value to a message or tool call.Activity Events
Activity events carry structured progress state for UI renderers.ActivitySnapshotEvent
ActivityDeltaEvent
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 optionalSubagentRunId on most other event types.
SubagentRunId identifies one invocation, not a reusable subagent
definition — the same subagent run twice yields two different values. See
Subagents for the full model.
SubagentStartedEvent
Announces a new subagent invocation and names it for display.SubagentFinishedEvent
Marks a subagent invocation as complete.SubagentErrorEvent
Marks a subagent invocation as failed.Attribution on other events
Most event types expose an optionalSubagentRunId. An event without it belongs
to the parent agent, so a stream that never sets it 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.
When events are converted to Microsoft.Extensions.AI types, attribution is
preserved on ChatMessage.AdditionalProperties under the key
agui.subagentRunId, since those types have no dedicated field for it.
Special Events
RawEvent
Passes through unprocessed external data.CustomEvent
Carries application-specific data.Serialization
BaseEvent uses a discriminator-based JSON converter keyed on the type field.
All concrete event types are registered in AGUIJsonSerializerContext.