跳到主要内容

快速开始指南

本指南将帮助你快速上手 AG-UI 协议，从环境配置到创建你的第一个界面。无论你是希望为代理添加界面能力还是构建界面渲染器，这里都提供了必要的步骤和示例代码。

准备工作​

在开始使用 AG-UI 协议之前，你需要准备以下环境：

安装 AG-UI SDK​

AG-UI SDK 提供了各种编程语言的实现，选择你最熟悉的语言：

Python​

pip install ag-ui

JavaScript/Node.js​

npm install @ag-ui/sdk

React​

npm install @ag-ui/react

注册 AG-UI 开发者账号​

  1. 访问 AG-UI 开发者门户
  2. 创建一个新的开发者账号
  3. 获取 API 密钥

创建你的第一个界面​

基础界面模板​

以下是创建一个简单表单界面的基本代码模板（Python 版本）：

from ag_ui import UIBuilder, UIRenderer

# 创建UI构建器
builder = UIBuilder()

# 定义表单界面
form_ui = builder.create_form(
    ui_id="my-first-form",
    title="用户注册",
    sections=[
        {
            "id": "basic-info",
            "title": "基本信息",
            "components": [
                builder.text_input(
                    id="name",
                    label="姓名",
                    placeholder="请输入您的姓名",
                    required=True
                ),
                builder.email_input(
                    id="email",
                    label="邮箱",
                    required=True
                ),
                builder.button(
                    id="submit",
                    label="提交",
                    action="submit"
                )
            ]
        }
    ]
)

# 渲染界面（Web平台）
renderer = UIRenderer(platform="web")
html_output = renderer.render(form_ui)
print(html_output)

JavaScript/React 版本​

import { UIBuilder, UIRenderer } from '@ag-ui/sdk';
import { AGUIProvider } from '@ag-ui/react';

// 创建UI构建器
const builder = new UIBuilder();

// 定义界面
const formUI = builder.createForm({
  uiId: 'my-first-form',
  title: '用户注册',
  sections: [
    {
      id: 'basic-info',
      title: '基本信息',
      components: [
        builder.textInput({
          id: 'name',
          label: '姓名',
          placeholder: '请输入您的姓名',
          required: true
        }),
        builder.emailInput({
          id: 'email',
          label: '邮箱',
          required: true
        }),
        builder.button({
          id: 'submit',
          label: '提交',
          action: 'submit'
        })
      ]
    }
  ]
});

// 在React中使用
function App() {
  return (
    <AGUIProvider>
      <AGUIComponent ui={formUI} />
    </AGUIProvider>
  );
}

处理用户交互​

事件处理​

from ag_ui import EventHandler

# 创建事件处理器
handler = EventHandler()

# 处理表单提交
@handler.on("form-submit")
def handle_submit(event):
    form_data = event.data
    
    # 验证数据
    if not validate_form(form_data):
        return {
            "type": "error",
            "message": "表单验证失败",
            "errors": get_validation_errors(form_data)
        }
    
    # 处理数据
    result = process_form_data(form_data)
    
    # 返回结果并更新界面
    return {
        "type": "success",
        "message": "提交成功",
        "ui_update": {
            "show_success_message": True
        }
    }

# 处理按钮点击
@handler.on("button-click")
def handle_button_click(event):
    if event.action == "search":
        results = perform_search(event.data)
        return {
            "type": "update-table",
            "table_id": "results-table",
            "data": results
        }

创建数据表格界面​

表格定义​

# 创建数据表格
table_ui = builder.create_table(
    ui_id="data-table",
    title="数据列表",
    columns=[
        {"key": "id", "label": "ID", "sortable": True},
        {"key": "name", "label": "名称"},
        {"key": "status", "label": "状态", "type": "badge"},
        {"key": "actions", "label": "操作", "type": "actions"}
    ],
    data_source="agent://get-data-list",
    pagination=True,
    page_size=20
)

创建图表界面​

图表定义​

# 创建折线图
chart_ui = builder.create_chart(
    ui_id="sales-chart",
    type="line",
    title="销售趋势",
    data_source="agent://get-sales-data",
    x_axis="date",
    y_axis="amount",
    options={
        "responsive": True,
        "maintainAspectRatio": False
    }
)

# 创建柱状图
bar_chart = builder.create_chart(
    ui_id="category-chart",
    type="bar",
    title="分类统计",
    data_source="agent://get-category-stats"
)

动态界面更新​

根据状态更新界面​

from ag_ui import UIState, UIUpdate

# 创建UI状态管理器
state = UIState()

# 初始界面
initial_ui = builder.create_form(...)

# 根据用户输入更新界面
def on_country_change(country: str):
    update = UIUpdate()
    
    if country == "cn":
        # 添加中国特有字段
        update.add_component(
            builder.text_input(
                id="id-card",
                label="身份证号",
                required=True
            ),
            section_id="basic-info"
        )
    else:
        # 移除身份证字段
        update.remove_component("id-card")
    
    state.apply_update(update)

部署你的界面​

Web部署​

from ag_ui import WebServer

# 创建Web服务器
server = WebServer(
    port=8000,
    ui_definitions={
        "form": form_ui,
        "table": table_ui,
        "chart": chart_ui
    }
)

# 启动服务器
server.start()

React应用集成​

import { AGUIProvider, useAGUI } from '@ag-ui/react';

function MyApp() {
  const { ui, updateUI } = useAGUI();
  
  return (
    <AGUIProvider ui={ui} onUpdate={updateUI}>
      <AGUIRenderer />
    </AGUIProvider>
  );
}

调试技巧​

本地测试​

from ag_ui import UISimulator

# 创建UI模拟器
sim = UISimulator()

# 测试界面渲染
rendered = sim.render(form_ui)
print(rendered)

# 测试事件处理
result = sim.trigger_event("form-submit", {"name": "Test", "email": "test@example.com"})
print(result)

日志和追踪​

import logging
from ag_ui import set_log_level

# 设置日志级别
set_log_level(logging.DEBUG)

# 启用UI追踪
renderer.enable_tracing(output_dir="./ui-traces")

最佳实践​

  1. 清晰的界面结构：合理组织界面层次和组件
  2. 响应式设计：确保界面在不同设备上正常显示
  3. 性能优化：优化渲染和更新性能
  4. 用户体验：关注交互流畅性和反馈
  5. 无障碍支持：确保界面可访问性

常见问题解答​

Q: AG-UI 协议是否支持自定义组件？
A: 是的，你可以注册自定义组件到组件注册表。

Q: 界面可以在哪些平台使用？
A: 支持Web、移动端（iOS/Android）、桌面应用等平台。

Q: 如何处理界面性能问题？
A: 使用虚拟滚动、懒加载、缓存等技术优化性能。

Q: 如何确保界面安全性？
A: 实施输入验证、XSS防护、CSRF保护等安全措施。

Q: 界面更新的延迟如何？
A: 延迟取决于网络和渲染性能，AG-UI 协议本身经过优化，引入的额外延迟最小。