AI导哈

智能体UI协议演示

展示三种智能体前端交互协议（AG-UI、A2UI、MCP-UI）的核心差异及实现方式。

  • by MadLongTom
  • TypeScript
  • 本地部署
  • 14 星标
  • 更新于
在 GitHub 查看 MadLongTom/demo-agent-ui-protocols

使用说明

Agent-UI Protocols Demo

演示三种智能体前端交互协议：AG-UI、A2UI、MCP-UI

🎯 项目简介

本项目通过统一的餐厅搜索场景，展示三种 Agent-to-UI 协议的核心差异：

协议 来源 核心理念 数据格式
AG-UI CopilotKit 事件驱动的双向通信 SSE 事件流 (~16种事件类型)
A2UI Google 声明式 UI 组件规范 JSONL (邻接表模型)
MCP-UI 社区 MCP Tool 的 UI 扩展 UIResource (HTML/URI/RemoteDOM)

📁 项目结构

demo-agent-ui-protocols/
├── apps/web/                # Next.js 前端 (port 3000)
├── agents/
│   ├── ag-ui-agent/         # AG-UI Python Agent (port 8001)
│   ├── a2ui-agent/          # A2UI Python Agent (port 8002)
│   └── mcp-ui-agent/        # MCP-UI Python Agent (port 8003)
├── packages/shared/         # 共享类型定义
├── install.sh               # 一键安装依赖
├── run.sh                   # 一键启动所有服务
└── .env.example             # 环境变量模板

🚀 快速开始

1️⃣ 克隆项目

git clone <repo-url>
cd demo-agent-ui-protocols

2️⃣ 配置环境变量

cp .env.example .env

编辑 .env 文件，填入你的 API 配置：

OPENAI_API_KEY=your-api-key
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4o-mini

3️⃣ 安装依赖

chmod +x install.sh run.sh
./install.sh

4️⃣ 启动服务

./run.sh

所有服务将自动启动，按 Ctrl+C 可停止全部服务。

5️⃣ 访问 Demo

页面 地址
首页 http://localhost:3000
AG-UI Demo http://localhost:3000/ag-ui-demo
A2UI Demo http://localhost:3000/a2ui-demo
MCP-UI Demo http://localhost:3000/mcp-ui-demo

📡 协议核心特性

AG-UI (CopilotKit)

事件驱动的流式协议，前端控制 UI 渲染：

事件类型:
├── 生命周期: RUN_STARTED / RUN_FINISHED / RUN_ERROR
├── 文本消息: TEXT_MESSAGE_START / CONTENT / END
├── 工具调用: TOOL_CALL_START / ARGS / END / RESULT
└── 状态管理: STATE_SNAPSHOT / STATE_DELTA

A2UI (Google)

声明式 UI 规范，Agent 生成组件定义：

消息类型:
├── surfaceUpdate    # 组件定义 (邻接表模型)
├── dataModelUpdate  # 数据模型更新
├── beginRendering   # 触发渲染信号
└── deleteSurface    # 删除 UI 区域

MCP-UI (社区)

MCP 协议的 UI 扩展，Tool 返回可渲染内容：

UIResource:
├── mimeType: text/html          # iframe srcDoc
├── mimeType: text/uri-list      # iframe src
└── mimeType: remote-dom         # Shopify RemoteDOM

UI Actions: tool / prompt / notify / link

🛠 环境要求

  • Node.js 18+
  • pnpm 9+ (自动安装)
  • Python 3.10+
  • uv (自动安装)

📝 手动启动 (可选)

如果需要分别启动各服务：

# 终端 1: 前端
pnpm dev:web

# 终端 2: AG-UI Agent
cd agents/ag-ui-agent && source .venv/bin/activate && python server.py

# 终端 3: A2UI Agent
cd agents/a2ui-agent && source .venv/bin/activate && python server.py

# 终端 4: MCP-UI Agent
cd agents/mcp-ui-agent && source .venv/bin/activate && python server.py

📚 参考资料

📄 License

MIT

相关 MCP