Skip to content

Latest commit

 

History

History
281 lines (220 loc) · 7.9 KB

README_zh.md

File metadata and controls

281 lines (220 loc) · 7.9 KB

AG-UI 协议演示

English Documentation

一个全面的 Agent User Interaction Protocol (AG-UI) 演示，使用多种前端和后端技术实现，展示实时代理通信、流式事件和人机协作工作流。

概述

此演示实现了 AG-UI 协议，在 AI 代理和前端应用程序之间创建标准化接口。它展示了：

  • 实时流式通信 - 代理和 UI 之间
  • 事件驱动架构 - 遵循 AG-UI 规范
  • 工具调用机制 - 支持人机协作工作流
  • 状态同步 - 代理和前端之间
  • 多种后端实现 - SignalR/.NET 和 Socket.IO/Node.js

应用截图

应用界面

AG-UI 演示主界面 AG-UI 协议演示界面，显示演示场景（左）、聊天界面（中）和实时事件日志（右）

交互演示

AG-UI 交互演示 AG-UI 协议事件的实时演示，包括消息流传输、工具调用和状态同步

架构

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   前端          │    │   通信层         │    │   后端          │
│   (Svelte)      │◄──►│                  │◄──►│   (.NET/Node)   │
└─────────────────┘    └──────────────────┘    └─────────────────┘
        │                       │                       │
        │                       │                       │
        ▼                       ▼                       ▼
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│  AgentChat      │    │  SignalR/        │    │  AgentHub/      │
│  组件           │    │  Socket.IO       │    │  AgentService   │
└─────────────────┘    └──────────────────┘    └─────────────────┘

特性

✨ AG-UI 协议合规性

  • 完整实现 AG-UI 事件
  • 生命周期事件（RUN_STARTED、RUN_FINISHED 等）
  • 文本消息流（TEXT_MESSAGE_START、CONTENT、END）
  • 工具调用事件（TOOL_CALL_START、ARGS、END、RESULT）
  • 状态管理（STATE_SNAPSHOT、STATE_DELTA）

🔧 多种后端选项

  • SignalR/.NET 8：企业级实时通信
  • Socket.IO/Node.js：轻量级、灵活的实现

🎯 高级功能

  • 实时消息流：逐字符文本渲染
  • 工具集成：可扩展的工具调用系统
  • 状态同步：双向状态共享
  • 事件日志：完整的 AG-UI 事件透明度
  • 错误处理：强大的连接和错误管理

快速开始

前置要求

  • Node.js 18+ 和 npm
  • .NET 8 SDK（用于 SignalR 后端）
  • 现代 Web 浏览器

安装

# 克隆仓库
git clone <repository-url>
cd ag-ui-demo1

# 安装前端依赖
cd frontend
npm install

# 安装 Node.js 后端依赖
cd ../backend/nodejs-mock-server
npm install

# 返回项目根目录
cd ../..

运行演示

选项 1：Socket.IO 后端（Node.js）

终端 1：启动 Node.js 后端

cd backend/nodejs-mock-server
npm run dev
# 或者：npm start

这将在端口 5001 启动 Node.js 后端

终端 2：启动前端

cd frontend
npm run dev

这将在端口 5173 启动前端

选项 2：SignalR 后端（.NET）

终端 1：启动 .NET 后端

cd backend/dotnet-signalr-server
dotnet run

这将在端口 5000 启动 .NET SignalR 后端

终端 2：启动前端

cd frontend
npm run dev

这将在端口 5173 启动前端

访问应用程序

项目结构

├── frontend/                 # Svelte 前端应用
│   ├── src/
│   │   ├── lib/
│   │   │   ├── components/   # UI 组件
│   │   │   │   └── AgentChat.svelte
│   │   │   ├── SignalRAgent.ts    # SignalR 客户端
│   │   │   ├── SocketIOAgent.ts   # Socket.IO 客户端
│   │   │   └── types.ts           # AG-UI 类型定义
│   │   ├── App.svelte        # 主应用程序
│   │   └── main.ts
├── backend/
│   ├── dotnet-signalr-server/     # .NET SignalR 实现
│   │   ├── AgentHub.cs            # 带 AG-UI 事件的 SignalR Hub
│   │   └── Program.cs
│   └── nodejs-mock-server/        # Node.js Socket.IO 实现
│       ├── server.js              # Express + Socket.IO 服务器
│       └── package.json
└── docs/                    # 多语言文档
    ├── en/                  # 英文文档
    ├── zh/                  # 中文文档
    └── README.md           # 此文件

AG-UI 协议实现

此演示展示了完整的 AG-UI 协议实现：

已实现的事件类型

  1. 生命周期事件

    • RUN_STARTED：代理执行开始
    • RUN_FINISHED：代理执行完成
    • RUN_ERROR：代理执行失败
    • STEP_STARTED：代理步骤开始
    • STEP_FINISHED：代理步骤完成

  2. 消息事件

    • TEXT_MESSAGE_START：消息流开始
    • TEXT_MESSAGE_CONTENT：消息内容块
    • TEXT_MESSAGE_END：消息流完成

  3. 工具事件

    • TOOL_CALL_START：工具执行开始
    • TOOL_CALL_ARGS：工具参数流
    • TOOL_CALL_END：工具调用完成
    • TOOL_CALL_RESULT：工具执行结果

  4. 状态事件

    • STATE_SNAPSHOT：完整状态同步
    • STATE_DELTA：增量状态更新

工具系统

演示包含几个示例工具，展示 AG-UI 工具调用模式：

const tools = [
  {
    name: "getUserPreferences",
    description: "获取用户偏好和设置",
    parameters: {
      type: "object",
      properties: {
        userId: { type: "string", description: "用户 ID" }
      },
      required: ["userId"]
    }
  },
  // 更多工具...
];

开发

添加新工具

  1. 在 frontend/src/App.svelte 中定义工具：
const newTool = {
  name: "myTool",
  description: "此工具的功能描述",
  parameters: {
    type: "object",
    properties: {
      param1: { type: "string", description: "参数描述" }
    },
    required: ["param1"]
  }
};
  1. 在后端处理工具执行
  2. 在前端界面测试工具调用

自定义 AG-UI 事件

在 AgentChat.svelte 中扩展事件处理：

function handleAgentEvent(event: AGUIEvent) {
  switch (event.type) {
    case EventType.CUSTOM:
      // 处理自定义事件
      break;
    // ... 其他情况
  }
}

文档

提供多语言综合文档：

可用文档

  • 架构指南
  • 开发设置
  • API 参考
  • 故障排除
  • 贡献指南

贡献

我们欢迎贡献！请查看我们的贡献指南了解详情。

开发工作流

  1. Fork 仓库
  2. 创建功能分支
  3. 进行更改
  4. 如适用，添加测试
  5. 更新文档
  6. 提交拉取请求

许可证

此项目根据 MIT 许可证授权 - 请参阅 LICENSE 文件了解详情。

资源

支持

如有问题和支持：