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) 是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 hooks和前端组件，请参考
```
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

流水线自动展开为开始/内容/结束三元组，你可以使用这些事件简化后端实现。

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

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

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`	事件、类型、schemas	协议定义
`@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参考