Agui Development

AG-UI Protocol Events Reference

Quick-reference for the AG-UI (Agent-User Interaction) protocol streaming events.

When to Use This Skill

• Building a frontend that consumes streaming agent responses
• Implementing a backend endpoint that serves AG-UI events
• Debugging event ordering or missing events in streaming flows
• Understanding the event lifecycle for tool calls, text messages, or reasoning

Dependencies

See "Verified against" below for exact versions this skill was checked against.

Official References

Verified against: ag-ui-protocol (Python) v0.1.19 — latest on PyPI as of 2026-08-02, released 2026-06-02, requires-python >=3.9, pydantic>=2.11.2 — and @ag-ui/core (TS) v0.0.57, latest on npm as of 2026-08-02. (Newer GitHub releases exist but are for adjacent framework-integration packages — CrewAI, Mastra, Strands, .NET clients — not the core protocol packages this skill documents.)

Note on "protocol version": AG-UI has no independently versioned spec — the repo's own contributor docs state "each package has independent versioning." The event names/fields are defined by whatever the reference SDKs currently implement, so the package versions above are the closest thing to a protocol version. Both are pre-1.0 — field names and event shapes can still change between minor releases; re-check sdks/python/ag_ui/core/events.py and types.py in the GitHub repo if something here looks stale.

Event Categories (28 Total)

1. Lifecycle Events (5)

Control the run boundary. RUN_STARTED/RUN_FINISHED/RUN_ERROR bound the whole agent run; STEP_STARTED/STEP_FINISHED bound each inner iteration (e.g. one LLM call). The spec doesn't mandate a specific "layer" emits each — this is the typical nesting shown in the flow diagrams below, not a protocol rule.

2. Text Message Events (4)

Streaming text content from the assistant.

3. Tool Call Events (5)

Tool invocation lifecycle.

4. Reasoning Events (7)

Chain-of-thought / thinking visibility.

5. State Events (3)

Synchronize agent state with the UI.

6. Activity Events (2)

Progress indicators for long-running operations.

7. Special Events (2)

Event Flow Diagrams

Simple Text Response

RUN_STARTED
└── STEP_STARTED (iteration-0)
    ├── TEXT_MESSAGE_START
    ├── TEXT_MESSAGE_CONTENT (×N chunks)
    ├── TEXT_MESSAGE_END
    └── STEP_FINISHED (iteration-0, usage in rawEvent)
RUN_FINISHED

Tool Call + Response

RUN_STARTED
└── STEP_STARTED (iteration-0)
    ├── TOOL_CALL_START (toolCallId, toolCallName)
    ├── TOOL_CALL_ARGS (delta: JSON fragments ×N)
    ├── TOOL_CALL_END
    ├── TOOL_CALL_RESULT (content)
    └── STEP_FINISHED (iteration-0)
└── STEP_STARTED (iteration-1)
    ├── TEXT_MESSAGE_START
    ├── TEXT_MESSAGE_CONTENT (×N)
    ├── TEXT_MESSAGE_END
    └── STEP_FINISHED (iteration-1)
RUN_FINISHED

With Reasoning/Thinking

RUN_STARTED
└── STEP_STARTED (iteration-0)
    ├── REASONING_START
    ├── REASONING_MESSAGE_START
    ├── REASONING_MESSAGE_CONTENT (×N)
    ├── REASONING_MESSAGE_END
    ├── REASONING_END
    ├── TEXT_MESSAGE_START
    ├── TEXT_MESSAGE_CONTENT (×N)
    ├── TEXT_MESSAGE_END
    └── STEP_FINISHED (iteration-0)
RUN_FINISHED

Detailed Guides

• Event Structures Reference — JSON shapes, field types, serialization rules → references/event-structures.md
• Frontend Integration Guide — React/TypeScript patterns, SSE consumption, state management → references/frontend-guide.md
• Backend Integration Guide — Python emission patterns, SSE endpoints, custom events → references/backend-guide.md