• AI应用
• 移动开发

AGenUI 是一个面向 iOS / Android / HarmonyOS 的 Native A2UI 渲染引擎，而agent_sdks/go目录下的Go Agent SDK正是它的「服务端大脑」。它让 Go 编写的 Agent 能够生成符合 A2UI 协议的 UI、对 LLM 输出做流式解析、并在下发前完成严格校验，从而把大模型的文本输出，实时变成任意 A2UI 客户端都能渲染的富交互界面。本文将带你用一条完整管线，跑通「UI 生成 → 流式解析 → 校验」三步。

AGenUI Go Agent SDK 是什么？为什么需要它

一句话概括：它是 LLM 后端与任意 A2UI 前端渲染器之间的桥梁。

A2UI（Agent-to-UI）协议定义了一种标准方式，让 AI Agent 生成丰富、可交互的用户界面。Go Agent SDK 聚焦在「服务端要做的四件事」：

• 生成结构化 UI 响应— 产出createSurface、updateComponents、updateDataModel、deleteSurface等 A2UI 消息，供 Android / iOS / HarmonyOS / Web 等任何合规渲染器显示。
• 增量流式渲染 UI— 在 LLM 逐 token 输出的同时，实时解析并吐出「部分」UI 组件，实现低延迟的渐进式渲染。
• 校验输出— 用 JSON Schema + 协议规则（拓扑、可达性、循环引用、递归深度）拦截错误，避免脏数据到达客户端。
• 管理组件目录（Catalog）— 加载内置或自定义 Catalog，生成能教会模型「有哪些组件、怎么用」的系统提示词。

💡 设计精髓：A2UI 是声明式 + 数据驱动的——UI 是数据状态的直接函数，组件用path绑定数据模型。这正是服务端只需下发「组件 + 数据」即可驱动整屏渲染的原因。

服务端 UI 生成：让 LLM 按规范输出 A2UI 组件

第一步是「教模型」。核心入口是 a2ui.go，它定义了SystemPromptOptions选项结构与InferenceStrategy接口；真正实现提示词装配的是 manager.go 中的A2uiSchemaManager.GenerateSystemPrompt。

它把几段内容拼成最终的 LLM 系统提示词（manager.go#L255-L293）：

1. 角色描述（RoleDescription）
2. 工作流描述（默认规则DefaultWorkflowRules+ 自定义WorkflowDescription）
3. UI 描述（UIDescription）
4. Schema 指令（RenderAsLLMInstructions，把 JSON Schema 转成模型可读说明）
5. 示例（LoadExamples，注入目录的示例组件）

组件目录（Catalog）由 catalog.go 的A2uiCatalog承载，而标准基础目录（Button、Text、Row、Column 等）则由 basiccatalog.go 的BundledCatalogProvider从内嵌资源加载——Schema JSON 通过go:embed打包进二进制，运行时无需额外文件。

一个关键细节：模型必须把 JSON 包在<a2ui-json>与</a2ui-json>标签中，并且根组件必须排在components列表第一位、父组件先于子组件（Top-Down Ordering）。这套约定直接服务于后续的流式解析。

流式解析：边生成边渲染的低延迟管线

这是整个 SDK 最精彩的部分。parser.go 提供ParseResponse做同步解析（适合拿到完整响应）；而真正的实时能力在 streaming.go 的A2uiStreamParser中，入口是ProcessChunk（streaming.go#L230）。

它做了一件困难的事：在 JSON 还没写完、大模型还在吐 token 的时候，就把「已经能确定的组件」先解析出来交给渲染器。

ProcessChunk的三大能力：

• JSON 自愈（Healing）。模型输出常带「尾部逗号、智能引号、未闭合括号」等毛病。解析器用fixJSON自动补全括号、闭合字符串，并通过 payload_fixer.go 的ParseAndFix修复尾部逗号。注意：只有CuttableKeys（如text、label、hint）这类可安全截断的字符串字段才会被自动补全，结构性字段（id、surfaceId、path）绝不会被误修。
• 组件级 yield。sniffPartialComponent不断探测缓冲区里「已成形的组件」，handlePartialComponent缓存后标记topologyDirty；随后yieldReachable调用AnalyzeTopology做拓扑可达性分析，把从根节点可达的组件打包下发。还没到的子组件会插入loading_xxx占位组件，渲染器先显示骨架、到齐后再替换。
• 安全护栏。jsonBuffer超过10 MB仍未出现闭合标签时，解析器会resetJSONState防止畸形输出导致内存无限膨胀。

这套「先给骨架、再填内容」的策略，让客户端在第一个组件到达时就能开始布局，极大降低了感知延迟。

校验管线：JSON Schema + 协议完整性双重把关

流式下发的每个片段，都会先过一遍校验器 validator.go。A2uiValidator.Validate（validator.go#L136）对 v0.9 协议执行两阶段检查：

• 第一阶段 · JSON Schema 校验。用jsonschema编译器把 server-to-client、catalog、common_types 三类 Schema 注册为资源，对每条消息按createSurface/updateComponents/updateDataModel/deleteSurface逐一匹配$defs子模式，逐字段报错。
• 第二阶段 · 完整性检查。ValidateComponentIntegrity+AnalyzeTopology检查组件 ID 引用、拓扑可达性、循环引用、自引用，ValidateRecursionAndPaths则限制函数调用深度（MaxFuncCallDepth = 5）与全局递归深度（MaxGlobalDepth = 50），并校验松约束 path 模式。

// 校验一条 A2UI 消息：rootID 为根组件，strictIntegrity 决定是否严格要求无孤儿节点 if err := validator.Validate(a2uiJSON, rootID, strictIntegrity); err != nil { return err // 返回「Validation failed: ...」聚合错误 }

在流式场景下，校验器以「非严格」模式运行——能确定有效的组件先放行，可疑片段只打日志跳过，从而兼顾速度与稳健。

完整示例：用 rizzcharts 电商看板串联整条管线

仓库内置了一个完整可运行的 Go 示例 samples/go/rizzcharts，它是一个通过 A2A（JSON-RPC）协议对外提供电商数据可视化的 Agent。它的三个文件恰好对应管线的三段：

运行流程一气呵成：buildSystemPrompt用A2uiSchemaManager装配提示词 →agent.Chat驱动 LLM 与工具循环 →parseA2UIFromText提取并解析<a2ui-json>块 → 以 A2A data part 返回。

其中自定义组件目录与示例分别在：

• 组件目录定义：rizzcharts_catalog_definition.json
• 图表 / 地图示例：chart.json、map.json

chart.json正是前文三步的「成品」——一个createSurface建表面、updateComponents声明Canvas → Column → Chart组件树（根组件root排第一）、updateDataModel绑定/chart.items数据，最终渲染成可交互的环形图。

一键安装与运行步骤

1. 拉取仓库（Go SDK 位于agent_sdks/go）

git clone https://gitcode.com/gh_mirrors/ag/AGenUI cd AGenUI

2. 安装 SDK 依赖

go get github.com/AGenUI/AGenUI/agent_sdks/go

3. 运行示例（需要 Go 1.22+ 与一个 OpenAI 兼容的 API Key）

在 samples/go/rizzcharts 下创建.env填入OPENAI_API_KEY/OPENAI_API_BASE/LITELLM_MODEL（或 Gemini 变量），然后：

cd samples/go/rizzcharts go run .

服务将启动在http://localhost:10002，可访问/.well-known/agent-card.json获取能力清单，或POST /发送message/send消息。

4. 跑测试（SDK 自带完善的单测与一致性测试）

cd agent_sdks/go go test ./...

目录结构与核心模块速览

快速定位代码，以下是最值得先读的模块：

• 包入口：a2ui.go —Version、SystemPromptOptions、InferenceStrategy
• Schema 管理：schema/ —A2uiSchemaManager（提示词）、A2uiValidator（校验）、A2uiCatalog（目录）、内嵌 Schema 资源
• 解析器：parser/ —ParseResponse（同步）、A2uiStreamParser（流式）、payload_fixer（自愈）、ResponsePart（结果结构）
• 基础目录：basiccatalog/ — 标准 A2UI 组件目录加载
• 官方说明：README.md、README.zh-CN.md

小结

AGenUI Go Agent SDK 把「让大模型生成 UI」这件容易踩坑的事，拆成了职责清晰、层层设防的三段管线：

1. UI 生成—— 用A2uiSchemaManager生成含 Schema + 示例的系统提示词，让模型输出「根优先、父先子后」的规范 A2UI；
2. 流式解析——A2uiStreamParser边收 token 边自愈 JSON、边做拓扑可达性分析、边插入占位组件，实现「先到先渲染」；
3. 校验管线——A2uiValidator用 JSON Schema + 完整性检查，在数据下发前拦截结构错误、循环引用与深层递归。

对 Go 开发者来说，这套 SDK 意味着你无需关心渲染细节，只需专注「业务意图 → A2UI 组件」的映射，就能把 LLM 的能力，低延迟、高可靠地送达任意平台的原生界面。

• AI应用
• 移动开发