mcpField
C
copilotkit-agui

copilotkit-agui

github.com/copilotkit开发38.3k2.8k 次安装今天更新
代码仓库

关于 copilotkit-agui

copilotkit-agui 是面向开发者的技能，用于实现或排查 Agent 与前端之间的 AG-UI 事件协议。内容涵盖类型化事件流、状态同步、流式传输和人在环路交互。

主要功能

  1. 01介绍 AG-UI 事件类别
  2. 02指导后端事件流传输
  3. 03说明状态快照与 JSON Patch
  4. 04记录中断和恢复流程
  5. 05排查 SSE 与编码问题

适用场景

  1. 01构建兼容 AG-UI 的 Agent 后端
  2. 02使用 AbstractAgent 添加框架集成
  3. 03诊断前端事件丢失或格式错误
  4. 04实现状态同步或人工审核

安装

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

$npx skills add https://github.com/copilotkit/copilotkit --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 实现 AbstractAgent.run()，返回 RxJS 的 Observable<BaseEvent>，客户端 SDK 负责事件应用、状态管理和消息历史。

何时使用

  • 构建需要支持 AG-UI 的自定义 Agent 后端
  • 为新的框架集成实现 AbstractAgent.run()
  • 调试事件为何未到达前端或以错误格式到达
  • 理解事件顺序（生命周期、文本、工具调用、状态）
  • 处理状态同步（快照 vs JSON Patch 增量）
  • 实现 human-in-the-loop 中断/恢复流程
  • 排查 SSE 流式传输或编码问题

何时不使用

  • 如需 CopilotKit React hooks 和前端组件，请使用 copilotkit-develop
  • 如需 CopilotKit runtime 的设置和配置，请使用 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 传输格式

每个事件都是一个 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
包
包npm用途
@ag-ui/core事件、类型、schema协议定义
@ag-ui/clientAbstractAgent、HttpAgent、中间件、事件应用客户端 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 -- 完整的事件类型参考，包含 schema 和示例
  • references/building-agents.md -- 构建 AG-UI 后端的分步指南
  • references/event-flow-diagrams.md -- 常见流程的 ASCII 时序图
  • references/client-sdk.md -- @ag-ui/client API 参考

评论

支持 Markdown