Skip to content

feat: Add AG-UI and A2UI protocol support for real-time streaming and rich UIs#988

Open
protolabs42 wants to merge 6 commits intoagent0ai:developmentfrom
protolabs42:feature/agui-a2ui-protocol
Open

feat: Add AG-UI and A2UI protocol support for real-time streaming and rich UIs#988
protolabs42 wants to merge 6 commits intoagent0ai:developmentfrom
protolabs42:feature/agui-a2ui-protocol

Conversation

@protolabs42
Copy link

Summary

This PR adds support for two complementary protocols that enable real-time communication and rich interactive UIs:

AG-UI Protocol (SSE Streaming)

  • Real-time Server-Sent Events streaming at /agui endpoint
  • Events for text chunks, tool calls, reasoning/thinking, and step lifecycle
  • Compatible with CopilotKit and other AG-UI clients
  • Spec: https://docs.ag-ui.com

A2UI Protocol (Rich Interactive UIs)

  • Agents can generate declarative UI components (forms, cards, buttons, etc.)
  • Components rendered by compatible clients (Flutter, Web, React Native)
  • Full A2UI v0.8 standard catalog support (18/18 components)
  • Spec: https://a2ui.org/specification/v0.8-a2ui/

Architecture

Agent Zero
    │
    ▼
┌─────────────────────────┐
│  A2UI Tool              │  Agent generates UI via a2ui:show, a2ui:form, etc.
│  (python/tools/a2ui.py) │
└───────────┬─────────────┘
            │ wrapped as CustomEvent
            ▼
┌─────────────────────────┐
│  AG-UI Endpoint         │  SSE streaming: text, tools, thinking, A2UI events
│  (/agui)                │
└───────────┬─────────────┘
            │ SSE
            ▼
        Client (Flutter, Web, etc.)

Files Added

AG-UI Layer:

  • python/api/agui_endpoint.py - SSE endpoint
  • python/helpers/agui_server.py - Queue management
  • python/helpers/agui_validation.py - Request validation
  • python/extensions/*/_15_agui_*.py - 8 streaming hooks

A2UI Layer:

  • python/helpers/a2ui/ - Protocol package (types, builder, emitter, surfaces)
  • python/tools/a2ui.py - A2UI tool for agents
  • python/extensions/a2ui_action/_10_handle_action.py - User action handler
  • prompts/agent.system.tool.a2ui.md - Tool documentation

Integration:

  • run_ui.py - Mount /agui endpoint
  • requirements.txt - Add ag-ui-protocol dependency
  • docs/agui.md, docs/a2ui.md - Documentation

Verification

  • AG-UI: 17/17 event types implemented (100%)
  • A2UI v0.8: 18/18 standard components implemented (100%)
  • All Python files pass syntax verification

See docs/VERIFICATION_REPORT.md for full compliance details.

Testing

  1. Start Agent Zero with this branch
  2. Test SSE streaming: curl -N -X POST http://localhost:port/agui -H "Content-Type: application/json" -d '{"messages":[{"role":"user","content":"Hello"}]}'
  3. Test A2UI: Ask the agent to show a form or display information

protolabs42 and others added 6 commits February 4, 2026 13:43
Implements the AG-UI (Agent-User Interaction Protocol) for real-time
Server-Sent Events streaming between Agent Zero and frontend clients.

Features:
- SSE endpoint at /agui for streaming agent events
- Support for both JSON-RPC and flat request formats
- Event types: RUN_STARTED/FINISHED, TEXT_MESSAGE_*, TOOL_CALL_*,
  THINKING_*, STEP_STARTED/FINISHED, STATE_*, CUSTOM
- Authentication via Bearer token, API key header, or query param
- A2UI action endpoint at /agui/a2ui/action

Specification: https://docs.ag-ui.com

Co-Authored-By: Sophie <noreply@anthropic.com>
Extension hooks that emit AG-UI events during agent execution:
- _15_agui_step_start.py: Emit STEP_STARTED on loop iteration
- _15_agui_step_end.py: Emit STEP_FINISHED on loop completion
- _15_agui_text_stream.py: Stream TEXT_MESSAGE_CONTENT chunks
- _15_agui_text_end.py: Emit TEXT_MESSAGE_END
- _15_agui_thinking_stream.py: Stream THINKING_* events
- _15_agui_thinking_end.py: Emit THINKING_END
- _15_agui_tool_start.py: Emit TOOL_CALL_START/ARGS
- _15_agui_tool_end.py: Emit TOOL_CALL_END/RESULT

Co-Authored-By: Sophie <noreply@anthropic.com>
Implements the A2UI (Agent-to-UI) protocol v0.8 allowing agents to
generate declarative UI components rendered by compatible clients.

Package contents:
- types.py: Pydantic models for all A2UI messages and components
- components.py: Fluent ComponentBuilder API for UI construction
- emitter.py: A2UIEmitter for AG-UI transport integration
- surfaces.py: SurfaceManager for UI lifecycle management
- integration.py: High-level helpers (show_form, show_message, etc.)

Standard catalog components (100% coverage):
- Content: Text, Icon, Image, Video, AudioPlayer
- Layout: Column, Row, List, Card, Tabs, Divider, Modal
- Input: Button, CheckBox, TextField, DateTimeInput, MultipleChoice, Slider

Extension components beyond standard catalog:
- IconButton, Switch, Dropdown, ListTile, Progress indicators, Chip

Specification: https://a2ui.org/specification/v0.8-a2ui/

Co-Authored-By: Sophie <noreply@anthropic.com>
Adds the a2ui tool that allows agents to generate interactive UIs:
- Methods: show, form, message, progress, confirm, data, delete
- Surfaces: @ui (default), @modal, @toast, custom IDs
- Data binding with JSON Pointer paths
- User action callback handling via extension hook

Files:
- python/tools/a2ui.py: Tool implementation
- python/extensions/a2ui_action/_10_handle_action.py: Action handler
- prompts/agent.system.tool.a2ui.md: Tool documentation for LLM

Co-Authored-By: Sophie <noreply@anthropic.com>
- Mount /agui endpoint in Starlette routes alongside /mcp and /a2a
- Add ag-ui-protocol dependency to requirements.txt

Co-Authored-By: Sophie <noreply@anthropic.com>
- docs/agui.md: AG-UI protocol overview, endpoints, event types, usage
- docs/a2ui.md: A2UI tool guide, components, surfaces, examples
- docs/VERIFICATION_REPORT.md: Spec compliance verification

Protocol compliance verified:
- AG-UI: 17/17 event types (100%)
- A2UI v0.8: 18/18 standard components (100%)

Co-Authored-By: Sophie <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant