@ a2ui/ lit (英语)
升成像器,用于 A2UI (英语) (代理用户界面) - 启用 AI代理通过声明JSON生成丰富而互动的用户界面.
包含一个基本的目录执行,以帮助您立即启动.
附加自定义组件可以被推断为类型安全属性 从 佐德语Name 计划, 可以添加到您的定制目录中 用于对生成代码的总控制.
安装
yarn add @a2ui/lit @a2ui/web_core
协议版本
A2UI支持多个协议版本. 关于新项目,建议 使用该 页:1 协议.
要使用 v0. 9 执行, 从版本路径导入 :
import {A2uiSurface, basicCatalog} from '@a2ui/lit/v0_9';
快速启动
立特制造器与 MessageProcessor 从 @a2ui/web_core。 。 。 .
import {LitElement, html} from 'lit';
import {customElement, state} from 'lit/decorators.js';
import {MessageProcessor} from '@a2ui/web_core/v0_9';
import {A2uiSurface, basicCatalog} from '@a2ui/lit/v0_9';
@customElement('my-app')
export class MyApp extends LitElement {
private processor = new MessageProcessor([basicCatalog]);
@state()
private surface: any;
connectedCallback() {
super.connectedCallback();
// Listen for surface creation
this.processor.onSurfaceCreated(s => {
if (s.id === 'main-chat') {
this.surface = s;
}
});
// The message objects should come from your agent
this.processor.processMessages([
{
version: 'v0.9',
createSurface: {
surfaceId: 'main-chat',
catalogId: basicCatalog.id,
},
},
]);
}
render() {
return html`
<div class="a2ui-container">
${this.surface
? html`<a2ui-surface .surface=${this.surface}></a2ui-surface>`
: html`<div>Initializing Agent UI...</div>`}
</div>
`;
}
}
定义自定义组件
A2UI v0.9将组件的API(Schema)与其执行分离.
1. 界定组成部分API
使用 Zod 定义属性 .
import {z} from 'zod';
import {CommonSchemas} from '@a2ui/web_core/v0_9';
export const MyProfileApi = {
name: 'Profile',
schema: z.object({
username: CommonSchemas.DynamicString,
bio: CommonSchemas.DynamicString,
onEdit: CommonSchemas.Action,
}),
};
2. 创建立项执行
扩展 A2uiLitElement 执行 createController 财务报告和审定财务报表 render。 。 。 .
import {A2uiLitElement} from '@a2ui/lit/v0_9';
import {customElement} from 'lit/decorators.js';
import {html, nothing} from 'lit';
import {MyProfileApi} from './my-profile-api';
@customElement('my-profile')
export class MyProfileElement extends A2uiLitElement<typeof MyProfileApi> {
protected readonly api = MyProfileApi;
render() {
const props = this.controller?.props;
if (!props) return nothing;
return html`
<div class="profile-widget">
<h2>${props.username}</h2>
<p>${props.bio}</p>
<button @click=${props.onEdit}>Edit</button>
</div>
`;
}
}
// Export the catalog entry
export const MyProfile = {
...MyProfileApi,
tagName: 'my-profile',
};
3. 界定目录
将您的自定义组件分组为 a Catalog 从 @a2ui/web_core/v0_9。 。 。 .
import {Catalog} from '@a2ui/web_core/v0_9';
import {MyProfile} from './my-profile';
export const myCatalog = new Catalog('https://example.com/catalogs/my-catalog.json', 'v0.9', [
MyProfile,
]);
4. 使用自定义目录
将您的自定义目录传递到 MessageProcessor 与基本目录并列
在您的应用程序设置( 如快速启动 ) .
import {MessageProcessor} from '@a2ui/web_core/v0_9';
import {basicCatalog} from '@a2ui/lit/v0_9';
import {myCatalog} from './my-catalog';
// Initialize the MessageProcessor with both catalogs
const processor = new MessageProcessor([basicCatalog, myCatalog]);
基本目录组件
这个 @a2ui/lit/v0_9 软件包包括一个 basicCatalog 带有标准组件.
您可以在目录中找到基本目录的全部规格 GitHub 仓库。 。 。 .
- 版式数字 :
Row, (中文(简体) ),Column, (中文(简体) ),List, (中文(简体) ),Card, (中文(简体) ),Tabs, (中文(简体) ),Modal, (中文(简体) ),Divider - 内容数字 :
Text, (中文(简体) ),Image, (中文(简体) ),Icon, (中文(简体) ),Video - 投入数字 :
Button, (中文(简体) ),TextField, (中文(简体) ),CheckBox, (中文(简体) ),ChoicePicker, (中文(简体) ),Slider, (中文(简体) ),DateTimeInput
标准的基本目录组件作为框架不可知的普遍自定义元素在 @a2ui/web_core (单位:千美元)gitHub 上的源代码和从 @a2ui/lit/v0_9 为后向相容性.
从v0.8移徙
如果您正在将一个已有的应用程序从 v0. 8 迁移到 v0. 9 , 您可以参考 shell 样本的迁移 调取请求 # 1105 (承诺) a5ad0c328628df6fd8f53aef86f5b3db452ba3a8) (中文(简体) ).
移徙的主要变化包括:
- 页眉更新于
client.ts: 您必须更新X-A2A-Extensions请求 v0. 9 协议的页眉 :https://a2ui.org/a2a-extension/a2ui/v0.9。 。 。 . - 手册处理
app.ts:在v0.8中,应用程序必须听取自定义动作事件(如:@a2uiaction)和人工解析上下文路径来构建行动信息. 在v0.9中MessageProcessor和普通宾德自动处理。 您可以从模板中删除复杂的事件听众 . - 基于 CSS 的基本目录: 基本目录部件现在可以样式化
通过压倒性的 CSS 变量,例如
--a2ui-primary-color。 。 。 .
我们强烈反对以v0.8启动新项目.
警卫
[大 所提供的样本代码是用于演示目的,并说明了A2UI和A2A代理协议的力学. 在建立生产应用程序时,关键是要将任何在您直接控制之外运作的代理商视为一个潜在的不信任实体.
外部代理人提供的所有业务数据——包括其代理卡、信息、文物和任务状况——应作为不信任的投入处理。 例如,恶意代理可以在其领域提供被精心制作的数据(如名称,技能.description),如果在没有进行消毒的情况下用于构建大语言模型(LLM)的提示,可能会使您的应用暴露于即时注射攻击.
同样,所收到的任何UI定义或数据流都必须作为不信任处理. 恶意代理可能试图对合法接口进行套用来欺骗用户(fishing),通过属性值(XSS)来注入恶意脚本,或者产生过度的布局复杂来降低客户端性能(DoS). 如果您的应用程序支持可选的嵌入内容(如iframes或web视图),则必须额外注意防止被恶意外部网站曝光.
开发者责任:不能正确验证数据和严格地提供沙盒内容可能会造成严重的脆弱性。 开发者负责执行适当的安全措施,例如输入消毒、内容安全政策、对可选嵌入内容的严格隔离、以及确保证书处理,以保护他们的系统和用户.