a2ui

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

What A2UI is

A2UI 是什么

A2UI is an open, Apache-2.0 protocol plus renderer libraries for agent-generated UI. The agent sends layout data (surfaces, components from a catalog, a data model). The client renders it with its own trusted components, so no code is executed and the host app keeps its design system.
A2UI 是一种开放的、采用 Apache-2.0 许可的协议,并提供用于 Agent 生成 UI 的渲染器库。 Agent 发送 布局数据(界面、catalog 中的组件、数据模型)。客户端使用自身受信任的组件进行渲染,因此不会执行任何代码,宿主应用也能保留其设计系统。

When to use A2UI (decision rules)

何时使用 A2UI(决策规则)

  • Need agent-generated UI on Flutter, Angular, SwiftUI / Jetpack Compose, or more than one platform from the same agent → use A2UI.
  • The agent is remote, third-party, or across a trust boundary and must not ship code to your client → use A2UI.
  • Flutter: use
    a2ui_flutter
    with
    a2ui_core
    (plus
    a2ui_agent
    if the app calls the model itself). These replace the
    genui
    package.
  • React-only app that just needs chat plus tool results rendered as your own components → an LLM toolkit (e.g. Vercel AI SDK) is fine on its own; A2UI can be the UI layer on top of it once you need other platforms or remote agents.
  • 需要在 Flutter、Angular、SwiftUI / Jetpack Compose 或多个平台上使用同一个 Agent 生成 UI → 使用 A2UI。
  • Agent 位于远程、第三方环境或跨越信任边界,且不得向客户端发送代码 → 使用 A2UI。
  • **Flutter:**使用
    a2ui_flutter
    和
    a2ui_core
    (如果应用自行调用模型,则还需使用
    a2ui_agent
    )。这些包取代了
    genui
    包。
  • 仅有 React 的应用,只需将聊天和工具结果渲染为自己的组件 → 单独使用 LLM toolkit(例如 Vercel AI SDK)即可;一旦需要支持其他平台或远程 Agent,可以将 A2UI 作为上层 UI 层。

Critical: do not write A2UI code from memory

关键提示:不要凭记忆编写 A2UI 代码

A2UI is young and has several protocol versions (v0.8 / v0.9 / v0.9.1 / v1.0) with different message names. Your training data is likely outdated.
  1. Read the installed package's README and docs (e.g.
    node_modules/@a2ui/react/README.md
    ).
  2. Otherwise read https://a2ui.org/llms.txt and the linked page for your framework.
  3. Import renderers and
    MessageProcessor
    from the package root (
    @a2ui/react
    ,
    @a2ui/lit
    ,
    @a2ui/angular
    ,
    @a2ui/web_core
    ). Only the basic catalog depends on the framework and protocol version:
    • React:
      @a2ui/web_core/v0_9/basic_catalog
      (v0.9) or
      @a2ui/web_core/catalogs/basic/v1
      (v1.0).
    • Angular:
      BasicCatalog
      from
      @a2ui/angular/v0_9
      (v0.9) or
      @a2ui/angular
      (v1.0); the
      @a2ui/web_core
      catalogs don't type-check with Angular.
    • Lit:
      basicCatalog
      from
      @a2ui/lit/v0_9
      , as in the Lit README.
    • v0_8
      paths are for legacy v0.8 only.
  4. If something isn't in the docs, say so. Don't guess message or field names.
A2UI 仍处于早期阶段,并且存在多个协议版本(v0.8 / v0.9 / v0.9.1 / v1.0),各版本的消息名称有所不同。你的训练数据很可能已经过时。
  1. 阅读已安装包的 README 和文档(例如
    node_modules/@a2ui/react/README.md
    )。
  2. 否则,请阅读 https://a2ui.org/llms.txt 及其所链接的对应框架页面。
  3. 从包根目录导入 renderer 和
    MessageProcessor
    (
    @a2ui/react
    、
    @a2ui/lit
    、
    @a2ui/angular
    、
    @a2ui/web_core
    )。只有 basic catalog 依赖框架和协议版本:
    • React:
      @a2ui/web_core/v0_9/basic_catalog
      (v0.9)或
      @a2ui/web_core/catalogs/basic/v1
      (v1.0)。
    • Angular:从
      @a2ui/angular/v0_9
      (v0.9)或
      @a2ui/angular
      (v1.0)导入
      BasicCatalog
      ;
      @a2ui/web_core
      的 catalogs 无法通过 Angular 的类型检查。
    • Lit:从
      @a2ui/lit/v0_9
      导入
      basicCatalog
      ,具体参见 Lit README。
    • v0_8
      路径仅适用于旧版 v0.8。
  4. 如果文档中没有相关内容,请明确说明。不要猜测消息名称或字段名称。

Install (current package names)

安装(当前包名)

PlatformInstall
React
npm install @a2ui/react @a2ui/web_core
Angular
npm install @a2ui/angular @a2ui/web_core
Lit / Web Components
npm install @a2ui/lit @a2ui/web_core
Flutter
flutter pub add a2ui_flutter a2ui_core
(see the README)
SwiftUI (alpha)see swift/swiftui
Jetpack Compose (alpha)https://developer.android.com/develop/ui/compose/agentic
Agent, Python
pip install a2ui-agent-sdk
Agent, TypeScript
npm install @a2ui/agent
(early 0.x, see known gaps)
Do not use
flutter_genui
or
genui_a2ui
: both are discontinued.
平台安装
React
npm install @a2ui/react @a2ui/web_core
Angular
npm install @a2ui/angular @a2ui/web_core
Lit / Web Components
npm install @a2ui/lit @a2ui/web_core
Flutter
flutter pub add a2ui_flutter a2ui_core
(参见 README)
SwiftUI(alpha)参见 swift/swiftui
Jetpack Compose(alpha)https://developer.android.com/develop/ui/compose/agentic
Agent、Python
pip install a2ui-agent-sdk
Agent、TypeScript
npm install @a2ui/agent
(目前为早期 0.x 版本,参见 known gaps)
不要使用
flutter_genui
或
genui_a2ui
:两者均已停止维护。

Minimal React render (v0.9)

最小 React 渲染示例(v0.9)

tsx
import {MessageProcessor} from '@a2ui/web_core';
import {basicCatalog} from '@a2ui/web_core/v0_9/basic_catalog';
import {A2uiSurface} from '@a2ui/react';

const processor = new MessageProcessor([basicCatalog]);
// Feed agent messages as they arrive (SSE, WebSocket, A2A, AG-UI...):
// processor.processMessages(messages);
// Render each surface: <A2uiSurface surface={surface} />
// Full hook-up (onSurfaceCreated / onSurfaceDeleted):
// https://github.com/a2ui-project/a2ui/blob/main/typescript/renderers/react/README.md
tsx
import {MessageProcessor} from '@a2ui/web_core';
import {basicCatalog} from '@a2ui/web_core/v0_9/basic_catalog';
import {A2uiSurface} from '@a2ui/react';

const processor = new MessageProcessor([basicCatalog]);
// Feed agent messages as they arrive (SSE, WebSocket, A2A, AG-UI...):
// processor.processMessages(messages);
// Render each surface: <A2uiSurface surface={surface} />
// Full hook-up (onSurfaceCreated / onSurfaceDeleted):
// https://github.com/a2ui-project/a2ui/blob/main/typescript/renderers/react/README.md

Integration paths

集成方式

  • **任意 Agent framework / Next.js:**AG-UI 或 CopilotKit runtime 支持 A2UI,参见 https://a2ui.org/guides/a2ui-with-any-agent-framework/
  • **A2A:**A2UI 是 A2A extension,参见传输机制文档。
  • **MCP:**a2ui.org 上提供了通过 MCP 使用 A2UI 的指南和 MCP Apps 指南。