@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这样做 没有 发送他们的值
自动。 要捕捉用户输入的内容,模型必须:
- 捆绑每个输入的
value用于数据模型路径({ "path": "/email" }) (中文(简体) ). - 重复提交中的相同路径
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()数字 :
- 将目录的能力输入系统 提示模型知道
以物配主
instructions: 'none') (中文(简体) ). - 截取了模型的输出,既包括流出块,也包括最终块 汇总消息.
- 摘录
a2ui从模型的文本中取出有栅栏的代码块. - 对照目录验证它们(每
validate选项). - 把它们重写成 Cononical a2ui 数据部件.
输入的a2ui部分(例如,作为下个转弯返回的表面动作,或 (重播历史)在基础模型看到之前被归纳为纯文本 因此,一个不懂 ai2ui mime 类型的模型 仍然可以解释 关于先前的表面和用户动作.
许可证
阿帕奇 - 2.0