mcpField
C
copilotkit-agui

copilotkit-agui

github.com/copilotkit开发39607 次安装21 周前更新
代码仓库

关于 copilotkit-agui

copilotkit-agui 是面向 CopilotKit AG-UI 事件协议的技能资料，供构建 Agent 后端或框架集成的开发者使用。内容涵盖事件顺序、流式传输格式、状态同步及中断与恢复流程。

主要功能

  1. 01AG-UI 事件类型参考
  2. 02SSE 与 protobuf 编码指南
  3. 03后端实现流程
  4. 04状态快照与 JSON Patch 处理
  5. 05人工介入的中断与恢复

适用场景

  1. 01构建兼容 AG-UI 的 Agent 后端
  2. 02实现 AbstractAgent.run()
  3. 03排查前端事件格式错误或缺失
  4. 04追踪状态同步与工具调用流程

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/copilotkit/skills --skill copilotkit-agui

安装后在 Claude Code 中输入/copilotkit-agui确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

sources.md
references/
building-agents.md
client-sdk.md
event-flow-diagrams.md
protocol-spec.md

详细介绍

AG-UI 协议技能

概述

AG-UI（Agent-User Interaction）是 CopilotKit 推出的开放式事件协议，用于 Agent 与 UI 之间的通信。所有 Agent 与前端之间的交互都通过 SSE（Server-Sent Events）或二进制 protobuf 传输方式流式传送的类型化事件进行。Agent 实现返回 RxJS Observable<BaseEvent> 的 AbstractAgent.run()，客户端 SDK 负责处理事件应用、状态管理和消息历史记录。

适用场景

  • 构建需要使用 AG-UI 通信的自定义 Agent 后端
  • 为新的框架集成实现 AbstractAgent.run()
  • 调试事件为何未到达前端或格式异常
  • 理解事件顺序（生命周期、文本、工具调用、状态）
  • 处理状态同步（快照与 JSON Patch 增量）
  • 实现人在回路中的中断／恢复流程
  • 排查 SSE 流式传输或编码问题

不适用场景

  • 如需使用 CopilotKit React hooks 和前端组件，请使用 copilotkit-develop
  • 如需设置和配置 CopilotKit 运行时，请使用 copilotkit-setup
  • 如需查看特定框架的集成指南（LangGraph、Mastra、CrewAI），请使用 copilotkit-integrations

快速参考

事件类别
类别事件用途
生命周期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_RESULTAgent 工具调用
状态STATE_SNAPSHOT、STATE_DELTA、MESSAGES_SNAPSHOT状态同步
推理REASONING_START、REASONING_MESSAGE_START/CONTENT/END、REASONING_END、REASONING_ENCRYPTED_VALUE思维链可见性
活动ACTIVITY_SNAPSHOT、ACTIVITY_DELTA结构化进度更新
自定义RAW、CUSTOM扩展点
便捷分块事件

TEXT_MESSAGE_CHUNK 和 TOOL_CALL_CHUNK 会通过客户端的 transformChunks 管道自动展开为 Start/Content/End 三元组。后端实现较简单时可使用这些事件。

SSE 线上格式

每个事件都是作为 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
软件包
软件包npm用途
@ag-ui/coreEvents、types、schemas协议定义
@ag-ui/clientAbstractAgent、HttpAgent、middleware、event application客户端 SDK
@ag-ui/encoderEventEncoder（SSE + protobuf）服务端编码

工作流：构建 AG-UI 后端

  1. 定义端点 —— 接收包含 RunAgentInput 正文的 POST 请求，并以 text/event-stream 响应
  2. 解析输入 —— 从请求正文中提取 threadId、runId、messages、tools、state、context
  3. 按顺序发送事件 —— 首先发送 RUN_STARTED，然后发送内容事件，最后发送 RUN_FINISHED 或 RUN_ERROR
  4. 编码为 SSE —— 使用 @ag-ui/encoder 的 EventEncoder.encode()，或手动写入 data: JSON\n\n
  5. 处理工具结果 —— 客户端会将 TOOL_CALL_RESULT 发回；Agent 处理结果并继续运行

完整的可运行示例请参阅 references/building-agents.md。

协议关键规则

  • 每次运行都必须以 RUN_STARTED 开始，并以 RUN_FINISHED 或 RUN_ERROR 结束
  • TEXT_MESSAGE_CONTENT.delta 不能为空
  • 工具调用事件通过 toolCallId 关联
  • STATE_DELTA 使用 RFC 6902 JSON Patch 操作
  • 支持多个连续运行——每次运行都必须在下一次开始前完成
  • 消息会在多次运行间累积；除非通过 STATE_SNAPSHOT 重置，否则状态会持续保留

参考资料

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

评论

支持 Markdown