The Agent–User Interaction Protocol (AG-UI) defines a standardized, event-based method for communication between intelligent agents and user interfaces. The protocol specifies a set of sixteen events that enable reliable streaming of content, tool invocation, state synchronization, and lifecycle management. This article enumerates these events, classifies them into functional groups, and explains their role in building AG-UI compliant applications. The discussion is intended to provide a clear reference for practitioners who implement real-time, agent-driven user interfaces.
1 Introduction
Intelligent agents increasingly form the basis of interactive applications in domains such as software development, healthcare, customer support, and education. These systems must provide responses to user inputs with low latency while maintaining transparency of intermediate computations. Conventional client–server communication models, which transmit outputs only upon task completion, are insufficient to support this requirement. Instead, a standardized event-driven model is necessary to enable streaming of partial outputs, synchronization of system state, invocation of external tools, and accurate error reporting.
The Agent–User Interaction Protocol (AG-UI) has been proposed to address this gap. AG-UI specifies a set of events that define how agents communicate with user interfaces. Each event is atomic and semantically unambiguous, enabling deterministic handling by clients. The protocol is transport-agnostic, allowing events to be transmitted using Server-Sent Events (SSE), WebSockets, or other mechanisms. By relying on a fixed set of events, AG-UI ensures interoperability across frameworks and reduces the need for application-specific communication logic.
The protocol defines sixteen distinct events, which can be classified into four categories: (1) messaging events, which govern the delivery of text-based content; (2) tool events, which handle agent-initiated tool invocation and results; (3) state management events, which synchronize application state between agent and interface; and (4) lifecycle and control events, which manage execution boundaries and error conditions. Together, these events provide a complete foundation for building interactive, real-time agent applications.
The objective of this article is to describe these sixteen events in a structured manner. Each event will be defined, its role explained, and its relationship to other events identified. A typical execution flow will also be presented to illustrate how the events interact in practice. Finally, recommendations for implementation are provided to support robust and efficient deployment of AG-UI applications.
2. Background
Event-driven communication is a well-established model in distributed systems. In this model, a sender emits discrete events that a receiver processes in real time. Unlike request–response models, event-driven communication supports asynchronous interaction and incremental delivery of information. These properties make it suitable for intelligent agents, which often generate outputs progressively, invoke external tools, and modify internal state during execution.
Several protocols address related aspects of agent communication. The Model Context Protocol (MCP) defines a framework for connecting agents with external tools and services. The Agent-to-Agent Protocol (A2A) specifies communication between multiple agents in cooperative or competitive environments. In contrast, the Agent–User Interaction Protocol (AG-UI) focuses specifically on the interface between agents and end users. It complements, rather than replaces, these other protocols by addressing the unique requirements of human–agent interaction.
The role of AG-UI is to standardize how events are structured and transmitted between agents and user interfaces. This standardization reduces fragmentation and allows user interface frameworks, agent frameworks, and middleware systems to interoperate without custom adapters. In practice, AG-UI events can be transmitted over a variety of transport layers, including Server-Sent Events (SSE), WebSockets, or HTTP long polling. The choice of transport is implementation-dependent and does not affect event semantics.
The following sections classify and describe the sixteen events defined by AG-UI. These events represent the minimal set required to cover messaging, tool usage, state synchronization, and execution lifecycle. By conforming to this model, applications can achieve predictable and consistent user interaction behavior regardless of the underlying agent implementation.
3. Event Categories
The AG-UI protocol defines a set of discrete event types. Each event is delivered as a JSON object conforming to the BaseEvent schema, extended with event-specific fields. The event taxonomy is divided into five categories: Messaging, Tool, State, Lifecycle, and Other. This section provides a structured classification of these categories.
3.1 Messaging Events
Messaging events represent the incremental transmission of text output from the agent. They enable real-time rendering of assistant responses and maintain consistency in multi-turn dialogue.
- TEXT_MESSAGE_START: Indicates the beginning of a new assistant message. Includes identifiers such as
messageIdandrole. - TEXT_MESSAGE_CONTENT: Contains a fragment of textual content associated with the active message. Multiple events of this type may occur for a single message.
- TEXT_MESSAGE_END: Signals completion of the message. May contain status indicators confirming that no further content will follow.
3.2 Tool Events
Tool events describe the invocation and execution of external functions or APIs that augment the agent’s capabilities. They provide a structured mechanism for communicating inputs and outputs between the agent and an external system.
- TOOL_CALL_START: Marks the beginning of a tool call.
- TOOL_CALL_ARGS: Transmits the arguments for the tool call.
- TOOL_CALL_RESULT: Returns the structured result from the tool execution.
- TOOL_CALL_END: Concludes the tool call, reporting success or failure.
3.3 State Events
State events maintain synchronization between the agent runtime and the user interface. They enable restoration, update, and inspection of the active conversation state.
- STATE_SNAPSHOT: Represents a full serialization of the current application state.
- STATE_DELTA: Encodes incremental changes applied to an existing snapshot.
- MESSAGES_SNAPSHOT: Provides a bulk representation of accumulated message objects for resynchronization.
3.4 Lifecycle Events
Lifecycle events describe the execution status of a reasoning run and its intermediate steps. These events are essential for tracking progress, detecting errors, and coordinating multiple agent invocations.
- RUN_STARTED: Indicates the start of a new agent run, identified by
runIdandthreadId. - RUN_FINISHED: Marks successful completion of a run, optionally including a result payload.
- RUN_ERROR: Reports an error condition encountered during a run. Includes an error code and descriptive message.
- STEP_STARTED: Identifies the beginning of a reasoning step within the run.
- STEP_FINISHED: Marks completion of a reasoning step.
3.5 Other Events
The specification reserves additional event types for extensibility.
- RAW: Encapsulates an unmodified upstream event payload. This enables applications to consume events not yet formally mapped into AG-UI structures.
- CUSTOM: Supports vendor-defined or application-specific event types. Custom events must be namespaced to prevent collisions with reserved identifiers.
Table 1 — AG-UI Event Categories and Event Types
|
Category |
Event Types |
|---|---|
|
Messaging |
|
|
Tool |
|
|
State |
|
|
Lifecycle |
|
|
Other |
|
4. Detailed Event Semantics and Payload Structures
This section defines each AG-UI event type. All events derive from BaseEvent, which defines:
- type: EventType discriminator.
- timestamp?: Optional numeric timestamp.
- rawEvent?: Optional raw payload retained post-transformation.
4.1 Messaging Events
TEXT_MESSAGE_START
- Purpose: Signals commencement of a new assistant-generated message.
- Payload:
{
"type": "TEXT_MESSAGE_START",
"message_id": "string",
"role": "assistant"
}
- Notes:
Therolefield is always"assistant". Clients allocate buffers or render placeholders upon receipt.
TEXT_MESSAGE_CONTENT
- Purpose: Delivers a streaming fragment of text.
- Payload:
{
"type": "TEXT_MESSAGE_CONTENT",
"message_id": "string",
"delta": "non-empty string"
}
- Notes:
Thedeltafield must be non-empty; enforced by SDK validation. Clients concatenate in order.
TEXT_MESSAGE_END
- Purpose: Indicates message completion.
- Payload:
{
"type": "TEXT_MESSAGE_END",
"message_id": "string"
}
- Notes:
Marks the end of content fragments for the identified message.
4.2 Tool Events
TOOL_CALL_START
- Purpose: Initiates a tool invocation by the agent.
- Payload:
{
"type": "TOOL_CALL_START",
"tool_call_id": "string",
"tool_call_name": "string",
"parent_message_id": "string (optional)"
}
- Notes:
The optionalparent_message_idlinks the tool call to its triggering message.
TOOL_CALL_ARGS
- Purpose: Streams argument data for the tool call.
- Payload:
{
"type": "TOOL_CALL_ARGS",
"tool_call_id": "string",
"delta": "string"
}
- Notes:
Supports streaming large argument payloads using incrementaldeltachunks.
TOOL_CALL_RESULT (commonly TOOL_CALL_END in some places)
- Purpose: Returns the tool output result.
- Payload:
{
"type": "TOOL_CALL_RESULT",
"tool_call_id": "string",
"result": "any"
}
- Notes:
Some SDKs may combine result and end semantics; the spec standardizes this combined form.
TOOL_CALL_END
- Purpose: Terminates the tool call sequence.
- Payload:
{
"type": "TOOL_CALL_END",
"tool_call_id": "string"
}
- Notes:
Finalizes the invocation lifecycle.
4.3 State Events
STATE_SNAPSHOT
- Purpose: Provides a complete agent-side state snapshot.
- Payload:
{
"type": "STATE_SNAPSHOT",
"snapshot": { /* State object */ }
}
- Notes:
Clients should use this to fully replace existing state.
STATE_DELTA
- Purpose: Applies partial state updates using JSON Patch (RFC 6902).
- Payload:
{
"type": "STATE_DELTA",
"delta": [ /* JSON Patch array */ ]
}
- Notes:
Clients should apply patches in sequence for correct synchronization.
MESSAGES_SNAPSHOT
- Purpose: Synchronizes full message history.
- Payload:
{
"type": "MESSAGES_SNAPSHOT",
"messages": [ /* Array of message objects */ ]
}
- Notes:
Useful for initializing or recovering conversation context.
4.4 Lifecycle Events
RUN_STARTED
- Purpose: Marks the beginning of a new agent execution run.
- Payload:
{
"type": "RUN_STARTED",
"thread_id": "string",
"run_id": "string"
}
- Notes:
Clients may initialize run-specific state at this point.
RUN_FINISHED
- Purpose: Indicates successful completion of the run.
- Payload:
{
"type": "RUN_FINISHED",
"thread_id": "string",
"run_id": "string",
"result": "any (optional)"
}
- Notes:
May include final output or metadata.
RUN_ERROR
- Purpose: Reports an error encountered during the run.
- Payload:
{
"type": "RUN_ERROR",
"message": "string",
"code": "string (optional)"
}
- Notes:
Clients should execute error handling upon receipt.
STEP_STARTED
- Purpose: Marks the start of an internal reasoning or processing step.
- Payload:
{
"type": "STEP_STARTED",
"step_name": "string"
}
- Notes:
Enables detailed run instrumentation.
STEP_FINISHED
- Purpose: Indicates completion of an internal step.
- Payload:
{
"type": "STEP_FINISHED",
"step_name": "string"
}
- Notes:
Useful for monitoring and performance metrics.
4.5 Other Events
RAW
- Purpose: Forwards unmodified upstream event data.
- Payload:
{
"type": "RAW",
"event": "any",
"source": "string (optional)"
}
- Notes:
Maintains compatibility with non-AG-UI events.
CUSTOM
- Purpose: Conveys application-specific or vendor-defined events.
- Payload:
{
"type": "CUSTOM",
"name": "string",
"value": "any"
}
Notes:
Must be namespaced to avoid conflicts with standard types.
5. Example Use Cases and Message Sequences
This section describes three representative application scenarios for AG-UI event flows. Each use case is small and limited in scope. Message exchanges are shown as sequence diagrams.
5.1 Use Case 1: Greeting Exchange
Description:
The user greets the agent. The agent replies with a short message, “Hello, how can I help you?”.
Sequence:
Client Agent
| |
|------ USER: "Hello" ---------->|
| |
|<--- TEXT_MESSAGE_START --------|
|<--- TEXT_MESSAGE_CONTENT: "Hello, how can I help you?"
|<--- TEXT_MESSAGE_END ----------|
| |
5.2 Use Case 2: Weather Lookup
Description:
The user asks for the weather in Paris. The agent calls a weather tool, receives the result, and returns the text response.
Sequence:
Client Agent
| |
|-- USER: "What is weather in Paris?" ------->|
| |
|<--- TOOL_CALL_START (id=1, name="weather")--|
|<--- TOOL_CALL_ARGS ({"location": "Paris"})--|
|<--- TOOL_CALL_END (id=1) -------------------|
| |
|<--- TEXT_MESSAGE_START ---------------------|
|<--- TEXT_MESSAGE_CONTENT: "It is 25°C and sunny in Paris."
|<--- TEXT_MESSAGE_END -----------------------|
|. |
5.3 Use Case 3: Shopping Cart Recovery After Reconnect
Description:
A user is interacting with an e-commerce assistant. The client loses connection while the user is adding items to a shopping cart. After reconnection, the client requests synchronization (not explicitly, not a logic in AG-UI). The agent responds with the current application state (cart contents) and the conversation history.
Sequence:
Client Agent
| |
|------------ RECONNECTS -------------->|
| |
|<--- STATE_SNAPSHOT -------------------|
| { |
| "cart": [ |
| {"item": "Laptop", "qty": 1},
| {"item": "Mouse", "qty": 2}
| ] |
| } |
| |
|<--- MESSAGES_SNAPSHOT ----------------|
| [ |
| {"id": "m1", "role": "user", "content": "Add laptop to my cart"},
| {"id": "m2", "role": "assistant", "content": "Laptop added."},
| {"id": "m3", "role": "user", "content": "Add two mice"}
| ] |
| |
5.4 Use Case 4: Flight Booking Query with Tool Integration
Description:
The user asks the assistant to “Book me a flight from New York to Paris tomorrow.” The agent starts a run, performs a step that calls a flight search tool, receives the results, and then returns a text response.
Sequence:
Client Agent
| |
|-- USER: "Book flight from NY to Paris" -->|
| |
|<--- RUN_STARTED --------------------------|
| { "runId": "r1", "threadId": "t1" } |
| |
|<--- STEP_STARTED -------------------------|
| { "stepId": "s1", "runId": "r1" } |
| |
|<--- TOOL_CALL_START ----------------------|
| { "toolCallId": "tc1", "name": "searchFlights" }
| |
|<--- TOOL_CALL_ARGS -----------------------|
| { "from": "New York", "to": "Paris", "date": "2025-08-26" }
| |
|<--- TOOL_CALL_RESULT ---------------------|
| { "flights": [ |
| {"airline": "Air France", "price": 850}, |
| {"airline": "Delta", "price": 820} |
| ] } |
| |
|<--- TOOL_CALL_END ------------------------|
| { "toolCallId": "tc1" } |
| |
|<--- STEP_FINISHED ------------------------|
| { "stepId": "s1" } |
| |
|<--- TEXT_MESSAGE_START -------------------|
| { "messageId": "m1", "role": "assistant" }
|<--- TEXT_MESSAGE_CONTENT -----------------|
| "I found flights from New York to Paris. Delta: $820, Air France: $850."
|<--- TEXT_MESSAGE_END ---------------------|
| |
|<--- RUN_FINISHED -------------------------|
| { "runId": "r1" } |
| |
6. Conclusion
The AG-UI event protocol defines a compact and systematic framework for real-time interaction between agents and user interfaces. Sixteen core events establish the primitives for managing runs, steps, tool calls, state synchronization, and message exchange. By composing these events, developers can construct applications that support incremental reasoning, tool integration, and resilient client recovery.
This article has described the classification of AG-UI events, presented representative payload structures, and demonstrated message flows across multiple use cases. The examples illustrate how event sequences map directly onto practical application scenarios, ranging from simple message exchange to multi-step tool invocation.
Future development of AG-UI applications requires adherence to the event semantics, careful handling of state recovery, and consistent use of structured payloads. The standardization of these interaction patterns enables portability across implementations and facilitates predictable behavior in heterogeneous environments.