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.

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.

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.

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.

3.5 Other Events

The specification reserves additional event types for extensibility.

Table 1 — AG-UI Event Categories and Event Types

Category

Event Types

Messaging

TEXT_MESSAGE_START, TEXT_MESSAGE_CONTENT, TEXT_MESSAGE_END

Tool

TOOL_CALL_START, TOOL_CALL_ARGS, TOOL_CALL_RESULT, TOOL_CALL_END

State

STATE_SNAPSHOT, STATE_DELTA, MESSAGES_SNAPSHOT

Lifecycle

RUN_STARTED, RUN_FINISHED, RUN_ERROR, STEP_STARTED, STEP_FINISHED

Other

RAW, CUSTOM

4. Detailed Event Semantics and Payload Structures

This section defines each AG-UI event type. All events derive from BaseEvent, which defines:

4.1 Messaging Events

TEXT_MESSAGE_START

{
  "type": "TEXT_MESSAGE_START",
  "message_id": "string",
  "role": "assistant"
}

TEXT_MESSAGE_CONTENT

{
  "type": "TEXT_MESSAGE_CONTENT",
  "message_id": "string",
  "delta": "non-empty string"
}

TEXT_MESSAGE_END

{
  "type": "TEXT_MESSAGE_END",
  "message_id": "string"
}

4.2 Tool Events

TOOL_CALL_START

{
  "type": "TOOL_CALL_START",
  "tool_call_id": "string",
  "tool_call_name": "string",
  "parent_message_id": "string (optional)"
}

TOOL_CALL_ARGS

{
  "type": "TOOL_CALL_ARGS",
  "tool_call_id": "string",
  "delta": "string"
}

TOOL_CALL_RESULT (commonly TOOL_CALL_END in some places)

{
  "type": "TOOL_CALL_RESULT",
  "tool_call_id": "string",
  "result": "any"
}

TOOL_CALL_END

{
  "type": "TOOL_CALL_END",
  "tool_call_id": "string"
}

4.3 State Events

STATE_SNAPSHOT

{
  "type": "STATE_SNAPSHOT",
  "snapshot": { /* State object */ }
}

STATE_DELTA

{
  "type": "STATE_DELTA",
  "delta": [ /* JSON Patch array */ ]
}

MESSAGES_SNAPSHOT

{
  "type": "MESSAGES_SNAPSHOT",
  "messages": [ /* Array of message objects */ ]
}

4.4 Lifecycle Events

RUN_STARTED

{
  "type": "RUN_STARTED",
  "thread_id": "string",
  "run_id": "string"
}

RUN_FINISHED

{
  "type": "RUN_FINISHED",
  "thread_id": "string",
  "run_id": "string",
  "result": "any (optional)"
}

RUN_ERROR

{
  "type": "RUN_ERROR",
  "message": "string",
  "code": "string (optional)"
}

STEP_STARTED

{
  "type": "STEP_STARTED",
  "step_name": "string"
}

STEP_FINISHED

{
  "type": "STEP_FINISHED",
  "step_name": "string"
}

4.5 Other Events

RAW

{
  "type": "RAW",
  "event": "any",
  "source": "string (optional)"
}

CUSTOM

{
  "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.