copilotkit-agui

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AG-UI Protocol Skill

AG-UI 协议技能

Overview

概述

AG-UI (Agent-User Interaction) is CopilotKit's open event-based protocol for agent-to-UI communication. All agent-frontend interaction flows through typed events streamed over SSE (Server-Sent Events) or binary protobuf transport. Agents implement

AbstractAgent.run()

returning an RxJS

Observable<BaseEvent>

, and the client SDK handles event application, state management, and message history.

AG-UI（Agent-User Interaction，即Agent与用户交互）是CopilotKit推出的基于事件的开源协议，用于Agent与UI之间的通信。所有Agent与前端的交互都通过SSE（Server-Sent Events，服务器发送事件）或二进制protobuf传输的类型化事件进行流转。Agent需实现

AbstractAgent.run()

方法，返回RxJS

Observable<BaseEvent>

，而客户端SDK负责事件应用、状态管理和消息历史记录。

When to Use

使用场景

Building a custom agent backend that needs to speak AG-UI
Implementing
```
AbstractAgent.run()
```
for a new framework integration
Debugging why events aren't reaching the frontend or arriving malformed
Understanding event ordering (lifecycle, text, tool calls, state)
Working with state synchronization (snapshots vs JSON Patch deltas)
Implementing human-in-the-loop interrupt/resume flows
Troubleshooting SSE streaming or encoding issues

构建需要适配AG-UI协议的自定义Agent后端
为新框架集成实现
```
AbstractAgent.run()
```
方法
调试事件无法到达前端或格式异常的问题
理解事件的顺序（生命周期、文本、工具调用、状态相关事件）
处理状态同步（快照与JSON Patch增量）
实现人机协同的中断/恢复流程
排查SSE流式传输或编码问题

When NOT to Use

非适用场景

For CopilotKit React hooks and frontend components, use
```
copilotkit-develop
```
For CopilotKit runtime setup and configuration, use
```
copilotkit-setup
```
For framework-specific integration guides (LangGraph, Mastra, CrewAI), use
```
copilotkit-integrations
```

若使用CopilotKit React钩子和前端组件，请使用
```
copilotkit-develop
```
若进行CopilotKit运行时设置和配置，请使用
```
copilotkit-setup
```
若需要框架特定的集成指南（LangGraph、Mastra、CrewAI），请使用
```
copilotkit-integrations
```

Quick Reference

快速参考

Event Families

事件类别

Family	Events	Purpose
Lifecycle	`RUN_STARTED` , `RUN_FINISHED` , `RUN_ERROR` , `STEP_STARTED` , `STEP_FINISHED`	Run boundaries and progress
Text	`TEXT_MESSAGE_START` , `TEXT_MESSAGE_CONTENT` , `TEXT_MESSAGE_END`	Streaming text messages
Tool Calls	`TOOL_CALL_START` , `TOOL_CALL_ARGS` , `TOOL_CALL_END` , `TOOL_CALL_RESULT`	Agent tool invocations
State	`STATE_SNAPSHOT` , `STATE_DELTA` , `MESSAGES_SNAPSHOT`	State synchronization
Reasoning	`REASONING_START` , `REASONING_MESSAGE_START/CONTENT/END` , `REASONING_END` , `REASONING_ENCRYPTED_VALUE`	Chain-of-thought visibility
Activity	`ACTIVITY_SNAPSHOT` , `ACTIVITY_DELTA`	Structured progress updates
Custom	`RAW` , `CUSTOM`	Extension points

类别	事件	用途
生命周期	`RUN_STARTED` , `RUN_FINISHED` , `RUN_ERROR` , `STEP_STARTED` , `STEP_FINISHED`	运行边界与进度跟踪
文本	`TEXT_MESSAGE_START` , `TEXT_MESSAGE_CONTENT` , `TEXT_MESSAGE_END`	流式文本消息传输
工具调用	`TOOL_CALL_START` , `TOOL_CALL_ARGS` , `TOOL_CALL_END` , `TOOL_CALL_RESULT`	Agent工具调用管理
状态	`STATE_SNAPSHOT` , `STATE_DELTA` , `MESSAGES_SNAPSHOT`	状态同步
推理	`REASONING_START` , `REASONING_MESSAGE_START/CONTENT/END` , `REASONING_END` , `REASONING_ENCRYPTED_VALUE`	思维链可视化
活动	`ACTIVITY_SNAPSHOT` , `ACTIVITY_DELTA`	结构化进度更新
自定义	`RAW` , `CUSTOM`	扩展接口

Convenience Chunk Events

便捷分块事件

TEXT_MESSAGE_CHUNK

and

TOOL_CALL_CHUNK

auto-expand into Start/Content/End triads via the client's

transformChunks

pipeline. Use these for simpler backend implementations.

TEXT_MESSAGE_CHUNK

和

TOOL_CALL_CHUNK

会通过客户端的

transformChunks

管道自动扩展为Start/Content/End三段式事件。在后端实现较简单的场景下可使用这些事件。

SSE Wire Format

SSE 传输格式

Each event is a JSON object sent as an SSE data line:

data: {"type":"RUN_STARTED","threadId":"t1","runId":"r1"}\n\n
data: {"type":"TEXT_MESSAGE_START","messageId":"m1","role":"assistant"}\n\n
data: {"type":"TEXT_MESSAGE_CONTENT","messageId":"m1","delta":"Hello"}\n\n
data: {"type":"TEXT_MESSAGE_END","messageId":"m1"}\n\n
data: {"type":"RUN_FINISHED","threadId":"t1","runId":"r1"}\n\n

每个事件都是作为SSE数据行发送的JSON对象：

data: {"type":"RUN_STARTED","threadId":"t1","runId":"r1"}\n\n
data: {"type":"TEXT_MESSAGE_START","messageId":"m1","role":"assistant"}\n\n
data: {"type":"TEXT_MESSAGE_CONTENT","messageId":"m1","delta":"Hello"}\n\n
data: {"type":"TEXT_MESSAGE_END","messageId":"m1"}\n\n
data: {"type":"RUN_FINISHED","threadId":"t1","runId":"r1"}\n\n

Packages

Package	npm	Purpose
`@ag-ui/core`	Events, types, schemas	Protocol definition
`@ag-ui/client`	AbstractAgent, HttpAgent, middleware, event application	Client SDK
`@ag-ui/encoder`	EventEncoder (SSE + protobuf)	Server-side encoding

包名	npm地址	用途
`@ag-ui/core`	包含事件、类型、Schema定义	协议核心定义
`@ag-ui/client`	包含AbstractAgent、HttpAgent、中间件、事件应用逻辑	客户端SDK
`@ag-ui/encoder`	包含EventEncoder（支持SSE + protobuf）	服务端编码工具

Workflow: Building an AG-UI Backend

工作流：构建AG-UI后端

Define your endpoint -- Accept POST with
```
RunAgentInput
```
body, respond with
```
text/event-stream
```
Parse input -- Extract
```
threadId
```
,
```
runId
```
,
```
messages
```
,
```
tools
```
,
```
state
```
,
```
context
```
from the request body
Emit events in order --
```
RUN_STARTED
```
first, then content events, then
```
RUN_FINISHED
```
or
```
RUN_ERROR
```

Encode as SSE -- Use

@ag-ui/encoder

EventEncoder.encode()

or manually write

data: JSON\n\n

Handle tool results -- Client sends
```
TOOL_CALL_RESULT
```
back; agent processes and continues

See

references/building-agents.md

for a complete working example.

定义端点 -- 接收带有
```
RunAgentInput
```
请求体的POST请求，返回
```
text/event-stream
```
类型响应
解析输入 -- 从请求体中提取
```
threadId
```
、
```
runId
```
、
```
messages
```
、
```
tools
```
、
```
state
```
、
```
context
```
按顺序发送事件 -- 先发送
```
RUN_STARTED
```
，再发送内容事件，最后发送
```
RUN_FINISHED
```
或
```
RUN_ERROR
```
编码为SSE格式 -- 使用
```
@ag-ui/encoder
```
的
```
EventEncoder.encode()
```
方法，或手动编写
```
data: JSON\n\n
```
格式内容
处理工具结果 -- 客户端会回传
```
TOOL_CALL_RESULT
```
；Agent处理后继续执行流程

完整的示例可参考

references/building-agents.md

。

Key Protocol Rules

核心协议规则

Every run MUST start with
```
RUN_STARTED
```
and end with
```
RUN_FINISHED
```
or
```
RUN_ERROR
```
```
TEXT_MESSAGE_CONTENT.delta
```
must be non-empty
Tool call events are linked by
```
toolCallId
```
```
STATE_DELTA
```
uses RFC 6902 JSON Patch operations
Multiple sequential runs are supported -- each must complete before the next starts
Messages accumulate across runs; state continues unless reset by
```
STATE_SNAPSHOT
```

每次运行必须以
```
RUN_STARTED
```
开头，以
```
RUN_FINISHED
```
或
```
RUN_ERROR
```
结尾
```
TEXT_MESSAGE_CONTENT.delta
```
必须非空
工具调用事件通过
```
toolCallId
```
关联
```
STATE_DELTA
```
采用RFC 6902 JSON Patch操作规范
支持多轮连续运行 -- 每一轮必须完成后才能启动下一轮
消息会在多轮运行中累积；状态会持续保留，除非通过
```
STATE_SNAPSHOT
```
重置

References

参考资料

```
references/protocol-spec.md
```
-- Complete event type reference with schemas and examples
```
references/building-agents.md
```
-- Step-by-step guide to building AG-UI backends
```
references/event-flow-diagrams.md
```
-- ASCII sequence diagrams for common flows
```
references/client-sdk.md
```
-- @ag-ui/client API reference

```
references/protocol-spec.md
```
-- 完整的事件类型参考，包含Schema和示例
```
references/building-agents.md
```
-- 构建AG-UI后端的分步指南
```
references/event-flow-diagrams.md
```
-- 常见流程的ASCII序列图
```
references/client-sdk.md
```
-- @ag-ui/client的API参考