简单理解AG-UI

作为笔记保存

AG-UI（Agent User Interaction Protocol）通过开放协议标准化了前端应用和AI agents之间的连接，填补了互动层的空白，完善了从用户到后端AI驱动系统的完整链条。当不同AI agents框架用不同语言返回内容，AG-UI更像是不同后端AI agents的万能翻译器，核心在于确保用户端和混搭代理系统的流畅交流，帮助集成需要实时交互、实时状态以及人机交互（human-in-the-loop）的AI工作流。

• MCP：Agent-to-Tool 代理到工具
• Agent2Agent：Agent-to-Agent 代理到代理
• AG-UI：Agent-to-User-Interaction 代理到用户互动

尽管多步骤代理工作流（multi-step agentic workflows）很强大，把代理放到app时还是会遇到一些问题，人们常提到的场景有：

• 当想逐个令牌地传输 LLM 响应，而无需构建自定义 WebSocket 服务器
• 实时显示工具执行进度，并在不阻断或丢失上下文的情况下暂停以等待人工反馈
• 同步大型、不断变化的对象（例如代码或表格），而无需将所有内容重新发送到 UI
• 允许用户在代理运行过程中中断、取消或回复，而不会丢失上下文

而且每个代理后端有自己的工具调用机制、ReAct规划、状态差异（state diff）、输出格式等等。比如使用LangGraph时，前端会实现自定义的WebSocket逻辑、复杂的JSON以及LangGraph专用的UI适配——如果要迁移到CrewAI，这一切必须要因地制宜对应地调整。可扩展性的缺乏可见一斑。

---

CopilotKit提供的AG-UI开源协议可以解决这个问题。整体流程简单来看是这样：

1. 用户在应用上进行交互
2. 应用发出Agent call给到AG-UI
3. AG-UI和任一个Agent后端交流
4. AG-UI收到Agent的响应并进行处理
5. AG-UI把标准化后的响应返回给应用，呈现给用户

就好比REST之于客户端-服务器请求。

AG-UI用SSE（Server-Sent Events）把结构化的JSON事件传输到前端。 每个事件都包含一个显式的载荷（payload），例如：

• TEXT_MESSAGE_CONTENT：用于令牌流式传输 token streaming
• TOOL_CALL_START：用于显示工具执行情况
• STATE_DELTA：用于更新共享状态（shared state），比如代码、数据等
• AGENT_HANDOFF：在代理之间平滑地传递控制权

调用这些payload只需要类似于agui_response[`TEST_MESSAGE_CONTENT`]的方式，类似于Python字典里的键。

AG-UI还附带TypeScript和Python语言的SDK，几乎可以即插即用（plug-and-play）于任何LLM agent后端技术栈。SDK文档在这里：https://docs.agentwire.io/introduction

• AI agents平台均可以发出AG-UI事件，可以根据需要混搭Agent框架，充分利用不同agents的优势
• 开发者可以用CopilotKit组件或者自己的React技术栈动手搭建通用的UI
• 可以在本地将GPT-4切换成Llama-3而无需修改前端任何内容

---

截至写此文时（2025/5/13），AG-UI支持的AI代理框架有LangGraph，CrewAI，Mastra和AG2。

• LangGraph：使用LangGraph强大的编排功能，构建具有共享状态和human-in-the-loop workflow的代理原生应用程序
• CrewAI Flows：创建具有明确阶段和流程控制的顺序多代理工作流。
• ​CrewAI Crews：设计具有专门角色和代理间通信的协作代理团队。
• ​Mastra：利用 TypeScript 构建强类型代理实现，增强开发者体验。
• ​AG2：利用开源 AgentOS 实现可扩展、可立即投入生产的代理部署。

还有很多框架等待着开源工程师帮助一同构建适配性，比如OpenAI Agent SDK和Google ADK等等。

---

Links：
AG-UI GitHub网址：ag-ui-protocol/ag-ui: AG-UI: The Agent-User Interaction Protocol
AG-UI SDK文档：Introduction - Agent User Interaction Protocol