现在位置: 首页 / 免费干货 / 正文

AG-UI 与 Agent Framework 的集成

AG-UI 是一种协议，可用于使用高级功能（如实时流式处理、状态管理和交互式 UI 组件）生成基于 Web 的 AI 代理应用程序。 代理框架 AG-UI 集成提供代理和 Web 客户端之间的无缝连接。

什么是 AG-UI？

AG-UI 是用于生成 AI 代理接口的标准化协议，可提供：

  • 远程代理托管：将 AI 代理部署为多个客户端可访问的 Web 服务
  • 实时流式处理：使用 Server-Sent 事件（SSE）流式处理代理响应以获取即时反馈
  • 标准化通信：可靠代理交互的一致消息格式
  • 线程管理：跨多个请求维护会话上下文
  • 高级功能：人工循环审批、状态同步和自定义 UI 呈现

何时使用 AG-UI

如果需要以下条件，请考虑使用 AG-UI：

  • 生成与 AI 代理交互的 Web 或移动应用程序
  • 将代理以服务的形式部署，使之能够被多用户并发访问
  • 实时流式处理代理响应以提供即时用户反馈
  • 实施审批流程，用户在执行前确认操作
  • 在客户端和服务器之间同步状态以获取交互式体验
  • 基于代理工具调用呈现自定义 UI 组件

支持的功能

代理框架 AG-UI 集成支持所有 7 AG-UI 协议功能：

  1. 代理聊天：使用自动工具调用的基本流式聊天
  2. 后端工具呈现：在后端执行的工具，结果流式传输到客户端
  3. 人机交互：请求用户确认的函数审批
  4. 生成式代理 UI：异步工具用于进行长时间运行的操作，并提供进度更新
  5. 基于工具的生成 UI：基于工具调用呈现的自定义 UI 组件
  6. 共享状态：客户端和服务器之间的双向状态同步
  7. 预测状态更新：将工具参数作为乐观状态更新流式传输

使用 CopilotKit 生成代理 UI

CopilotKit 提供丰富的 UI 组件，用于基于标准 AG-UI 协议生成代理用户界面。 CopilotKit 支持流式聊天接口、前端和后端工具调用、人机循环交互、生成 UI、共享状态等。 可以在 AG-UI Dojo 示例应用程序中查看 CopilotKit 支持的各种代理 UI 方案的示例。

CopilotKit 可帮助你专注于代理的功能，同时提供精致的用户体验，而无需重新发明轮子。 若要详细了解如何开始使用 Microsoft Agent Framework 和 CopilotKit，请参阅 copilotKit 的 Microsoft Agent Framework 集成 文档。

AG-UI 与直接代理使用情况

虽然可以使用 Agent Framework 和RunRunStreamingAsync方法直接在应用程序中运行代理，但 AG-UI 提供了其他功能：

功能 / 特点 直接代理使用情况 AG-UI 集成
部署 嵌入到应用程序中 通过 HTTP 远程服务
客户端访问 单个应用程序 多个客户端（Web、移动）
流媒体 进程内异步迭代 Server-Sent 事件（SSE）
状态管理 应用程序管理 协议级状态快照
线程上下文 应用程序管理 协议管理的线程 ID
审批工作流 自定义实现 内置中间件模式

体系结构概述

AG-UI 集成使用 ASP.NET Core，并遵循基于中间件的干净体系结构：

┌─────────────────┐
│ Web Client │
│ (Browser/App) │
└────────┬────────┘
│ HTTP POST + SSE
▼
┌─────────────────────────┐
│ ASP.NET Core │
│ MapAGUI("/", agent) │
└────────┬────────────────┘
│
▼
┌─────────────────────────┐
│ AIAgent │
│ (with Middleware) │
└────────┬────────────────┘
│
▼
┌─────────────────────────┐
│ IChatClient │
│ (Azure OpenAI, etc.) │
└─────────────────────────┘

关键组件

  • ASP.NET 核心终结点： MapAGUI 扩展方法处理 HTTP 请求和 SSE 流式处理
  • AIAgent：从 IChatClient 或自定义实现创建的代理框架代理
  • 中间件管道：用于审批、状态管理和自定义逻辑的可选中间件
  • 协议适配器：在代理框架类型和 AG-UI 协议事件之间进行转换
  • 聊天客户端：Microsoft.Extensions.AI 聊天客户端（Azure OpenAI、OpenAI、Ollama 等）

代理框架如何转换为 AG-UI

了解 Agent Framework 概念如何映射到 AG-UI 有助于构建有效的集成：

代理框架概念 AG-UI 等效项 Description
AIAgent 代理端点 每个代理都成为 HTTP 端点
agent.Run() HTTP POST 请求 客户端通过 HTTP 发送消息
agent.RunStreamingAsync() “服务器已发送”事件 通过 SSE 流式处理响应
AgentResponseUpdate AG-UI 事件 自动转换为协议事件
AIFunctionFactory.Create() 后端工具 在服务器上执行，结果流式传输
ApprovalRequiredAIFunction 人在环 中间件转换为审批协议
AgentThread 线程管理 ConversationId 维护上下文
ChatResponseFormat.ForJsonSchema<T>() 状态快照 结构化输出成为状态事件

Installation

AG-UI 集成包含在 ASP.NET Core 托管包中：

dotnet add package Microsoft.Agents.AI.Hosting.AGUI.AspNetCore

此包包括 AG-UI 集成所需的所有依赖项，包括 Microsoft.Extensions.AI。

后续步骤

若要开始 AG-UI 集成，

  1. 入门：生成第一个 AG-UI 服务器和客户端
  2. 后端工具渲染：向代理程序添加功能工具

其他资源

AG-UI 与直接代理使用情况

虽然可以使用 Agent Framework 和runrun_streaming方法直接在应用程序中运行代理，但 AG-UI 提供了其他功能：

功能 / 特点 直接代理使用情况 AG-UI 集成
部署 嵌入到应用程序中 通过 HTTP 远程服务
客户端访问 单个应用程序 多个客户端（Web、移动）
流媒体 进程内异步迭代 Server-Sent 事件（SSE）
状态管理 应用程序管理 双向协议级同步
线程上下文 应用程序管理 协议管理的线程 ID
审批工作流 自定义实现 内置协议支持

f概述

AG-UI 集成使用干净的模块化体系结构：

┌─────────────────┐
│ Web Client │
│ (Browser/App) │
└────────┬────────┘
│ HTTP POST + SSE
▼
┌─────────────────────────┐
│ FastAPI Endpoint │
│ (add_agent_framework_ │
│ fastapi_endpoint) │
└────────┬────────────────┘
│
▼
┌─────────────────────────┐
│ AgentFrameworkAgent │
│ (Protocol Wrapper) │
└────────┬────────────────┘
│
▼
┌─────────────────────────┐
│ Orchestrators │
│ (Execution Flow Logic) │
└────────┬────────────────┘
│
▼
┌─────────────────────────┐
│ ChatAgent │
│ (Agent Framework) │
└────────┬────────────────┘
│
▼
┌─────────────────────────┐
│ Chat Client │
│ (Azure OpenAI, etc.) │
└─────────────────────────┘

关键组件

  • FastAPI 终结点：处理 SSE 流式处理和请求路由的 HTTP 终结点
  • AgentFrameworkAgent：使 Agent Framework 代理适应 AG-UI 协议的轻型包装器
  • 编排器：处理不同的执行流（默认、人机协作、状态管理）
  • 事件桥：将代理框架事件转换为 AG-UI 协议事件
  • 消息适配器：AG-UI 和 Agent Framework 消息格式之间的双向转换
  • 确认策略：特定于域的确认消息的可扩展策略

代理框架如何转换为 AG-UI

了解 Agent Framework 概念如何映射到 AG-UI 有助于构建有效的集成：

代理框架概念 AG-UI 等效项 Description
ChatAgent 代理端点 每个代理都成为 HTTP 端点
agent.run() HTTP POST 请求 客户端通过 HTTP 发送消息
agent.run_streaming() “服务器已发送”事件 通过 SSE 流式处理响应
代理响应更新 AG-UI 事件 TEXT_MESSAGE_CONTENT、TOOL_CALL_START 等
函数工具 （@ai_function） 后端工具 在服务器上执行，结果流式传输到客户端
工具审批模式 人在环 通过协议审批请求/响应
会话历史记录 线程管理 threadId 维护跨请求的上下文

Installation

安装 AG-UI 集成包：

pip install agent-framework-ag-ui --pre

这会同时安装核心代理框架和 AG-UI 集成组件。

后续步骤

若要开始 AG-UI 集成，