- Understanding the AG-UI protocol
- Creating AG-UI compatible agents using TypeScript
- Hosting agents on Express.js or NestJS
- Connecting your agent to CometChat
What is AG-UI?
Overview
AG-UI (Agent-User Interaction Protocol) is an open-source, lightweight, event-based protocol developed to standardize real-time communication between AI agents and user interfaces. It provides a vendor-neutral format that works across different AI providers (OpenAI, Anthropic, custom models, etc.) without requiring changes to client-side implementations.Key Features
- Event-Driven Architecture: Streams JSON-encoded events over HTTP or WebSocket
- Real-Time Streaming: Supports token-by-token streaming of agent responses
- Tool Integration: Enables agents to call frontend tools and functions
- State Management: Synchronizes state between agents and UI
- Framework Agnostic: Works with Node.js, browsers, and any agent framework
- Vendor Neutral: Compatible with any AI service provider
Core Concepts
AG-UI operates on three fundamental concepts:- Events: Standardized messages that flow from agent to frontend
- Messages: Conversation history between users and agents
- Tools: Functions that agents can invoke to perform actions
AG-UI Event Types
AG-UI defines 16+ standardized event types organized into six categories. Understanding these events is crucial for implementing AG-UI compatible agents.1. Lifecycle Events
These events monitor the progression of agent runs.RUN_STARTED
Signals the start of an agent run.RUN_FINISHED
Signals successful completion of an agent run.RUN_ERROR
Signals an error during an agent run.STEP_STARTED & STEP_FINISHED
Optional events for tracking discrete steps within a run.2. Text Message Events
These events handle streaming textual content between agents and users.TEXT_MESSAGE_START
Signals the start of a text message.TEXT_MESSAGE_CONTENT
Represents a chunk of content in a streaming message.TEXT_MESSAGE_END
Signals the end of a text message.TEXT_MESSAGE_CHUNK
A convenience event that combines start, content, and end in one.3. Tool Call Events
These events manage tool executions by agents.TOOL_CALL_START
Signals the start of a tool call.TOOL_CALL_ARGS
Streams the arguments for a tool call.TOOL_CALL_END
Marks the completion of a tool call.TOOL_CALL_CHUNK
A convenience event for tool calls (similar to TEXT_MESSAGE_CHUNK).TOOL_CALL_RESULT
Provides the result of a tool call execution.4. State Management Events
These events synchronize agent state with the frontend.STATE_SNAPSHOT
Provides a complete snapshot of agent state.STATE_DELTA
Provides incremental state updates using JSON Patch (RFC 6902).MESSAGES_SNAPSHOT
Provides a snapshot of all messages in a conversation.5. Special Events
CUSTOM
Used for application-specific custom events.RAW
Used to pass through events from external systems.Event Flow Patterns
AG-UI events follow specific patterns:-
Start-Content-End Pattern: Used for streaming (text messages, tool calls)
- Start event initiates the stream
- Content events deliver data chunks
- End event signals completion
-
Snapshot-Delta Pattern: Used for state synchronization
- Snapshot provides complete state
- Delta events provide incremental updates
-
Lifecycle Pattern: Used for monitoring agent runs
- Started events signal beginnings
- Finished/Error events signal endings