CopilotKit + A2A + A2UI 实战:用 AG-UI 协议构建可动态渲染 UI 的餐厅预订 Agent

原创2026-09-09 19:44:041,981 阅读
文章标签:人工智能AI 应用AI Agent交互助手工具调用前端UI组件Agent 框架移动开发后端WebSocket

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)约定了三段式业务逻辑:

  1. 查找餐厅:必须调用 get_restaurants 工具,从用户输入中提取 cuisine、location 与数量 count;
  2. 预订:收到形如 USER_WANTS_TO_BOOK... 的查询时,生成预订表单 UI;
  3. 确认:收到 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 模板,并在提示词中约定了选择规则:

  1. SINGLE_COLUMN_LIST_EXAMPLE(单列列表):餐厅数量 ≤ 5 时使用,通过 List + template 把 /items 数据绑定渲染为垂直卡片流;
  2. TWO_COLUMN_LIST_EXAMPLE(双列列表):餐厅数量 > 5 时使用,用 Row 排布多张卡片;
  3. BOOKING_FORM_EXAMPLE(预订表单):收到预订意图时使用,包含 TextField(人数、饮食需求)与 DateTimeInput(日期时间)等;
  4. CONFIRMATION_EXAMPLE(确认页):预订提交后生成确认卡片,展示订座详情。

提示词中要求 LLM 的输出必须用分隔符 ---a2ui_JSON--- 拆成两部分:前半部分是对话文本,后半部分是"符合 Schema 的 A2UI 消息 JSON 数组"。如果你要复用到其他业务(如机票预订),只需替换示例模板,get_ui_prompt() 函数本身可以原样复用。

服务端如何校验与纠错

agent/agent.py 的 stream() 方法实现了"生成 → 校验 → 重试"的稳健机制:

  1. 将 A2UI_SCHEMA 解析后包装为数组校验器({"type": "array", "items": single_message_schema});
  2. 解析 LLM 输出,剥离 ---a2ui_JSON--- 分隔符与可能的 ```json 代码围栏;
  3. 用 json.loads 检查 JSON 可解析性,再用 jsonschema.validate 对照 Schema 校验;
  4. 校验失败时自动重试(max_retries = 1,即最多 2 次尝试),并携带失败原因重新提示 LLM 严格遵循 Schema;
  5. 重试耗尽仍未通过时,降级返回文本错误消息,避免前端收到损坏的 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",依次检查:

  1. ADK Agent 是否运行在 10002 端口——该端口在 route.tsx 的 new A2AClient("http://localhost:10002") 与 agent/main.py 的默认端口参数中均有硬编码约定;
  2. Gemini API Key 是否配置正确——确认 agent/.env 中的 GEMINI_API_KEY 已填写;
  3. 两个服务器是否都启动成功——用 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 定位)。将其迁移到其他业务(例如机票预订、酒店查询)时,核心步骤如下:

  1. 在 agent/tools.py 中新增领域工具,并注册到 agent/agent.py 的 LlmAgent(tools=[...]);
  2. 在 agent/prompt_builder.py 中按新场景编写 UI 模板示例,并更新 get_ui_prompt() 中的模板选择规则;
  3. 如需新的按钮动作(如 book_flight),在 agent_executor.py 的 userAction 分发逻辑中增加对应分支;
  4. 保持 A2UI_SCHEMA 不变——它描述的是通用 A2UI 协议能力,与具体业务解耦。

模板整体遵循 MIT 许可证,你可以自由提交 issue 与功能建议。本仓库中还有更多相关实现可以参考,例如 examples/integrations/a2a-middleware、examples/integrations/agent-spec 等集成示例,以及 packages/a2ui-renderer 中关于 A2UI 渲染器在前端的具体实现。

登录后查看全文
CopilotKit