Skip to main content

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 from BaseEvent and has a type discriminator.

Event Type Constants

AGUIEventTypes defines the SCREAMING_SNAKE_CASE wire discriminators:

BaseEvent

All events inherit from BaseEvent.
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 update AGUIReasoningMessage 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 optional SubagentRunId 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 optional SubagentRunId. 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.