A2UI — 用于 ADK 的 Agent-to-UI¶
A2UI 让你的智能体能够生成 真实的 UI —— 卡片、表单、图表、表格 —— 而不仅仅是文本。你的智能体输出结构化的 JSON，客户端上的渲染器将其转换为交互式组件。
它是传输无关的：A2UI 负载可以通过 A2A、MCP、REST、WebSocket 或任何其他协议传输。智能体描述要显示“什么”；客户端决定“如何”渲染它。
了解更多关于 A2UI 的信息
a2ui.org 提供了完整的规范、组件库、目录参考和渲染器文档。
快速入门¶
安装 SDK¶
1. 设置 Schema 管理器¶
A2uiSchemaManager 负责加载组件目录并生成系统提示词，教导 LLM 如何生成有效的 A2UI JSON。
from a2ui.core.schema.manager import A2uiSchemaManager
from a2ui.basic_catalog.provider import BasicCatalog
schema_manager = A2uiSchemaManager(
catalogs=[
BasicCatalog.get_config(
examples_path="examples",
),
],
)
注意
Schema 管理器将自动从传入的客户端请求中检测 A2UI 版本。如果你需要，也可以通过传递 version=VERSION_0_9 来显式设置版本。
提示
如果省略 catalogs 参数，Schema 管理器将使用由 A2UI 团队维护的基础目录 (Basic Catalog)，其中包含文本、卡片、按钮、图片等常用组件。你也可以创建包含特定领域组件的自定义目录，或者将基础目录与你自己的目录混合使用 —— 请参阅下文的高级模式。
2. 生成系统提示词¶
generate_system_prompt 方法将智能体的角色描述与 A2UI JSON schema 以及少样本 (few-shot) 示例相结合，以便 LLM 确切知道如何格式化其输出。
instruction = schema_manager.generate_system_prompt(
role_description="你是一个能够通过丰富的 UI 展示信息的得力助手。",
workflow_description="分析用户请求，并在适当时返回结构化 UI。",
ui_description="使用卡片进行摘要，使用表格进行比较，使用表单进行用户输入。",
include_schema=True,
include_examples=True,
allowed_components=["Heading", "Text", "Card", "Button", "Table"],
)
3. 创建你的 ADK 智能体¶
将生成的指令用作智能体的系统提示词：
from google.adk.agents.llm_agent import LlmAgent
agent = LlmAgent(
model="gemini-flash-latest",
name="ui_agent",
description="一个生成丰富 UI 响应的智能体。",
instruction=instruction,
)
4. 验证并流式传输 A2UI 输出¶
在将 LLM 的 JSON 输出发送到客户端之前，请务必进行验证。SDK 提供了解析、修复和验证工具：
from a2ui.core.parser.parser import parse_response
from a2ui.a2a import parse_response_to_parts
# 获取活动目录的验证器
selected_catalog = schema_manager.get_selected_catalog()
# 选项 A：手动解析 + 验证
response_parts = parse_response(llm_output_text)
for part in response_parts:
if part.a2ui_json:
selected_catalog.validator.validate(part.a2ui_json)
# 选项 B：返回 A2A Parts 的单行代码
parts = parse_response_to_parts(
llm_output_text,
validator=selected_catalog.validator,
fallback_text="这是我找到的内容。",
)
A2UI 负载被包装在 A2A DataPart 中，MIME 类型为 application/json+a2ui，以便渲染器可以识别它们：
from a2ui.a2a import create_a2ui_part
part = create_a2ui_part({"type": "Card", "props": {"title": "你好"}})
# → DataPart(data={...}, metadata={"mimeType": "application/json+a2ui"})
高级模式¶
动态目录¶
对于需要根据上下文提供不同 UI 组件的智能体（例如，数据查询使用图表，配置使用表单），可以在运行时解析目录并将其存储在会话状态中：
async def _prepare_session(self, context, run_request, runner):
session = await super()._prepare_session(context, run_request, runner)
# 从请求元数据中确定客户端能力
capabilities = context.message.metadata.get("a2ui_client_capabilities")
# 选择正确的目录
a2ui_catalog = self.schema_manager.get_selected_catalog(
client_ui_capabilities=capabilities
)
examples = self.schema_manager.load_examples(a2ui_catalog, validate=True)
# 存储在会话状态中供工具访问
await runner.session_service.append_event(
session,
Event(
actions=EventActions(
state_delta={
"system:a2ui_enabled": True,
"system:a2ui_catalog": a2ui_catalog,
"system:a2ui_examples": examples,
}
),
),
)
return session
自定义目录¶
你可以为特定领域的 UI 定义自己的组件目录：
from a2ui.core.schema.manager import CatalogConfig
schema_manager = A2uiSchemaManager(
catalogs=[
BasicCatalog.get_config(),
CatalogConfig.from_path(
name="my_dashboard_catalog",
catalog_path="catalogs/dashboard.json",
examples_path="catalogs/dashboard_examples",
),
],
)
多智能体编排¶
编排智能体可以汇总子智能体的 A2UI 能力，并在智能体卡片中发布它们：
from a2ui.a2a import get_a2ui_agent_extension
# 从子智能体收集目录 ID
supported_catalog_ids = set()
for subagent in subagents:
for extension in subagent_card.capabilities.extensions:
if extension.uri == "https://a2ui.org/a2a-extension/a2ui/v0.9":
supported_catalog_ids.update(
extension.params.get("supportedCatalogIds") or []
)
# 在编排器的 AgentCard 中发布
agent_card = AgentCard(
capabilities=AgentCapabilities(
extensions=[
get_a2ui_agent_extension(
supported_catalog_ids=list(supported_catalog_ids),
)
]
)
)
示例集¶
A2UI 仓库中包含你可以立即运行的 ADK 示例智能体：
| 示例 | 描述 |
|---|---|
| contact_lookup | 具有静态模式的简单智能体 —— 查找联系人并将结果显示为卡片 |
| restaurant_finder | 用于搜索和显示餐厅信息的静态模式智能体 |
| rizzcharts | 根据上下文选择图表组件的动态目录智能体 |
| orchestrator | 委托给子智能体并汇总 UI 能力的多智能体设置 |