@genkit-ai/a2ui

中文文档
0.7.0发布于 2026/11/04Apache-2.0TypeScriptESM + CJS零依赖近 30 天下载 4593

一个Genkit插件,通过模型中间软件提供A2UI(Agent-to-UI)流式UI协议支持.

中文使用文档
文档目录18 节
  1. 安装
  2. 快速启动
  3. 1. 在服务器上添加中间软件
  4. 2. 客户端表面
  5. 选项
  6. 处理用户动作
  7. 表单
  8. 招标人要求
  9. 自定义目录
  10. 目录格式
  11. 选项A:从 JSON 文件装入
  12. 备选案文B:内在定义
  13. 使用已注册目录
  14. 安全和信任边界
  15. 如何运作
  16. 1名代表
  17. 中间软件管道
  18. 许可证

@genkit-ai/a2ui (英语)

带来 Genkit 插件 A2UI (英语) ("UI代理"), a 运输-不可知,以JSON为主的流式UI协议,去源基特代理.

用编码代理? 先安装基因组JS技能.

npx skills add genkit-ai/skills --skill developing-genkit-js

它教你的代理人 现任Genkit JS APIs 和普通的gitchas. 其他语言的来源、人工安装和技能: 技能/技能。 。 。 .

由A2UI驱动的代理可以流出比流派更多. 它流出丰富,互动的UI 表面 客户端渐进制作的(卡片、列表、表格、按钮) 正如模型的反应。 整个服务器端集成是一个单一的模型 中间软件: 添加 a2ui() 给经纪人的 use 数组,没有其它变化.

状态:实验性.

安装

在您的工程中安装插件 :

npm i @genkit-ai/a2ui

要在浏览器中渲染表面, 您还需要一个渲染器及其 支持软件包。 A2UI 多个框架的船舶渲染器: @a2ui/lit, (中文(简体) ), @a2ui/react,以及 @a2ui/angular。实例 下面使用 Lit 渲染器:

npm i @a2ui/lit @a2ui/web_core @a2ui/markdown-it

您也会装入 材料符号已大纲 在客户端上的字体( 基本目录 Icon 组件使名称成为字体连接。 见 渲染器注释 见下文.

快速启动

1. 在服务器上添加中间软件

添加 a2ui() 给你的经纪人 use 阵列。 这是整个服务器侧设置.

import { genkit } from 'genkit/beta';
import { googleAI } from '@genkit-ai/google-genai';
import { a2ui } from '@genkit-ai/a2ui';

const ai = genkit({ plugins: [googleAI()] });

export const uiAgent = ai.defineAgent({
  name: 'uiAgent',
  model: 'googleai/gemini-flash-latest',
  system: 'You help users. Render UI when it is clearer than prose.',
  use: [a2ui()], // <- A2UI support (defaults to the bundled 'basic' catalog)
});

一发也一样 generate数字 :

const res = await ai.generate({
  prompt: 'Show me the weather in Tokyo',
  use: [a2ui()],
});

2. 客户端表面

@genkit-ai/a2ui/client 是浏览器安全( 没有节点依赖)。 假设 代理为 remoteAgent 从 genkit/beta/client,将 A2UI 信封各取出 块与 a2uiEnvelopesFromParts并供给造物主。 实例 以下用途 @a2ui/lit但还是一样 方法与 @a2ui/react 财务报告和审定财务报表 @a2ui/angular 渲染器:

import { MessageProcessor } from '@a2ui/web_core/v0_9';
import { basicCatalog } from '@a2ui/lit/v0_9';
import '@a2ui/lit/v0_9'; // registers <a2ui-surface> + basic components
import { a2uiEnvelopesFromParts } from '@genkit-ai/a2ui/client';
import { remoteAgent } from 'genkit/beta/client';

const processor = new MessageProcessor([basicCatalog]);
processor.onSurfaceCreated((s) => {
  document.querySelector('a2ui-surface').surface = s;
});

const chat = remoteAgent({ url: '/api/uiAgent' }).chat();
const turn = chat.sendStream('weather in Tokyo');
for await (const chunk of turn.stream) {
  if (chunk.text) appendProse(chunk.text);
  const envelopes = a2uiEnvelopesFromParts(chunk.raw.modelChunk?.content);
  if (envelopes.length) processor.processMessages(envelopes);
}

如果你没有使用完整的代理客户端, @genkit-ai/a2ui/client 船舶a 轻型 streamA2uiAgent({ url, message, sessionId }) 同步生成器帮助器 产量 { type: 'text' } 财务报告和审定财务报表 { type: 'envelopes' } 事件.

见 js/testapps/a2ui 用于完整、可运行的样本 (Express后端外加一维特+Lit前端).

选项

将选项传递到 a2ui() 控制目录,即时注射,以及 验证 :

选项默认说明
catalog'basic'描述代理商可能制作的目录的ID.
instructions'system'何处注入目录能力. 'none' 注射什么也没有.
validate'warn'对照目录验证所发射的信封 . 'warn' 日志和投放坏块; 'strict' 投掷; 'off' 跳过检查.
surfaceId新鲜UUID地表id政策. 默认为每个表面新建一个UUID;通过固定字符串来再利用每个表面的一个ID.
version'v0.9'协议版本印在信封上.

处理用户动作

当用户与表面交互时( 例如, 按 a) Button页:1 制造器发出一个 A2uiClientAction。将其变成代理输入 actionToMessage 并把它当作下一个转弯:

import { actionToMessage, type A2uiClientAction } from '@genkit-ai/a2ui/client';

const processor = new MessageProcessor([basicCatalog], (action) => {
  const turn = chat.sendStream({ message: actionToMessage(action) });
  // …consume turn.stream like above…
});

行动 name 作为用户信息发送; 全部动作(包括其 context)作为a2ui数据部分附后,使剂能与之反应.

表单

输入组件TextField, (中文(简体) ), CheckBox, (中文(简体) ), Slider这样做 没有 发送他们的值 自动。 要捕捉用户输入的内容,模型必须:

  1. 捆绑每个输入的 value 用于数据模型路径({ "path": "/email" }) (中文(简体) ).
  2. 重复提交中的相同路径 Button是因为 action.event.context。 。 。 .

输入系统的目录能力已指示 做这个的模型。 没有两步,动作就空了 context。 。 。 .

招标人要求

这个 @a2ui/lit 基本目录需要两个主机侧块才能完全渲染:

  • A 类 下调渲染器 通过 上下文(例如,由 @a2ui/markdown-it) (中文(简体) ). Text 标题变体作为Markdown提供.
  • 这个 材料符号已大纲 字体。 这个 Icon 组件将名称改为 字体连接.

没有它们,标题显示为文字 ## 图标以字面名称显示。 见 js/testapps/a2ui 为接线.

自定义目录

这个 catalog 选项是 目录编号 由基因组登记册解决。 这个 捆绑 'basic' 目录( mirroring) @a2ui/web_core基本目录)是 默认且不需要注册.

为了匹配自己的布局元素和设计系统,定义自定义目录, 注册到 loadCatalog,并引用代码.

目录格式

A2UI目录描述了允许该模型发射的组件:

  • id: 全球独一无二的URI 识别目录(作为 catalogId 打开 createSurface) (中文(简体) ).
  • components: 一组组件,每个组件都有:
    • name: 组件类型名称,匹配渲染器类型(例如) CustomCard, (中文(简体) ), Text) (中文(简体) ).
    • description:该组成部分是什么以及何时构成的明确、一行摘要 用这个.
    • props: 关于其属性的紧凑、模型化文本描述(按 一个简单的,人能读取的字符串,以尽量减少系统即时符号的使用.

选项A:从 JSON 文件装入

创建 JSON 文件( 例如) ./my-catalog.json遵循这一格式:

{
  "id": "https://my-app.org/catalogs/custom.json",
  "components": [
    {
      "name": "Banner",
      "description": "Displays a prominent alert banner at the top of a section.",
      "props": "title: string (required); severity?: info|warning|error."
    },
    {
      "name": "Text",
      "description": "Displays a plain or inline-markdown text run.",
      "props": "text: string (required); variant?: body|caption."
    }
  ]
}

然后在查询标识符下注册(例如) 'my-catalog') 上 时 间 服务器 :

import { loadCatalog } from '@genkit-ai/a2ui';

await loadCatalog(ai, { id: 'my-catalog', file: './my-catalog.json' });

备选案文B:内在定义

您可以构建和注册 A2uiCatalog 直接 :

import { loadCatalog, type A2uiCatalog } from '@genkit-ai/a2ui';

const myCatalog: A2uiCatalog = {
  id: 'https://my-app.org/catalogs/custom.json',
  components: [
    {
      name: 'Banner',
      description: 'Displays a prominent alert banner at the top of a section.',
      props: 'title: string (required); severity?: info|warning|error.',
    },
    {
      name: 'Text',
      description: 'Displays a plain or inline-markdown text run.',
      props: 'text: string (required); variant?: body|caption.',
    },
  ],
};

await loadCatalog(ai, { id: 'my-catalog', catalog: myCatalog });

使用已注册目录

注册后,请参考您 a2ui() 选项:

export const uiAgent = ai.defineAgent({
  name: 'uiAgent',
  model: 'googleai/gemini-flash-latest',
  use: [a2ui({ catalog: 'my-catalog' })],
});

登记簿中的目录(数值类型) a2ui-catalog所以中间的软件可以 通过id来解决它们,在未来,工具可以列出它们.

安全和信任边界

Generative UI 将模型输出移入 DOM, 所以处理每个表面的代理 输出为 未信任输入编辑 a2ui() 中间软件 validate 选项 (包括 'strict'(b) 检查信封结构和组件 类型名称 只反对目录。 没错 没有 验证组件道具或数据模型 值:模型控制值,例如 Image.url 财务报告和审定财务报表 Text (在线马克下, ,而渲染器可能变成HTML)通过未变. 'strict' 是一个 良好的结构检查,不是安全边界.

因此,一个被迅速注射或直接错误的模型可以释放任意的远程 图像 URL,或 Markdown 即一个渲染器会变成 HTML 。 为了保证安全:

  • 渲染器/目录拥有道具的消毒. 不管是什么使一个表面 (例如 @a2ui/lit 加上你的Markdown渲染器) 在到达DOM之前 逃脱并消毒道具值 如果你运送 自定义目录,其渲染器必须将自己的组件道具进行消毒.
  • 限制主机的远程源 . 为应用程序提供内容安全 限制的政策 img-src 以你们所信任的出身, 因此模型提供的图像或链接 URL 无法过滤数据或加载 意外内容 .
  • 不要在数据模型中隐藏秘密 . 任何与地表数据相连的东西 模型可以通过动作回放 context。 。 。 .

如果您需要服务器端对道具的控制( 例如, 允许列表图像) 主机后, 添加您自己的型号中间软件 a2ui() 检查并重写 释放出a2ui部件.

如何运作

1名代表

A2UI 骑自有部分频道:一款Genkit data 带有 mime 类型的部件 application/a2ui+json 谁 data 是对象 { envelopes } 包装 数组 A2UI 信封信息。 此地图为 A2UI 装订的 A2A 上的 1:1 spec,所以一个A2A或MCP绑定可以稍后免费下放.

  • A 类 混合 转动是信息的内容 [textPart, a2uiPart, …]。 。 。 .
  • A 类 纯地表 转弯是没有文本部分的特例.
  • 下游消费者(客户运输、, @a2ui/web_core) 只见过a2ui 页:1 "Pure vs mix"是一个提示性的选择,而不是单独的代码路径.

中间软件管道

在代理工具循环的每个模型呼叫中, a2ui()数字 :

  1. 将目录的能力输入系统 提示模型知道 以物配主 instructions: 'none') (中文(简体) ).
  2. 截取了模型的输出,既包括流出块,也包括最终块 汇总消息.
  3. 摘录 a2ui 从模型的文本中取出有栅栏的代码块.
  4. 对照目录验证它们(每 validate 选项).
  5. 把它们重写成 Cononical a2ui 数据部件.

输入的a2ui部分(例如,作为下个转弯返回的表面动作,或 (重播历史)在基础模型看到之前被归纳为纯文本 因此,一个不懂 ai2ui mime 类型的模型 仍然可以解释 关于先前的表面和用户动作.

许可证

阿帕奇 - 2.0

版本与发布记录

@genkit-ai/a2ui 共发布 10 个版本,首次发布于 2026/08/28;过去 12 个月发布了 10 个版本。

版本发布日期距今
0.7.0latest2026/11/0412 天前
0.6.02026/10/2225 天前
0.6.0-rc.3next2026/10/2225 天前
0.6.0-rc.22026/10/2126 天前
0.6.0-rc.12026/10/091 个月前
0.6.0-rc.02026/10/091 个月前

关于 @genkit-ai/a2ui 的常见问题

@genkit-ai/a2ui 是什么?

一个Genkit插件,通过模型中间软件提供A2UI(Agent-to-UI)流式UI协议支持.

如何安装 @genkit-ai/a2ui?

在项目目录运行 npm install @genkit-ai/a2ui,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:genkit(^1.44.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@genkit-ai/a2ui 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@genkit-ai/a2ui 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@genkit-ai/a2ui 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=20。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@genkit-ai/a2ui 可以商用吗?

@genkit-ai/a2ui 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@genkit-ai/a2ui 的下载量有多少?

根据 npm 官方下载统计,@genkit-ai/a2ui 在 2026/10/16 – 2026/11/14 这 30 天内被下载 4,593 次,日均约 153 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@genkit-ai/a2ui 还在维护吗?

最新版本 0.7.0 发布于 2026/11/04(12 天前);至今共发布 10 个版本,其中过去 12 个月发布了 10 个;首次发布于 2026/08/28。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。