创建日期：2026-10-20 ｜ 最近更新：2026-10-20 基准：A2UI v0.9.1（0.9 协议族当前生产版本），仓库 a2ui-project/a2ui commit
ba4c47b（2026-10-19）。协议细节见「笔记 → A2UI」系列：入门。
A2UI 初期问题
这里收集上手 A2UI 时最先卡住的问题。先从「到底要不要自己写」开始。
Q1：客户端和 Agent 需要自己实现吗？允许自行实现吗？
一句话：不是必须从零实现，但 Agent 侧和客户端侧都至少要有「一个实现」；官方提供了可用的 SDK 和渲染器，也明确允许你自己实现。
需要拆开看的是：A2UI 不是一个托管服务，也不是一个开箱即用的聊天产品。它是一套协议 + 参考实现。协议规定消息长什么样、数据怎么绑定、交互怎么回传；至于「谁来生成」「谁来渲染」，协议不强制指定厂商或框架。
1. 先分清「客户端」和「Agent」各包含什么
很多时候「要不要自己实现」之所以难回答，是因为把两层东西混在一起了。
客户端侧实际有两层：
| 层 | 职责 | 谁来提供 |
|---|---|---|
| Host App（宿主应用） | 聊天窗口、surface 放在哪、登录/鉴权、传输连接、产品交互 | 永远是你自己，A2UI 不提供 |
| Renderer（渲染器） | 解析 A2UI 消息、管理 surface/组件树/数据模型、把抽象组件映射成原生控件、回传 action | 官方渲染器，或你自己实现 |
所以即使你用官方 React/Lit/Angular 渲染器，宿主应用仍然要自己写。官方渲染器是「组件库 + 协议引擎」，不是一个完整的聊天产品。
Agent 侧同样有两层：
| 层 | 职责 | 谁来提供 |
|---|---|---|
| Agent 逻辑 | 理解用户意图、决定展示什么 UI、调用工具、处理 action | 你自己（可以用任意 LLM / Agent 框架，甚至确定性代码） |
| Agent SDK | 把 Catalog 转成提示词、解析模型输出、校验成 A2UI 消息 | 可选；官方有 Python / Dart SDK，TS 版尚未发布 |
关键一句来自官方 Agent 开发指南：
The agent SDK does not depend on an agent framework.
也就是说，SDK 只是帮你做「Catalog → prompt」和「模型输出 → A2UI JSON」这两件脏活，不绑定 ADK、LangGraph、CrewAI 等任何框架。你完全可以不用它，自己拼提示词、自己解析 JSON。
2. 四种组合都成立
| 组合 | 可行性 | 适用场景 |
|---|---|---|
| 官方 Renderer + 官方 Agent SDK | ✅ 最省事 | 快速验证、标准 Web/Flutter 界面 |
| 官方 Renderer + 自己的 Agent | ✅ 很常见 | 已有 Agent 框架，只想让它「会说 A2UI」 |
| 自己的 Renderer + 官方 Agent SDK | ✅ 可行 | 自定义设计系统、非官方支持的平台 |
| 两边都自己写 | ✅ 允许 | 深度定制、特殊运行时；工作量最大 |
「允许自行实现吗」的答案是允许，而且不是灰色地带：
- 仓库采用 Apache 2.0 许可证；
- 官方专门写了 Renderer Development Guide，开头就是「给新渲染器实现者的必备功能清单」；
- 官方专门写了 Defining Your Own Catalog，明确说「大多数生产应用会定义自己的 Catalog」；
- Renderers 参考页的原话是：
You have a lot of flexibility, to bring custom components to a renderer, or build your own renderer to support your UI component framework.
- 仓库还有一套语言无关的 conformance 测试套件，用来保证不同 SDK 的行为一致，你可以拿它自测。
3. 截至 2026-10-20，官方现成的东西有哪些
渲染器（来自 docs/public/reference/renderers.md）：
| 平台 | 渲染器 | v0.9.1 状态 |
|---|---|---|
| Web | React (@a2ui/react) | ✅ Stable |
| Web | Lit (@a2ui/lit) | ✅ Stable |
| Web | Angular (@a2ui/angular) | ✅ Stable |
| Mobile/Desktop/Web | Flutter（GenUI SDK） | ✅ Stable |
| Android | Jetpack Compose | 🟡 Alpha |
| iOS/macOS | SwiftUI | 🚧 Planned |
Web 端还有一个关键底座：@a2ui/web_core。它把消息处理、surface 状态、数据绑定、组件树、表达式求值都做完了。官方渲染器开发指南的建议很直接：
Building a web renderer without
web_coremeans reimplementing ~3,000 lines of message processing, state management, and schema validation. Unless you have a specific reason to diverge, use it.
所以「自己写 Web 渲染器」的合理姿势通常是：复用 web_core，只写组件映射和宿主集成，而不是从 JSONL 解析开始重写协议。
Agent SDK（来自 README 的 Packages 表）：
| 语言 | 包 | 状态 |
|---|---|---|
| Python | a2ui-agent-sdk | ✅ 已发布 PyPI |
| Python | a2ui-core | ✅ 已发布 PyPI |
| TypeScript | @a2ui/agent | ⏳ 尚未发布 |
| Dart | a2ui_agent | ✅ 已发布 pub |
| Python A2A / ADK 集成 | a2ui-a2a / a2ui-adk | ⏳ 尚未发布 |
注意：Agent SDK 未发布不代表不能做 Agent。协议只要求模型能生成符合 schema 的 JSON；官方也明确说任何能输出 JSON 的模型都可以。SDK 的价值是减少提示词拼装和解析的重复劳动。
4. 如果自己实现，工作量大在哪
Agent 侧
最小闭环是：
- 把目标 Catalog 的 schema、组件说明、几个合法示例拼进系统提示词；
- 让模型输出 A2UI JSON（通常是一个 JSON 数组或 JSONL）；
- 解析模型输出（处理 Markdown 代码围栏、截断、多余解释文字）；
- 用
server_to_client.json+ Catalog schema 校验； - 校验失败时，把标准错误格式喂回模型自纠；
- 通过 A2A / AG-UI / SSE / WebSocket 流式发给客户端；
- 接收
action，执行业务逻辑，再发updateComponents/updateDataModel。
官方 Python SDK 的 DirectJsonFormat 做的就是第 1、3 步的一部分；校验、传输、action 处理仍然要你接。
Renderer 侧
官方渲染器开发指南列出的 v0.9.1 必备能力：
- JSONL / 分帧解析与消息分发（
createSurface/updateComponents/updateDataModel/deleteSurface）； - 校验
application/a2ui+jsonMIME； - 按 surface 管理组件缓冲、
root到达后建树、支持渐进渲染； - 数据模型与 JSON Pointer 绑定、模板列表展开；
- 客户端函数求值（
required、regex、formatString等）； - 双向绑定、
checks、action回传、sendDataModel； - 校验失败时发
VALIDATION_FAILED； - 把抽象组件映射成原生控件。
如果平台是 Web，强烈建议用 web_core 承担前七项；如果是 Flutter，用 GenUI SDK 的 core。真正需要你从零写的，通常是「组件映射 + 宿主应用 + 设计系统」，而不是协议状态机。
5. 「自行实现」的边界：可以自己写，但不能自己改协议
允许自行实现，不等于可以随意发明消息格式。要能和别人的 Agent/渲染器互操作，至少要对齐：
- 消息 schema：
server_to_client.json/client_to_server.json/common_types.json； - Catalog：双方必须认识同一个
catalogId和同一份组件/函数定义； - 版本：v0.9 与 v0.9.1 兼容，但 v0.8 与 v0.9 不兼容；
- 安全模型：只渲染 Catalog 白名单里的组件，不执行任意代码。
这也是为什么 catalogId 只是一个「约定标识符」，不是运行时下载地址：两边都得在编译/部署时就知道这份 Catalog。你自己实现渲染器时，真正要对齐的是这份 schema，而不是某个官方 SDK 的内部 API。
6. 给你的落地建议
按「先跑通，再替换」的顺序最省力：
- 先跑官方最小闭环：官方 Quickstart 是 Gemini + ADK Agent + Lit 渲染器；它不代表唯一路径，但能让你在 5 分钟内看到完整数据流。
- 保留官方渲染器，替换 Agent：如果你的 Agent 已经存在，先让它输出 basic catalog 的 JSON，客户端直接用
@a2ui/react/@a2ui/lit/@a2ui/angular。 - 要贴自己的设计系统时，再自定义 Catalog：定义自己的组件 schema，写组件映射；Web 端继续复用
web_core。 - 只有平台没有官方渲染器时，才考虑从零写 Renderer：先对照 Renderer Development Guide 和 conformance 用例，别一上来就重写协议层。
- 无论哪条路，都先锁定 v0.9.1：v1.0 还是 RC，当前生产基线是 0.9.1。
7. 一句话回答
- 需要自己实现吗？ 不一定。官方有 React/Lit/Angular/Flutter 渲染器和 Python/Dart Agent SDK；但宿主应用、Agent 业务逻辑、Catalog 设计仍然是你的事。
- 允许自行实现吗？ 允许，而且官方鼓励：Apache 2.0、公开 schema、渲染器开发指南、自定义 Catalog 指南、conformance 套件都摆在那。
- 最容易踩的坑：把「用官方渲染器」当成「客户端不用写」，或者把「用 Agent SDK」当成「Agent 不用写」。两者都只是省掉了协议层的一部分，不是整条链路。
来源
| 材料 | 链接 |
|---|---|
| README（包与状态） | README.md |
| 渲染器清单与状态 | reference/renderers.md |
| 渲染器开发指南 | guides/renderer-development.md |
| Agent 开发指南 | guides/agent-development.md |
| 自定义 Catalog | guides/defining-your-own-catalog.md |
| Conformance 套件 | conformance/README.md |
| 许可证 | LICENSE（Apache 2.0） |