CopilotKit + A2A + A2UI 实战:用 AG-UI 协议构建可动态渲染 UI 的餐厅预订 Agent
CopilotKit + A2A + A2UI 实战:用 AG-UI 协议构建可动态渲染 UI 的餐厅预订 Agent
本文以仓库中的 A2A + A2UI Starter 模板 为蓝本,完整讲解如何基于 CopilotKit 前端栈与 Google ADK(A2A 协议)搭建一个能"边对话、边生成真实 UI"的餐厅查找与预订 Agent。读完本文,你将掌握 A2A/A2UI 协议的端到端协作链路、双服务器开发环境的启动与调试方式,以及如何借助声明式 UI Schema 让 LLM 直接输出可渲染的组件树。
模板概览:一个"餐厅搜索 + 在线订座"的 AI 应用
该 Starter 是一个现代 Next.js 全栈示例:前端由 CopilotKit 提供聊天界面与 A2UI 渲染能力,后端是一个运行于独立端口上的 A2A(Agent-to-Agent)Agent 服务。整体业务能力包括:
- 根据用户输入的美食类型(cuisine)与地点(location)查找餐厅并返回结果列表;
- 将结果渲染为带图片、评分、地址的卡片列表(单列或双列布局);
- 在卡片上发起"Book Now"(预订)操作,Agent 动态生成预订表单(人数、日期时间、饮食需求);
- 提交表单后生成预订成功确认界面,完成"对话 → 表单 → 确认"的完整闭环。
模板的核心思想是:大部分 UI 不再由前端手写,而是由 Agent 以 A2UI 声明式 JSON 的形式动态下发。前端 app/page.tsx 中仅挂载了 CopilotChat 组件,其余界面均由 Agent 生成。
环境准备(Prerequisites)
开始前需要准备以下环境:
| 依赖 | 版本/说明 |
|---|---|
| Gemini API Key | 供 ADK/A2A Agent 调用大模型(详见下文 API Key 一节) |
| Python | 3.12+ |
| uv | Python 依赖与虚拟环境管理工具 |
| Node.js | 20+ |
| 包管理器 | npm(默认)、pnpm、yarn、bun 任选其一 |
Node.js 20+ 是运行 Next.js 16 前端与构建工具链的最低要求;Python 3.12+ 与 uv 用于运行 Agent 侧的 ADK 框架与 A2A 服务端。
快速开始:一键启动双服务
第一步:安装依赖
在模板根目录执行安装命令,使用你偏好的包管理器:
# 使用 npm(默认)
npm install
# 使用 pnpm
pnpm install
# 使用 yarn
yarn install
# 使用 bun
bun install
注意:安装过程会自动完成 Python 环境的初始化(
postinstall钩子会调用install:agent,即执行 scripts/setup-agent.sh 在agent/目录下运行uv sync)。如果手动安装遇到问题,可单独执行:npm run install:agent
第二步:配置 Gemini API Key
在 agent 文件夹内创建 .env 文件(即 examples/integrations/a2a-a2ui/agent/.env),写入以下内容:
GEMINI_API_KEY=your-gemini-api-key-here
Agent 服务启动时通过 agent/main.py 中的 load_dotenv() 加载该文件。源码中的校验逻辑是:只要环境变量 GOOGLE_GENAI_USE_VERTEXAI 不等于 TRUE,就必须存在 GEMINI_API_KEY,否则服务直接报错退出——也就是说,如果你改为使用 Vertex AI,可以不用设置该 Key。此外,Agent 默认使用 LITELLM_MODEL 环境变量指定的模型(默认值为 gemini/gemini-2.5-flash),需要切换模型时可以通过该变量覆盖。
第三步:启动开发服务器
# 使用 npm(默认)
npm run dev
# 使用 pnpm
pnpm dev
# 使用 yarn
yarn dev
# 使用 bun
bun run dev
该命令通过 concurrently 同时启动两个服务(见 package.json 中的 dev 脚本):
- UI 服务:
next dev --turbopack,即 Next.js 前端; - Agent 服务:执行 scripts/run-agent.sh,在
agent/目录下运行uv run .,通过 uvicorn 启动 A2A 服务器(默认监听http://localhost:10002)。
启动完成后打开前端页面,即可向聊天窗口提问,例如"Find me the top 5 chinese restaurants"。
可用脚本一览
所有脚本均可搭配你选择的包管理器运行:
| 脚本 | 说明 |
|---|---|
dev |
同时启动 UI 与 Agent 两个开发服务器(默认入口) |
dev:debug |
以 LOG_LEVEL=debug 启动开发服务器,便于排查协议层问题 |
dev:ui |
仅启动 Next.js UI 服务器 |
dev:agent |
仅启动 A2A Agent 服务器 |
build |
构建 Next.js 应用用于生产环境 |
start |
启动生产服务器 |
install:agent |
为 Agent 安装 Python 依赖(uv sync) |
架构拆解:A2A 与 A2UI 如何协作
要真正用好这个模板,需要理解两条关键链路:A2A 负责"对话与任务",A2UI 负责"界面生成与更新"。
A2A 服务端:ADK Agent 的暴露方式
agent/main.py 将基于 Google ADK 构建的 RestaurantAgent 包装为标准的 A2A Starlette 应用:
- 通过
AgentCapabilities(streaming=True, extensions=[get_a2ui_agent_extension()])声明支持流式输出,并挂载 A2UI 扩展; - 通过
AgentSkill(id="find_restaurants", ...)声明"查找餐厅"技能,供客户端在发现阶段识别; - 挂载
CORSMiddleware,允许来自http://localhost:5173的跨域请求; - 将
agent/images/目录作为/static静态资源对外服务,供卡片中的菜品图片引用。
其中 A2UI 扩展定义在 a2ui_extension/src/a2ui/a2ui_extension.py:它约定 MIME 类型 application/json+a2ui,通过 create_a2ui_part() 把 A2UI JSON 包装成 A2A 的 DataPart 随消息流下发。
Agent 实现:工具调用 + 动态 UI 输出
agent/agent.py 中的 RestaurantAgent 是核心逻辑所在,其指令(AGENT_INSTRUCTION)约定了三段式业务逻辑:
- 查找餐厅:必须调用
get_restaurants工具,从用户输入中提取 cuisine、location 与数量count; - 预订:收到形如
USER_WANTS_TO_BOOK...的查询时,生成预订表单 UI; - 确认:收到
User submitted a booking...的查询时,生成确认 UI。
其中 agent/tools.py 实现了 get_restaurants(cuisine, location, count) 工具:它会读取 agent/restaurant_data.json 中的餐厅数据,并利用 ToolContext 中的 base_url 把图片链接中的 http://localhost:10002 替换为 Agent 服务的实际地址,保证前端能正确加载静态图片。
前端:CopilotRuntime 桥接 A2A 与 CopilotKit
app/api/copilotkit/[[...slug]]/route.tsx 是前后端之间的桥梁:它实例化 A2AClient("http://localhost:10002"),并通过 RuntimeA2AAgent(继承自 @ag-ui/a2a 的 A2AAgent)将 A2A Agent 包装为 CopilotKit Runtime 的默认 Agent,随后用 createCopilotEndpoint 暴露为 /api/copilotkit 端点。前端 app/page.tsx 中的 CopilotKitProvider 通过 runtimeUrl="/api/copilotkit" 接入该端点,并通过 a2ui={{ theme }} 与 renderActivityMessages={activityRenderers} 启用 A2UI 渲染。
理解 A2UI 声明式 Schema:Agent 如何"画"出界面
模板的关键在于 agent/prompt_builder.py(即 examples/integrations/a2a-a2ui/agent/prompt_builder.py)。它向 LLM 提供了完整的 A2UI JSON Schema(A2UI_SCHEMA)、针对餐厅场景的 UI 模板示例(RESTAURANT_UI_EXAMPLES),以及组装系统提示词的 get_ui_prompt()。
A2UI 消息的四类动作
Schema 规定一条 A2UI 消息必须且只能包含以下四个动作之一:
| 动作 | 作用 |
|---|---|
beginRendering |
通知客户端开始渲染一个 UI Surface,指定 surfaceId、根组件 root 与样式(font、primaryColor) |
surfaceUpdate |
用一组组件更新/新建某个 Surface(components 数组) |
dataModelUpdate |
更新 Surface 对应的数据模型(contents 键值数组,path 为可选定位,缺省或为 / 时整体替换) |
deleteSurface |
按 surfaceId 删除某个 Surface |
组件树:从 Text 到 Button 的完整组件体系
surfaceUpdate.components 中的每个组件都包含 id(组件唯一标识)、可选的 weight(对应 CSS flex-grow,仅当作为 Row/Column 的直接子级时允许设置)与 component(组件类型及其属性)。Schema 内置的组件类型包括:
- 基础展示:
Text(支持h1~h5、caption、body等usageHint)、Image(fit对应object-fit,usageHint支持icon/avatar/smallFeature/header等)、Icon、Video、AudioPlayer; - 布局容器:
Row/Column(children可用explicitList固定子级,或用template结合dataBinding动态生成)、List(vertical/horizontal)、Card、Tabs、Divider、Modal; - 交互组件:
Button(通过action.name与action.context派发客户端动作)、CheckBox、TextField(textFieldType支持shortText/longText/number/date/obscured,可配置validationRegexp)、DateTimeInput(enableDate/enableTime)、MultipleChoice、Slider。
所有字段的值既可以是字面量(literalString/literalNumber/literalBoolean/literalArray),也可以是数据模型路径引用(path,例如 /items/0/name),这使得同一套组件树可以复用动态数据。
四种内置 UI 模板
RESTAURANT_UI_EXAMPLES 为 LLM 预置了四种可直接套用的 UI 模板,并在提示词中约定了选择规则:
- SINGLE_COLUMN_LIST_EXAMPLE(单列列表):餐厅数量 ≤ 5 时使用,通过
List+template把/items数据绑定渲染为垂直卡片流; - TWO_COLUMN_LIST_EXAMPLE(双列列表):餐厅数量 > 5 时使用,用
Row排布多张卡片; - BOOKING_FORM_EXAMPLE(预订表单):收到预订意图时使用,包含
TextField(人数、饮食需求)与DateTimeInput(日期时间)等; - CONFIRMATION_EXAMPLE(确认页):预订提交后生成确认卡片,展示订座详情。
提示词中要求 LLM 的输出必须用分隔符
---a2ui_JSON---拆成两部分:前半部分是对话文本,后半部分是"符合 Schema 的 A2UI 消息 JSON 数组"。如果你要复用到其他业务(如机票预订),只需替换示例模板,get_ui_prompt()函数本身可以原样复用。
服务端如何校验与纠错
agent/agent.py 的 stream() 方法实现了"生成 → 校验 → 重试"的稳健机制:
- 将
A2UI_SCHEMA解析后包装为数组校验器({"type": "array", "items": single_message_schema}); - 解析 LLM 输出,剥离
---a2ui_JSON---分隔符与可能的 ```json 代码围栏; - 用
json.loads检查 JSON 可解析性,再用jsonschema.validate对照 Schema 校验; - 校验失败时自动重试(
max_retries = 1,即最多 2 次尝试),并携带失败原因重新提示 LLM 严格遵循 Schema; - 重试耗尽仍未通过时,降级返回文本错误消息,避免前端收到损坏的 UI 数据。
理解 A2UI 客户端事件:从"点击按钮"到"Agent 响应"
A2UI 的双向性体现在 agent_executor.py(examples/integrations/a2a-a2ui/agent/agent_executor.py)中。它根据客户端是否声明了 A2UI 扩展(try_activate_a2ui_extension)选择使用"UI 版 Agent"还是"纯文本 Agent",同时解析消息中的 DataPart:
- 若
DataPart中包含userAction(即客户端 UI 事件),则按actionName分发:book_restaurant→ 组装USER_WANTS_TO_BOOK: ...查询,携带restaurantName、address、imageUrl上下文;submit_booking→ 组装User submitted a booking for ...查询,携带人数、时间、饮食需求;
- 否则回退到
context.get_user_input()的纯文本输入。
最终响应会根据任务类型设置不同的任务终态:提交预订后为 TaskState.completed,其余场景为 TaskState.input_required(等待用户继续操作),并调用 create_a2ui_part() 把每个 A2UI 消息封装为独立的 DataPart 下发给前端。
常见问题排查(Troubleshooting)
Agent 连接问题
如果前端出现 "I'm having trouble connecting to my tools",依次检查:
- ADK Agent 是否运行在 10002 端口——该端口在 route.tsx 的
new A2AClient("http://localhost:10002")与 agent/main.py 的默认端口参数中均有硬编码约定; - Gemini API Key 是否配置正确——确认 agent/.env 中的
GEMINI_API_KEY已填写; - 两个服务器是否都启动成功——用
npm run dev同时观察ui与agent两个进程的输出。
Python 依赖问题
如果遇到 Python import 错误,可进入 agent 目录手动同步依赖并启动:
cd agent
uv sync
uv run .
模板文件的阅读路线图
| 文件(仓库相对路径) | 作用 |
|---|---|
| examples/integrations/a2a-a2ui/README.md | 模板总览、快速开始与排查指南 |
| examples/integrations/a2a-a2ui/package.json | npm 脚本与前端依赖清单 |
| examples/integrations/a2a-a2ui/app/page.tsx | 前端聊天界面入口(CopilotChat 挂载点) |
| examples/integrations/a2a-a2ui/app/api/copilotkit/[[...slug]]/route.tsx | CopilotRuntime 与 A2A Agent 的桥接路由 |
| examples/integrations/a2a-a2ui/agent/agent.py | 餐厅 Agent 主体(含 A2UI 校验与重试逻辑) |
| examples/integrations/a2a-a2ui/agent/prompt_builder.py | A2UI Schema、UI 模板示例与提示词组装 |
| examples/integrations/a2a-a2ui/agent/agent_executor.py | A2A 事件解析与 UI 客户端动作分发 |
| examples/integrations/a2a-a2ui/agent/tools.py | get_restaurants 工具实现 |
| examples/integrations/a2a-a2ui/agent/main.py | A2A 服务器装配(AgentCard、CORS、静态资源) |
| examples/integrations/a2a-a2ui/a2ui_extension/src/a2ui/a2ui_extension.py | A2UI 扩展定义与 create_a2ui_part 封装 |
如何扩展到其他业务场景
这个模板的设计目标是"易于扩展"(Starter 定位)。将其迁移到其他业务(例如机票预订、酒店查询)时,核心步骤如下:
- 在 agent/tools.py 中新增领域工具,并注册到 agent/agent.py 的
LlmAgent(tools=[...]); - 在 agent/prompt_builder.py 中按新场景编写 UI 模板示例,并更新
get_ui_prompt()中的模板选择规则; - 如需新的按钮动作(如
book_flight),在 agent_executor.py 的userAction分发逻辑中增加对应分支; - 保持
A2UI_SCHEMA不变——它描述的是通用 A2UI 协议能力,与具体业务解耦。
模板整体遵循 MIT 许可证,你可以自由提交 issue 与功能建议。本仓库中还有更多相关实现可以参考,例如 examples/integrations/a2a-middleware、examples/integrations/agent-spec 等集成示例,以及 packages/a2ui-renderer 中关于 A2UI 渲染器在前端的具体实现。