Overview of the CometChat AG-UI integration protocol, event categories, and message formats.CometChat has integrated support for AG-UI (Agent-User Interaction Protocol), making it easier than ever to bring your own AI agents into your applications. With the “Bring Your Own Agent” (BYOA) approach, you can now host your own AG-UI compatible agent and seamlessly integrate it with CometChat’s full-stack platform. This documentation provides a comprehensive guide on:
- 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