# https://github.com/microsoft/agent-framework 项目说明书 生成时间：2026-05-13 17:14:16 UTC ## 目录 - [框架介绍](#introduction) - [安装与配置](#installation) - [系统架构](#architecture) - [核心概念](#core-concepts) - [Agent 基础](#agent-basics) - [模型提供商集成](#agent-providers) - [工具与技能系统](#agent-tools) - [工作流系统概述](#workflow-overview) - [工作流编排模式](#workflow-patterns) - [检查点与恢复机制](#checkpoint-recovery) ## 框架介绍 ### 相关页面 相关主题：[安装与配置](#installation), [系统架构](#architecture)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/microsoft/agent-framework/blob/main/README.md) - [python/AGENTS.md](https://github.com/microsoft/agent-framework/blob/main/python/AGENTS.md) - [dotnet/AGENTS.md](https://github.com/microsoft/agent-framework/blob/main/dotnet/AGENTS.md) - [dotnet/src/Shared/Foundry/Agents/README.md](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Shared/Foundry/Agents/README.md) - [python/samples/01-get-started/README.md](https://github.com/microsoft/agent-framework/blob/main/python/samples/01-get-started/README.md) - [python/packages/declarative/README.md](https://github.com/microsoft/agent-framework/blob/main/python/packages/declarative/README.md)
# 框架介绍 Microsoft Agent Framework（微软智能体框架）是一个跨平台的智能体（Agent）开发框架，旨在帮助开发者快速构建、部署和管理 AI 智能体应用。该框架提供了丰富的工具、运行时和 SDK，支持多种编程语言和部署场景。 ## 框架概述 Agent Framework 由微软开发维护，是一个现代化的 AI 智能体开发平台。框架的核心设计理念是提供一个统一且灵活的架构，使开发者能够轻松创建具有对话能力、工具调用能力、工作流编排能力的高级 AI 应用。 该框架支持两种主要的开发语言生态： | 编程语言 | SDK 包名 | 定位 | |---------|---------|------| | Python | `agent-framework` | 主要面向 Python 开发者，提供完整的智能体开发能力 | | .NET/C# | Microsoft.Agents.AI | 面向 .NET 生态，提供企业级智能体支持 | 资料来源：[README.md:1]() ## 核心组件架构 ### Python SDK 组件 Python SDK 是框架的主要实现之一，提供了从基础智能体创建到复杂工作流编排的完整能力。 ``` graph TD A[用户应用] --> B[agent-framework SDK] B --> C[Agent 智能体] B --> D[Workflow 工作流] B --> E[Tools 工具] C --> F[ChatClient 聊天客户端] D --> G[Graph Workflow 图工作流] D --> H[Functional Workflow 函数式工作流] ``` Python SDK 的核心包结构： - `agent-framework` - 核心包，包含智能体、工具和工作流的基础类 - `agent-framework-declarative` - 声明式包，支持通过 YAML 规范构建智能体 资料来源：[python/AGENTS.md:1]() ### .NET SDK 组件 .NET SDK 提供企业级的智能体开发支持，集成了多种 AI 服务和托管选项。 | 组件命名空间 | 功能说明 | |------------|---------| | `Microsoft.Agents.AI` | 核心 AI 抽象和接口定义 | | `Microsoft.Agents.AI.Hosting.OpenAI` | OpenAI 托管集成 | | `Microsoft.Agents.AI.GitHub.Copilot` | GitHub Copilot 客户端集成 | | `Microsoft.Agents.AI.AzureAI.Persistent` | Azure AI 持久化智能体客户端 | | `Microsoft.Agents.AI.Skills` | 智能体技能（Skills）管理系统 | 资料来源：[dotnet/AGENTS.md:1]() ## 智能体（Agent）体系 智能体是框架的核心抽象单元，代表一个能够理解自然语言、执行工具调用、维护对话状态的 AI 实例。 ### ChatClientAgent `ChatClientAgent` 是框架中最基础的智能体类型，它通过 `IChatClient` 接口与底层聊天服务交互。这种设计实现了智能体逻辑与底层 AI 服务的解耦。 ```csharp // 创建一个基础智能体的核心参数 public class ChatClientAgent { string? Instructions { get; } // 系统指令 string? Name { get; } // 智能体名称 string? Description { get; } // 智能体描述 IList? Tools { get; } // 可用工具列表 ILoggerFactory? LoggerFactory { get; } // 日志工厂 IServiceProvider? Services { get; } // 依赖服务 } ``` 资料来源：[dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs:1]() ### 智能体创建流程 ``` graph LR A[配置模型] --> B[定义工具] B --> C[设置指令] C --> D[创建 Agent 实例] D --> E[建立会话] E --> F[发送消息/接收响应] ``` ### AgentId 标识模型 每个智能体都有一个唯一的标识符，用于在分布式系统中追踪和管理智能体实例。 ```csharp public sealed class AgentId { public AgentIdType Type { get; init; } // 标识类型 public string Name { get; init; } // 智能体名称 public string Version { get; init; } // 版本号 } ``` 资料来源：[dotnet/src/Microsoft.Agents.AI.Hosting.OpenAI/Responses/Models/AgentId.cs:1]() ## 工具系统（Tools） 工具系统使智能体能够执行外部操作，扩展了纯对话的能力边界。 ### 工具定义结构 | 属性 | 类型 | 说明 | |-----|------|-----| | Name | string | 工具名称，用于标识和调用 | | Description | string | 工具功能描述，供 AI 理解用途 | | Parameters | Schema | 参数模式定义 | | Handler | Delegate | 实际执行逻辑 | 框架支持两种工具定义方式： 1. **代码定义工具** - 通过装饰器或接口直接在代码中实现 2. **文件定义工具** - 通过 YAML/JSON 配置文件声明 资料来源：[python/samples/01-get-started/README.md:1]() ### 工具资源管理 智能体的工具可以关联资源（Resources），这些资源在运行时被注入到工具执行上下文中。 ```csharp public abstract class AgentSkill { // 技能关联的资源列表 public virtual IReadOnlyList? Resources => null; // 技能关联的脚本列表 public virtual IReadOnlyList? Scripts => null; } ``` 资料来源：[dotnet/src/Microsoft.Agents.AI/Skills/AgentSkill.cs:1]() ## 技能系统（Skills） 技能系统是框架的高级特性，允许开发者将领域知识、操作流程和资源打包成可复用的模块。 ### AgentSkillsProvider `AgentSkillsProvider` 是技能系统的核心组件，它负责： - 加载和组织技能定义 - 将技能转换为 AI 可理解的提示词 - 管理技能相关的工具和脚本执行 - 提供上下文感知的技能推荐 ```csharp public sealed partial class AgentSkillsProvider : AIContextProvider { // 技能列表占位符 private const string SkillsPlaceholder = "{skills}"; // 脚本指令占位符 private const string ScriptInstructionsPlaceholder = "{script_instructions}"; // 资源指令占位符 private const string ResourceInstructionsPlaceholder = "{resource_instructions}"; } ``` 资料来源：[dotnet/src/Microsoft.Agents.AI/Skills/AgentSkillsProvider.cs:1]() ### 技能指令模板 框架使用预定义的提示词模板来组织技能信息： ``` 你有权访问包含领域特定知识和能力的技能。 每个技能为特定任务提供专业指导、参考文档和资源。 {skills} 当任务与某个技能的领域匹配时，按以下步骤操作： - 使用 `load_skill` 加载技能指令 - 遵循提供的指导 {resource_instructions} {script_instructions} 只加载所需内容，按需加载。 ``` 资料来源：[dotnet/src/Microsoft.Agents.AI/Skills/AgentSkillsProvider.cs:1]() ### 技能类型 | 技能类型 | 说明 | 使用场景 | |---------|------|---------| | 文件技能（File-Based） | 基于 SKILL.md 文件定义 | 知识型技能、内容管理 | | 代码技能（Code-Defined） | 通过代码接口实现 | 动态逻辑、自定义行为 | | 混合技能（Mixed） | 结合文件和代码 | 复杂业务逻辑 | 资料来源：[python/packages/declarative/README.md:1]() ### 技能配置选项 ```csharp public sealed class AgentSkillsProviderOptions { // 自定义技能提示模板 public string? SkillsInstructionPrompt { get; set; } // 脚本执行是否需要审批 public bool ScriptApproval { get; set; } // 是否禁用工具和指令缓存 public bool DisableCaching { get; set; } } ``` 资料来源：[dotnet/src/Microsoft.Agents.AI/Skills/AgentSkillsProviderOptions.cs:1]() ## 工作流系统（Workflows） 框架提供了两种工作流编写范式，满足不同复杂度和可维护性需求。 ### 函数式工作流 函数式工作流将工作流定义为普通的异步函数，简洁直观。 ```python # 简单示例：异步函数即工作流 async def my_workflow(input_data): result = await agent.run(input_data) return process_result(result) ``` 资料来源：[python/samples/01-get-started/README.md:1]() ### 图工作流 图工作流通过有向图组织多个执行节点，支持复杂的条件分支和并行执行。 ``` graph TD A[开始节点] --> B[执行器1] A --> C[执行器2] B --> D[决策节点] C --> D D -->|条件A| E[执行器3] D -->|条件B| F[执行器4] E --> G[结束节点] F --> G ``` 图工作流的核心概念： | 概念 | 说明 | |-----|------| | 节点（Node） | 工作流中的处理单元 | | 边（Edge） | 节点间的数据流向和控制关系 | | 输入/输出 | 数据的注入和产出 | 资料来源：[python/samples/01-get-started/README.md:1]() ## 会话管理（Session） `AgentSession` 管理智能体的对话状态，支持多轮对话和上下文维护。 ```python # 建立会话 session = AgentSession( agent=my_agent, thread_id="unique-thread-id" ) # 多轮对话 async with session: response1 = await session.run("你好") response2 = await session.run("帮我查询天气") response3 = await session.run("谢谢") # 上下文保持 ``` 会话管理的关键特性： - **线程隔离** - 每个会话有独立的对话历史 - **状态持久化** - 支持跨请求的状态恢复 - **上下文传递** - 自动维护对话上下文 资料来源：[python/samples/01-get-started/README.md:1]() ## 上下文提供者（Context Provider） `ContextProvider` 允许开发者自定义上下文注入逻辑，为智能体提供动态的补充信息。 ```python class MyContextProvider(ContextProvider): async def provide_context(self, session, request): # 从外部获取相关上下文 user_profile = await get_user_profile(session.user_id) return {"user": user_profile} ``` 上下文提供者的工作流程： ``` graph LR A[请求进入] --> B[ContextProvider.provide_context] B --> C[聚合上下文数据] C --> D[注入系统提示] D --> E[发送给 AI] E --> F[处理响应] F --> G[返回结果] ``` 资料来源：[python/samples/01-get-started/README.md:1]() ## Azure AI 集成 框架通过 `PersistentAgentsClient` 提供与 Azure AI Foundry Agents 服务的深度集成。 ```csharp // 已废弃，请使用最新的 Foundry Agents 服务 [Obsolete("Please use the latest Foundry Agents service via the Microsoft.Agents.AI.AzureAI package.")] public static async Task CreateAIAgentAsync( this PersistentAgentsClient persistentAgentsClient, string model, string? name = null, string? description = null, string? instructions = null, IEnumerable? tools = null, ToolResources? toolResources = null, float? temperature = null, float? topP = null, string? responseFormat = null, IDictionary? metadata = null, IChatClientFactory? clientFactory = null, IServiceProvider? services = null, CancellationToken cancellationToken = default) ``` 资料来源：[dotnet/src/Microsoft.Agents.AI.AzureAI.Persistent/PersistentAgentsClientExtensions.cs:1]() ## GitHub Copilot 集成 框架支持将 GitHub Copilot 作为 AI 后端： ```csharp public static AIAgent AsAIAgent( this CopilotClient client, bool ownsClient = false, string? id = null, string? name = null, string? description = null, IList? tools = null, string? instructions = null) { Throw.IfNull(client); return new GitHubCopilotAgent(client, ownsClient, id, name, description, tools, instructions); } ``` 资料来源：[dotnet/src/Microsoft.Agents.AI.GitHub.Copilot/CopilotClientExtensions.cs:1]() ## 开发工具（DevUI） DevUI 是框架提供的示例应用，用于快速入门和探索智能体功能。 ``` graph TD A[DevUI 应用] --> B[连接 Agent Framework 后端] B --> C[示例画廊 Sample Gallery] B --> D[设置面板 Settings] C --> E[浏览示例] C --> F[下载示例] D --> G[配置端点] D --> H[查看能力] ``` DevUI 特性： | 功能 | 说明 | |-----|------| | 示例画廊 | 浏览和下载预置的智能体示例 | | 设置管理 | 配置连接参数和能力选项 | | 版本信息 | 显示框架和运行时版本 | | 能力展示 | 展示后端支持的各项能力 | 资料来源：[python/packages/devui/frontend/src/components/features/gallery/gallery-view.tsx:1]() ## 部署模式 框架支持多种部署场景： ### 客户端托管 智能体作为客户端应用的一部分运行，轻量级部署。 ```bash # Python 示例 cd python uv run samples/08_host_your_agent.py ``` ### 服务器托管 智能体部署为独立服务，通过 API 暴露功能。 ### 云原生部署 结合 Azure Container Apps、Azure Functions 或 Aspire 实现弹性扩缩容。 ``` graph TD A[客户端] -->|HTTP/WebSocket| B[API 网关] B --> C[Agent Service] C --> D[Foundry Agents API] D --> E[AI Model] C --> F[Skill Store] C --> G[Context Store] ``` 资料来源：[dotnet/src/Aspire.Hosting.AgentFramework.DevUI/AgentEntityInfo.cs:1]() ## 快速开始指南 ### Python 环境准备 ```bash # 安装核心包 pip install agent-framework # 设置环境变量 export FOUNDRY_PROJECT_ENDPOINT="https://your-project-endpoint" export FOUNDRY_MODEL="gpt-4o" # 可选，默认 gpt-4o ``` ### 创建第一个智能体 ```python from agent_framework import Agent # 创建智能体 agent = Agent( name="我的助手", instructions="你是一个有帮助的助手。", model="gpt-4o" ) # 运行智能体 result = await agent.run("你好，请介绍一下你自己。") print(result) ``` ### 添加工具 ```python from agent_framework import Agent, tool @tool def get_weather(city: str) -> str: """获取城市天气信息""" # 实现天气查询逻辑 return f"{city}今天天气晴朗" agent = Agent( name="天气助手", instructions="你是一个天气助手。", tools=[get_weather] ) ``` 资料来源：[python/samples/01-get-started/README.md:1]() ## 相关资源 - [官方文档](https://github.com/microsoft/agent-framework) - [Agent Skills 规范](https://agentskills.io/) - [Python SDK 仓库](https://github.com/microsoft/agent-framework/tree/main/python) - [.NET SDK 仓库](https://github.com/microsoft/agent-framework/tree/main/dotnet) - [示例代码库](https://github.com/microsoft/agent-framework/tree/main/python/samples) --- ## 安装与配置 ### 相关页面 相关主题：[框架介绍](#introduction), [Agent 基础](#agent-basics)
相关源码文件 以下源码文件用于生成本页说明： - [python/pyproject.toml](https://github.com/microsoft/agent-framework/blob/main/python/pyproject.toml) - [python/DEV_SETUP.md](https://github.com/microsoft/agent-framework/blob/main/python/DEV_SETUP.md) - [dotnet/src/Microsoft.Agents.AI/Microsoft.Agents.AI.csproj](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Microsoft.Agents.AI.csproj) - [python/samples/01-get-started/README.md](https://github.com/microsoft/agent-framework/blob/main/python/samples/01-get-started/README.md) - [dotnet/src/Shared/Foundry/Agents/README.md](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Shared/Foundry/Agents/README.md) - [python/packages/devui/frontend/src/components/layout/settings-modal.tsx](https://github.com/microsoft/agent-framework/blob/main/python/packages/devui/frontend/src/components/layout/settings-modal.tsx)
# 安装与配置 ## 概述 Agent Framework 是微软开发的一个跨平台智能代理框架，支持 Python 和 .NET 两种运行时环境。框架提供了完整的代理（Agent）开发、部署和管理能力，涵盖从基础代理创建到复杂工作流编排的完整功能链。 本页面详细介绍框架的安装方法、配置选项以及开发环境搭建指南。 --- ## 系统要求 ### Python 环境要求 | 组件 | 最低版本 | 推荐版本 | |------|----------|----------| | Python | 3.10 | 3.11+ | | pip | 21.0 | 最新版本 | ### .NET 环境要求 | 组件 | 最低版本 | 推荐版本 | |------|----------|----------| | .NET SDK | .NET 8 | .NET 8 LTS | | Visual Studio / VS Code | 最新 | 最新 | 资料来源：[dotnet/src/Microsoft.Agents.AI/Microsoft.Agents.AI.csproj](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Microsoft.Agents.AI.csproj) --- ## Python 安装 ### 方式一：pip 安装（生产环境） 使用 pip 直接安装稳定版本的 agent-framework 包： ```bash pip install agent-framework ``` 资料来源：[python/samples/01-get-started/README.md:14](https://github.com/microsoft/agent-framework/blob/main/python/samples/01-get-started/README.md#L14) ### 方式二：源码安装（开发环境） ```bash cd python pip install -e . ``` -e 参数表示可编辑模式安装，适合需要修改源码或参与框架开发的场景。 ### 依赖配置 Python 版本的依赖通过 pyproject.toml 管理，主要依赖包括： | 依赖包 | 用途 | |--------|------| | python-dotenv | 环境变量管理 | | httpx | HTTP 客户端 | | openai | OpenAI API 兼容接口 | 资料来源：[python/pyproject.toml](https://github.com/microsoft/agent-framework/blob/main/python/pyproject.toml) --- ## .NET 安装 ### NuGet 包引用 在 .NET 项目中，通过添加包引用来使用 Agent Framework： ```xml ``` ### 共享模块注入 Agent Framework 提供了多个可复用的共享模块，通过 .csproj 属性控制是否启用： ```xml true true true true ``` 资料来源：[dotnet/src/Shared/Foundry/Agents/README.md:7-11](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Shared/Foundry/Agents/README.md#L7-L11) ### 共享模块说明 | 模块 | 功能 | |------|------| | FoundryAgents | Foundry 代理创建和使用的共享模式 | | Samples | 高效的示例项目工具类 | | Redaction | 日志数据脱敏工具 | | Throw | 异常处理工具 | | 模块 | 功能 | |------|------| | TrimAttributes | AOT 裁剪优化支持 | | ExperimentalAttribute | 实验性功能标记 | | DiagnosticAttributes | 诊断属性支持 | | CallerAttributes | 调用者信息特性 | 资料来源：[dotnet/src/Shared/Redaction/README.md:15-25](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Shared/Redaction/README.md#L15-L25) --- ## 环境变量配置 ### Python 环境变量 创建 `.env` 文件或在终端中设置以下环境变量： ```bash export FOUNDRY_PROJECT_ENDPOINT="https://your-project-endpoint" export FOUNDRY_MODEL="gpt-4o" ``` | 变量名 | 必填 | 默认值 | 说明 | |--------|------|--------|------| | FOUNDRY_PROJECT_ENDPOINT | 是 | - | Azure Foundry 项目端点 | | FOUNDRY_MODEL | 否 | gpt-4o | 使用的模型标识符 | 资料来源：[python/samples/01-get-started/README.md:18-21](https://github.com/microsoft/agent-framework/blob/main/python/samples/01-get-started/README.md#L18-L21) ### .NET 环境变量 在 appsettings.json 中配置： ```json { "AzureAI": { "Endpoint": "https://your-resource.azurewebsites.net", "AuthenticationType": "ApiKey" } } ``` --- ## 开发环境搭建 ### 快速开始流程 ```mermaid graph TD A[安装依赖] --> B[配置环境变量] B --> C[克隆示例代码] C --> D[运行第一个代理] D --> E[添加自定义工具] E --> F[构建工作流] ``` ### Python 开发环境设置 1. **克隆仓库** ```bash git clone https://github.com/microsoft/agent-framework.git cd agent-framework ``` 2. **创建虚拟环境（推荐）** ```bash python -m venv venv source venv/bin/activate # Linux/macOS # 或 .\venv\Scripts\activate # Windows ``` 3. **安装开发依赖** ```bash cd python pip install -e ".[dev]" ``` 4. **验证安装** ```python import agent_framework print(agent_framework.__version__) ``` 资料来源：[python/DEV_SETUP.md](https://github.com/microsoft/agent-framework/blob/main/python/DEV_SETUP.md) ### .NET 开发环境设置 1. **克隆仓库** ```bash git clone https://github.com/microsoft/agent-framework.git ``` 2. **还原包** ```bash cd dotnet dotnet restore ``` 3. **构建项目** ```bash dotnet build ``` --- ## DevUI 配置 DevUI 是框架提供的示例应用，用于快速上手 Agent Framework 开发。 ### 部署模式 DevUI 支持多种运行模式： | 模式 | 说明 | 使用场景 | |------|------|----------| | default | 默认本地模式 | 开发调试 | | connected | 连接后端服务 | 完整功能测试 | | embedded | 内嵌模式 | 集成到现有应用 | 资料来源：[python/packages/devui/frontend/src/components/layout/settings-modal.tsx:35-38](https://github.com/microsoft/agent-framework/blob/main/python/packages/devui/frontend/src/components/layout/settings-modal.tsx#L35-L38) ### DevUI 版本信息 DevUI 界面可显示以下系统信息： - 版本号 (Version) - 运行时类型 (Runtime) - UI 模式 (UI Mode) - 能力支持 (Capabilities) ```typescript interface ServerCapabilities { instrumentation?: boolean; // 其他能力字段... } ``` --- ## Docker 部署配置 ### 快速部署步骤 1. **保存部署文件到项目目录** 2. **构建镜像** ```bash docker build -t my-agent . ``` 3. **启动容器** ```bash docker-compose up ``` ### 生产环境注意事项 | 注意事项 | 说明 | |----------|------| | 状态管理 | 内存状态在容器重启后会丢失 | | 认证 | 需要添加反向代理（nginx/Caddy）并配置认证 | | 密钥管理 | 使用 Azure Key Vault 管理敏感信息 | | 扩展性 | 单实例模式，不支持水平扩展 | 资料来源：[python/packages/devui/frontend/src/components/layout/deployment-modal.tsx](https://github.com/microsoft/agent-framework/blob/main/python/packages/devui/frontend/src/components/layout/deployment-modal.tsx) --- ## 代理创建配置 ### Python 创建代理 ```python from agent_framework import Agent, tool @tool def get_weather(city: str) -> str: """获取城市天气信息""" return f"{city}今天天气晴朗" agent = Agent( name="weather-assistant", instructions="你是一个天气助手", model="gpt-4o", tools=[get_weather] ) ``` ### .NET 创建代理 ```csharp using Microsoft.Agents.AI; // 创建代理配置 var agentConfig = new AgentConfiguration { Name = "my-agent", Instructions = "代理指令", Model = "gpt-4o" }; // 使用 ChatClientAgent var agent = await persistentAgentsClient.CreateAIAgentAsync( model: "gpt-4o", name: "my-agent", instructions: "代理指令", tools: agentTools ); ``` 资料来源：[dotnet/src/Microsoft.Agents.AI.AzureAI.Persistent/PersistentAgentsClientExtensions.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI.AzureAI.Persistent/PersistentAgentsClientExtensions.cs) ### 代理配置参数 | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | name | string | 是 | 代理名称（kebab-case） | | instructions | string | 是 | 代理指令文本 | | description | string | 否 | 代理描述 | | model | string | 否 | 模型标识符 | | tools | IEnumerable | 否 | 可用工具列表 | | temperature | float | 否 | 温度参数（0.0-2.0） | | topP | float | 否 | Top-P 参数 | | responseFormat | object | 否 | 响应格式配置 | | metadata | dictionary | 否 | 自定义元数据 | 资料来源：[python/samples/01-get-started/README.md:20-25](https://github.com/microsoft/agent-framework/blob/main/python/samples/01-get-started/README.md#L20-L25) --- ## 技能（Skill）配置 ### 技能定义 代理技能支持通过前端资料（frontmatter）定义元数据： ```python from agent_framework.skills import AgentInlineSkill skill = AgentInlineSkill( name="my-skill", description="技能描述", instructions="技能指令", license="MIT", compatibility="v1.0+", allowedTools="tool1 tool2", metadata={"author": "developer"} ) ``` ### 技能资源目录 技能可以包含以下类型的资源目录： | 目录名 | 用途 | |--------|------| | references | 参考文档 | | assets | 静态资源 | | scripts | 脚本文件 | 默认资源目录为 `references` 和 `assets`，可通过 `ResourceDirectories` 自定义配置。 资料来源：[dotnet/src/Microsoft.Agents.AI/Skills/File/AgentFileSkillsSourceOptions.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Skills/File/AgentFileSkillsSourceOptions.cs) --- ## 工作流配置 ### 功能式工作流 ```python from agent_framework import workflow, agent @workflow async def my_workflow(input_data): result = await agent.invoke(input_data) return result ``` ### 图工作流 ```mermaid graph TD A[开始] --> B[代理节点1] B --> C{条件判断} C -->|成功| D[代理节点2] C -->|失败| E[错误处理] D --> F[结束] E --> F ``` 资料来源：[python/samples/01-get-started/README.md:28-32](https://github.com/microsoft/agent-framework/blob/main/python/samples/01-get-started/README.md#L28-L32) --- ## 故障排除 ### 常见问题 | 问题 | 解决方案 | |------|----------| | 包安装失败 | 检查 Python 版本是否满足要求（≥3.10） | | 环境变量未生效 | 确保重启终端或在新的 shell 会话中运行 | | Docker 构建失败 | 检查 Dockerfile 路径和上下文 | | 代理响应慢 | 检查网络连接和 API 限流设置 | ### 验证安装 ```bash # Python 验证 python -c "import agent_framework; print('OK')" # .NET 验证 dotnet list package | grep Microsoft.Agents ``` --- ## 下一步 安装配置完成后，建议按以下顺序学习框架： 1. [创建第一个代理](samples/01-get-started/README.md) 2. [添加自定义工具](samples/02_add_tools.py) 3. [多轮对话实现](samples/03_multi_turn.py) 4. [上下文管理](samples/04_memory.py) 5. [功能式工作流](samples/05_functional_workflow_with_agents.py) 6. [图工作流](samples/07_first_graph_workflow.py) --- ## 系统架构 ### 相关页面 相关主题：[核心概念](#core-concepts), [Agent 基础](#agent-basics)
相关源码文件 以下源码文件用于生成本页说明： - [python/packages/core/agent_framework/_agents.py](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/agent_framework/_agents.py) - [python/packages/core/agent_framework/_workflows/_workflow.py](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/agent_framework/_workflows/_workflow.py) - [dotnet/src/Microsoft.Agents.AI.Abstractions/AIAgent.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI.Abstractions/AIAgent.cs) - [dotnet/src/Microsoft.Agents.AI.Workflows/Workflow.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI.Workflows/Workflow.cs) - [python/samples/01-get-started/README.md](https://github.com/microsoft/agent-framework/blob/main/python/samples/01-get-started/README.md) - [dotnet/src/Microsoft.Agents.AI/Skills/AgentSkill.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Skills/AgentSkill.cs) - [dotnet/src/Microsoft.Agents.AI/Skills/AgentSkillsProvider.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Skills/AgentSkillsProvider.cs)
# 系统架构 Microsoft Agent Framework 是一个用于构建 AI Agent 的跨平台框架，同时支持 Python 和 .NET 两种语言实现。本页面详细介绍该框架的整体架构设计、核心组件及其交互关系。 ## 1. 架构概览 Agent Framework 采用分层架构设计，核心层负责 Agent 的生命周期管理和运行时调度，工作流层提供组合多个 Agent 的能力，外围层则包含工具系统、技能系统、会话管理等功能扩展。 ```mermaid graph TB subgraph "外围层" Tools["工具系统
@tool 装饰器"] Skills["技能系统
AgentSkill"] Memory["会话记忆
AgentSession"] end subgraph "核心层" Agent["Agent / AIAgent"] Runtime["运行时调度器"] end subgraph "工作流层" Workflow["工作流
Workflow"] Functional["函数式工作流"] Graph["图工作流"] end subgraph "通信层" LLM["LLM 接口"] Streaming["流式输出"] end Tools --> Agent Skills --> Agent Memory --> Agent Agent --> Runtime Runtime --> LLM Runtime --> Streaming Workflow --> Agent Functional --> Agent Graph --> Workflow ``` 框架的核心设计理念包括： - **声明式优先**：支持 YAML 配置文件定义 Agent 行为 - **工具扩展**：通过 `@tool` 装饰器或 `ToolDefinition` 定义外部能力 - **状态持久化**：AgentSession 支持多轮对话状态管理 - **工作流编排**：支持函数式和图结构工作流组合 ## 2. 核心组件 ### 2.1 Agent 抽象 Agent 是框架的核心抽象，代表一个具备 LLM 交互能力的智能体。在 Python 和 .NET 中均有对应实现。 | 属性 | 类型 | 说明 | |------|------|------| | name | string | Agent 名称标识 | | description | string | Agent 功能描述 | | instructions | string | 系统指令/提示词 | | tools | List[Tool] | 可用工具集合 | | toolResources | dict | 工具资源映射 | **Python 实现**：`agent_framework._agents` 模块 ```python # Python Agent 示例结构 (来源：python/packages/core/agent_framework/_agents.py) class Agent: def __init__( self, name: str, description: str | None = None, instructions: str | None = None, tools: list[Any] | None = None, # ... 其他参数 ): self.name = name self.description = description self.instructions = instructions self._tools = tools or [] ``` **NET 实现**：`Microsoft.Agents.AI.Abstractions.AIAgent` ```csharp // .NET AIAgent 接口定义 (来源：dotnet/src/Microsoft.Agents.AI.Abstractions/AIAgent.cs) public abstract class AIAgent { public string? Id { get; } public string? Name { get; } public string? Description { get; } public IList? Tools { get; } public string? Instructions { get; } } ``` ### 2.2 工作流系统 工作流（Workflow）是组合多个 Agent 或任务的编排机制。框架支持三种工作流模式： | 工作流类型 | 说明 | 适用场景 | |------------|------|----------| | 函数式工作流 | 异步函数组合 | 简单线性流程 | | 图工作流 | 节点-边有向图 | 条件分支流程 | | 声明式工作流 | YAML 配置定义 | 可视化编排 | **Python 工作流基类** (来源：`python/packages/core/agent_framework/_workflows/_workflow.py`)： ```python class Workflow(ABC): """工作流基类""" @property @abstractmethod def input_schema(self) -> dict | None: """输入参数模式""" pass @property @abstractmethod def output_schema(self) -> dict | None: """输出参数模式""" pass @abstractmethod async def run(self, input_data: Any) -> Any: """执行工作流""" pass ``` **.NET 工作流定义** (来源：`dotnet/src/Microsoft.Agents.AI.Workflows/Workflow.cs`)： ```csharp public abstract class Workflow { public abstract Task RunAsync( WorkflowState input, CancellationToken cancellationToken = default); } ``` ### 2.3 工具系统 工具是 Agent 调用外部能力的接口，支持函数定义和资源绑定。 ```python # @tool 装饰器示例 (来源：python/samples/01-get-started/README.md) from agent_framework import tool @tool def get_weather(location: str) -> str: """获取指定位置的天气信息""" # 工具实现 return f"{location} 的天气是晴天" ``` 工具定义包含以下属性： | 属性 | 说明 | 必需 | |------|------|------| | name | 工具名称 | 是 | | description | 工具功能描述 | 是 | | parameters | JSON Schema 参数定义 | 是 | | resources | 关联资源映射 | 否 | ## 3. 会话与上下文管理 ### 3.1 AgentSession 多轮会话 AgentSession 维护对话历史，支持跨请求的上下文保持。 ```mermaid graph LR A[用户输入 1] --> B[Agent] B --> C[LLM 响应 1] C --> D[Session 存储] D --> E[用户输入 2] E --> B B --> F[LLM 响应 2] ``` 关键特性： - 自动维护对话历史 - 支持流式和非流式输出 - 可扩展的记忆系统接口 ### 3.2 ContextProvider 上下文提供者 通过 ContextProvider 接口动态注入额外上下文： ```python class ContextProvider(Protocol): """上下文提供者协议""" async def get_context(self) -> str: """获取额外上下文""" pass ``` 使用示例 (来源：`python/samples/01-get-started/04_memory.py`)： ```python agent = Agent( name="my_agent", context_providers=[MyCustomContextProvider()] ) ``` ## 4. 技能系统 技能（Skill）是一种可复用的 Agent 能力封装，支持文件和代码两种定义方式。 ### 4.1 技能结构 | 组件 | 说明 | |------|------| | name | 技能名称（kebab-case） | | description | 技能描述 | | instructions | 技能指令文本 | | resources | 关联资源文件 | | scripts | 执行脚本 | 技能抽象定义 (来源：`dotnet/src/Microsoft.Agents.AI/Skills/AgentSkill.cs`)： ```csharp public abstract class AgentSkill { public abstract string Name { get; } public abstract string Description { get; } public abstract string Content { get; } public virtual IReadOnlyList? Resources => null; public virtual IReadOnlyList? Scripts => null; } ``` ### 4.2 技能加载流程 ```mermaid graph TD A[用户请求] --> B[AgentSkillsProvider] B --> C{技能源类型} C -->|文件| D[SKILL.md 解析] C -->|代码| E[AgentInlineSkill 实例化] D --> F[生成技能内容] E --> F F --> G[注入 Agent 上下文] G --> H[LLM 调用] ``` 技能提供者配置 (来源：`dotnet/src/Microsoft.Agents.AI/Skills/AgentSkillsProvider.cs`)： ```csharp // 默认技能指令模板 private const string DefaultSkillsInstructionPrompt = """ You have access to skills containing domain-specific knowledge and capabilities. {skills} When a task aligns with a skill's domain, follow these steps: - Use `load_skill` to retrieve the skill's instructions. - Follow the provided guidance. """; ``` ## 5. 部署与托管 框架支持多种部署模式： | 部署方式 | 说明 | 适用场景 | |----------|------|----------| | 本地运行 | 开发调试 | 本地开发 | | 容器化部署 | Docker 容器 | 生产环境 | | Azure Foundry | 云托管服务 | 企业级部署 | 托管示例项目 (来源：`dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Workflow-Simple/README.md`)： ```bash docker run -e FOUNDRY_PROJECT_ENDPOINT=$FOUNDRY_PROJECT_ENDPOINT \ -e AZURE_BEARER_TOKEN=$AZURE_BEARER_TOKEN \ --env-file .env \ hosted-workflow-simple ``` ## 6. 示例学习路径 框架提供渐进式学习示例 (来源：`python/samples/01-get-started/README.md`)： | 阶段 | 示例文件 | 学习内容 | |------|----------|----------| | 入门 | 01_hello_agent.py | 创建首个 Agent | | 进阶 | 02_add_tools.py | 添加工具 | | 多轮 | 03_multi_turn.py | AgentSession | | 记忆 | 04_memory.py | ContextProvider | | 工作流 | 05-06_functional_workflow | 函数式编排 | | 图工作流 | 07_first_graph_workflow | 节点图编排 | | 部署 | 08_host_your_agent.py | 服务托管 | ## 7. 集成扩展 ### 7.1 LLM 提供商支持 框架通过抽象接口支持多种 LLM 提供商： | 包 | 提供商 | 安装命令 | |----|--------|----------| | agent-framework (内置) | OpenAI / Azure OpenAI | pip install agent-framework | | agent-framework-claude | Anthropic Claude | pip install agent-framework-claude --pre | | agent-framework-declarative | YAML 配置 | pip install agent-framework-declarative --pre | ### 7.2 Azure 服务集成 框架深度集成 Azure AI 服务： - **Azure AI Foundry**：Agent 部署和托管 - **Azure Content Understanding**：文档、图像、音视频理解 - **Azure AI Search**：知识检索增强 集成示例 (来源：`python/packages/azure-contentunderstanding/samples/README.md`)： ```python # PDF 文档问答 from agent_framework_azure_contentunderstanding import DocumentProcessor processor = DocumentProcessor(endpoint=AZURE_CU_ENDPOINT) result = await processor.analyze("document.pdf", "总结本文要点") ``` ## 8. 总结 Microsoft Agent Framework 的架构设计遵循以下原则： 1. **跨平台一致性**：Python 和 .NET 实现保持 API 对齐 2. **可扩展性**：通过抽象接口支持自定义扩展 3. **声明式优先**：支持 YAML 配置降低使用门槛 4. **生产就绪**：内置监控、日志、错误处理等企业特性 框架核心位于 `agent_framework._agents` 和 `agent_framework._workflows` 模块，通过清晰的职责划分实现 Agent 创建、工作流编排、工具集成、会话管理的完整功能闭环。 --- ## 核心概念 ### 相关页面 相关主题：[系统架构](#architecture), [Agent 基础](#agent-basics)
相关源码文件 以下源码文件用于生成本页说明： - [python/packages/core/agent_framework/_types.py](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/agent_framework/_types.py) - [python/packages/core/agent_framework/_sessions.py](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/agent_framework/_sessions.py) - [dotnet/src/Microsoft.Agents.AI.Abstractions/AgentSession.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI.Abstractions/AgentSession.cs) - [dotnet/src/Microsoft.Agents.AI.Abstractions/AgentResponse.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI.Abstractions/AgentResponse.cs) - [dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs) - [dotnet/src/Microsoft.Agents.AI/Skills/AgentSkill.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Skills/AgentSkill.cs) - [dotnet/src/Microsoft.Agents.AI/Skills/Programmatic/AgentInlineSkill.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Skills/Programmatic/AgentInlineSkill.cs) - [dotnet/src/Microsoft.Agents.AI/Harness/AgentMode/AgentModeProviderOptions.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Harness/AgentMode/AgentModeProviderOptions.cs)
# 核心概念 Microsoft Agent Framework 是一个跨平台的多智能体开发框架，支持 Python 和 .NET 两种语言实现。该框架提供了构建、配置和运行 AI Agent 的完整基础设施，涵盖从基础的会话管理到复杂的多智能体工作流编排。 ## 框架架构概览 Agent Framework 采用分层架构设计，核心层负责会话状态管理和响应处理，应用层提供 Agent 的构建和工具集成能力。 ```mermaid graph TD subgraph "应用层" A1[ChatClientAgent] A2[AgentSkill] A3[AgentModeProvider] end subgraph "核心抽象层" C1[AgentSession] C2[AgentResponse] C3[AIContext] end subgraph "客户端层" B1[IChatClient] B2[PersistentAgentsClient] end A1 --> C1 A2 --> C1 A3 --> C1 C1 --> C2 B1 --> A1 B2 --> A1 ``` ## 核心数据类型 ### AgentSession（Agent 会话） `AgentSession` 是框架中管理多轮对话状态的核心抽象，封装了对话历史、用户标识和会话元数据。 ```csharp // dotnet/src/Microsoft.Agents.AI.Abstractions/AgentSession.cs public class AgentSession { public string? SessionId { get; set; } public string? AssistantId { get; set; } public string? UserId { get; set; } public DateTimeOffset? CreatedAt { get; set; } public IDictionary? Metadata { get; set; } public IList? Messages { get; set; } } ``` 资料来源：[dotnet/src/Microsoft.Agents.AI.Abstractions/AgentSession.cs]() | 属性 | 类型 | 说明 | |------|------|------| | `SessionId` | string? | 会话唯一标识符 | | `AssistantId` | string? | Assistant 标识 | | `UserId` | string? | 用户标识 | | `CreatedAt` | DateTimeOffset? | 会话创建时间 | | `Metadata` | IDictionary? | 会话元数据键值对 | | `Messages` | IList? | 消息历史列表 | ### AgentResponse（Agent 响应） `AgentResponse` 封装了 Agent 执行结果的完整信息，包括响应内容、工具调用、Token 使用统计等。 ```csharp // dotnet/src/Microsoft.Agents.AI.Abstractions/AgentResponse.cs public class AgentResponse { public string? Content { get; set; } public IList? ToolCalls { get; set; } public CompletionUsage? Usage { get; set; } public string? FinishReason { get; set; } } ``` 资料来源：[dotnet/src/Microsoft.Agents.AI.Abstractions/AgentResponse.cs]() | 属性 | 类型 | 说明 | |------|------|------| | `Content` | string? | 响应文本内容 | | `ToolCalls` | IList? | 调用的工具列表 | | `Usage` | CompletionUsage? | Token 使用统计 | | `FinishReason` | string? | 完成原因（如 stop、tool_calls） | ### Python 类型定义 Python SDK 提供了等效的类型定义，通过数据类实现会话和消息的建模。 ```python # python/packages/core/agent_framework/_types.py @dataclass class AgentSession: session_id: Optional[str] = None user_id: Optional[str] = None created_at: Optional[datetime] = None metadata: Optional[Dict[str, str]] = None @dataclass class TurnResponse: output: str tool_calls: Optional[List[ToolCall]] = None usage: Optional[Usage] = None session: AgentSession ``` 资料来源：[python/packages/core/agent_framework/_types.py]() ## Agent 类型体系 ### ChatClientAgent `ChatClientAgent` 是基于 `IChatClient` 的标准 Agent 实现，支持流式和非流式两种运行模式。 ```csharp // dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs public sealed class ChatClientAgent : AIAgent { public ChatClientAgent( IChatClient chatClient, string? instructions = null, string? name = null, string? description = null, IEnumerable? tools = null, ILoggerFactory? loggerFactory = null, IServiceProvider? services = null); } ``` 资料来源：[dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs]() | 构造参数 | 类型 | 说明 | |----------|------|------| | `chatClient` | IChatClient | 底层聊天客户端 | | `instructions` | string? | 系统级指令 | | `name` | string? | Agent 名称 | | `description` | string? | Agent 描述 | | `tools` | IEnumerable? | 可用工具集 | | `loggerFactory` | ILoggerFactory? | 日志工厂 | | `services` | IServiceProvider? | 依赖注入服务容器 | ### AgentSkill（技能） `AgentSkill` 是框架中的技能抽象基类，支持文件定义和代码定义两种方式。 ```mermaid classDiagram class AgentSkill { <> +Name : string +Description : string +Content : string +Resources : IReadOnlyList~AgentSkillResource~? +Scripts : IReadOnlyList~AgentSkillScript~? } class AgentInlineSkill { +Instructions : string +License : string? +Compatibility : string? +AllowedTools : string? +Metadata : AdditionalPropertiesDictionary? } class FileBasedSkill { +FilePath : string } AgentSkill <|-- AgentInlineSkill AgentSkill <|-- FileBasedSkill ``` 资料来源：[dotnet/src/Microsoft.Agents.AI/Skills/AgentSkill.cs]() **AgentInlineSkill** 支持通过代码直接定义技能： ```csharp // dotnet/src/Microsoft.Agents.AI/Skills/Programmatic/AgentInlineSkill.cs public class AgentInlineSkill : AgentSkill { public AgentInlineSkill( string name, string description, string instructions, string? license = null, string? compatibility = null, string? allowedTools = null, AdditionalPropertiesDictionary? metadata = null, JsonSerializerOptions? serializerOptions = null); } ``` 资料来源：[dotnet/src/Microsoft.Agents.AI/Skills/Programmatic/AgentInlineSkill.cs]() | 参数 | 类型 | 说明 | |------|------|------| | `name` | string | 技能名称（kebab-case） | | `description` | string | 技能描述 | | `instructions` | string | 技能指令文本 | | `license` | string? | 许可证名称 | | `compatibility` | string? | 兼容性信息（最多500字符） | | `allowedTools` | string? | 预批准工具空格分隔列表 | | `metadata` | AdditionalPropertiesDictionary? | 自定义元数据 | | `serializerOptions` | JsonSerializerOptions? | JSON 序列化选项 | ## 会话管理 ### AgentSession 的生命周期 ```mermaid stateDiagram-v2 [*] --> 创建会话: 首次交互 创建会话 --> 活跃: 添加用户消息 活跃 --> 活跃: 多轮对话 活跃 --> 结束: 显式关闭或超时 结束 --> [*]: 资源释放 创建会话 --> 错误: 参数验证失败 活跃 --> 错误: 服务不可用 错误 --> [*]: 错误处理 ``` ### Python 会话管理 Python SDK 提供了 `AgentSession` 类的完整实现： ```python # python/packages/core/agent_framework/_sessions.py class AgentSession(ABC): @abstractmethod async def run(self, prompt: str, *args, **kwargs) -> TurnResponse: ... @abstractmethod async def run_streaming(self, prompt: str, *args, **kwargs) -> AsyncIterator[TurnResponse]: ... @abstractmethod async def reset(self) -> None: ... ``` 资料来源：[python/packages/core/agent_framework/_sessions.py]() | 方法 | 返回类型 | 说明 | |------|----------|------| | `run` | TurnResponse | 非流式执行单个轮次 | | `run_streaming` | AsyncIterator[TurnResponse] | 流式执行 | | `reset` | None | 重置会话状态 | ## Agent 模式（AgentMode） `AgentMode` 定义了 Agent 的运行模式，支持交互式规划和自主执行两种模式。 ```csharp // dotnet/src/Microsoft.Agents.AI/Harness/AgentMode/AgentModeProviderOptions.cs public sealed class AgentMode { public string Name { get; } public string Description { get; } public AgentMode(string name, string description); } public class AgentModeProviderOptions { public IReadOnlyList? Modes { get; set; } public string? DefaultMode { get; set; } } ``` 资料来源：[dotnet/src/Microsoft.Agents.AI/Harness/AgentMode/AgentModeProviderOptions.cs]() | 模式名称 | 说明 | |----------|------| | `plan` | 交互式规划模式 | | `execute` | 自主执行模式 | ## 工作流程集成 ### 多 Agent 协作 框架支持将多个 Agent 组合成工作流，实现复杂的任务分解和执行： ```mermaid graph LR subgraph "工作流" W1[主 Agent] W2[子 Agent 1] W3[子 Agent 2] W4[聚合器] end W1 --> W2 W1 --> W3 W2 --> W4 W3 --> W4 ``` ### 工具系统 框架的工具系统支持两种调用方式： | 调用方式 | 触发条件 | 用户确认 | |----------|----------|----------| | 自动调用 | AI 自动选择 | 默认无需确认 | | 请求确认 | 高风险操作 | 需要显式批准 | > [!NOTE] > 默认情况下，所有提供的工具都会自动调用。AI 选择调用的函数和参数应被视为不受信任的输入。开发者应为具有副作用、访问敏感数据或执行不可逆操作的工具要求显式批准。 资料来源：[dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs]() ## 快速入门示例 ### Python 示例 ```python # 创建基础 Agent from agent_framework import Agent agent = Agent( model="gpt-4o", instructions="你是一个有帮助的助手" ) # 非流式运行 response = await agent.run("今天天气怎么样？") print(response.output) # 流式运行 async for chunk in agent.run_streaming("讲个故事"): print(chunk.output, end="", flush=True) ``` ### .NET 示例 ```csharp // 创建 ChatClientAgent var agent = new ChatClientAgent( chatClient: chatClient, instructions: "You are a helpful assistant", name: "Assistant", description: "A general purpose assistant", tools: myTools); // 运行 Agent var response = await agent.RunAsync("Hello, how are you?"); ``` ## 核心概念总结 | 概念 | 作用 | 关键文件 | |------|------|----------| | AgentSession | 管理会话状态和消息历史 | _sessions.py, AgentSession.cs | | AgentResponse | 封装执行结果 | AgentResponse.cs | | ChatClientAgent | 基于 IChatClient 的 Agent 实现 | ChatClientAgent.cs | | AgentSkill | 技能抽象，支持文件和代码定义 | AgentSkill.cs | | AgentMode | 定义运行模式（plan/execute） | AgentModeProviderOptions.cs | | ContextProvider | 提供动态上下文 | AgentSkillsProvider.cs | --- ## Agent 基础 ### 相关页面 相关主题：[工具与技能系统](#agent-tools), [模型提供商集成](#agent-providers)
相关源码文件 以下源码文件用于生成本页说明： - [python/packages/core/agent_framework/_agents.py](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/agent_framework/_agents.py) - [python/samples/01-get-started/01_hello_agent.py](https://github.com/microsoft/agent-framework/blob/main/python/samples/01-get-started/01_hello_agent.py) - [dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs) - [dotnet/samples/01-get-started/01_hello_agent/Program.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/samples/01-get-started/01_hello_agent/Program.cs) - [dotnet/src/Microsoft.Agents.AI.Hosting.OpenAI/Responses/Models/AgentId.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI.Hosting.OpenAI/Responses/Models/AgentId.cs) - [README.md](https://github.com/microsoft/agent-framework/blob/main/README.md) - [python/README.md](https://github.com/microsoft/agent-framework/blob/main/python/README.md)
# Agent 基础 ## 概述 Agent（智能体）是 Microsoft Agent Framework 的核心抽象单元，代表能够理解自然语言、调用工具并执行复杂任务的 AI 驱动的软件实体。在 Agent Framework 中，Agent 作为一个封装了 AI 客户端、指令、工具和会话状态的可组合单元，为开发者提供了构建 AI 应用的基础构建块。 Agent 的核心职责包括： - 接收用户输入并生成响应 - 管理对话历史和多轮交互 - 调用工具扩展能力边界 - 集成多种 AI 服务提供商（如 Azure OpenAI、OpenAI、GitHub Copilot、Claude 等） 资料来源：[python/packages/core/agent_framework/_agents.py:1-50](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/agent_framework/_agents.py) ## Agent 的核心组件 ### Python 实现架构 Python Agent 由以下核心类组成： | 类名 | 用途 | |------|------| | `Agent` | 主入口类，封装客户端和指令 | | `ChatCompletionMessage` | 聊天消息的数据结构 | | `ChatClientProtocol` | 聊天客户端接口协议 | | `FunctionSpec` | 函数工具的规范定义 | 资料来源：[python/packages/core/agent_framework/_agents.py:1-100](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/agent_framework/_agents.py) ### .NET 实现架构 在 .NET 侧，`ChatClientAgent` 类是核心实现： ```csharp public sealed class ChatClientAgent : AIAgent ``` | 属性 | 类型 | 说明 | |------|------|------| | `Instructions` | `string?` | 系统指令，指导 Agent 行为 | | `Tools` | `IList?` | Agent 可调用的工具集合 | | `LoggerFactory` | `ILoggerFactory?` | 日志工厂 | | `Services` | `IServiceProvider?` | 依赖注入服务提供器 | 资料来源：[dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs:30-80](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs) ### Agent 标识模型 ```mermaid classDiagram class AgentId { +AgentIdType Type +string Name +string Version } class AgentIdType { +string Value } AgentId --> AgentIdType : contains ``` `AgentId` 类用于标识特定的 Agent 实例，包含类型、名称和版本信息。 资料来源：[dotnet/src/Microsoft.Agents.AI.Hosting.OpenAI/Responses/Models/AgentId.cs:10-40](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI.Hosting.OpenAI/Responses/Models/AgentId.cs) ## Agent 的创建与初始化 ### Python 创建模式 ```python from agent_framework import Agent, FoundryChatClient from azure.identity import AzureCliCredential agent = Agent( client=FoundryChatClient( credential=AzureCliCredential(), project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"], ), name="HaikuAgent", instructions="You are an upbeat assistant that writes beautifully.", ) ``` Python Agent 构造函数接受以下核心参数： | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | `client` | `ChatClientProtocol` | 是 | AI 聊天客户端实例 | | `name` | `str` | 否 | Agent 名称，用于标识和日志 | | `instructions` | `str` | 否 | 系统提示词 | 资料来源：[python/samples/01-get-started/01_hello_agent.py:1-50](https://github.com/microsoft/agent-framework/blob/main/python/samples/01-get-started/01_hello_agent.py) ### .NET 创建模式 ```csharp using Azure.AI.Projects; using Azure.Identity; using Microsoft.Agents.AI; AIAgent agent = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential()) .AsAIAgent( model: deploymentName, instructions: "You are an upbeat assistant.", name: "HaikuAgent" ); ``` .NET 通过扩展方法 `AsAIAgent()` 将 `AIProjectClient` 转换为 `AIAgent` 实例。 资料来源：[dotnet/samples/01-get-started/01_hello_agent/Program.cs:1-30](https://github.com/microsoft/agent-framework/blob/main/dotnet/samples/01-get-started/01_hello_agent/Program.cs) ### 初始化流程 ```mermaid sequenceDiagram participant User participant Agent participant Client participant AI_Service User->>Agent: 创建 Agent 实例 Agent->>Client: 初始化 ChatClient Client->>AI_Service: 建立连接 AI_Service-->>Client: 连接成功 Client-->>Agent: 客户端就绪 Agent-->>User: Agent 初始化完成 ``` ## Agent 的运行机制 ### 单轮对话执行 ```mermaid graph TD A[用户输入] --> B[Agent.run] B --> C[构建 ChatOptions] C --> D[调用 ChatClient] D --> E[AI 模型处理] E --> F[返回消息] F --> G[解析响应] G --> H[返回结果] ``` Agent 的 `run()` 方法执行单轮对话，输入直接转换为输出，不保留会话历史。 资料来源：[python/packages/core/agent_framework/_agents.py:100-150](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/agent_framework/_agents.py) ### 消息格式 Agent 使用结构化的消息格式进行通信： | 消息类型 | 说明 | |----------|------| | `user` | 用户发送的消息 | | `assistant` | AI 生成的回复 | | `tool` | 工具调用请求或结果 | ## 工具集成 ### 工具定义 Agent 通过工具扩展其能力范围。工具可以是： - **函数工具**：Python 函数或 .NET 方法，通过装饰器/属性暴露给 AI - **外部 API**：通过 HTTP 调用的远程服务 - **脚本**：可执行的代码片段 ### Python 工具定义示例 ```python from agent_framework import tool @tool def get_weather(city: str) -> str: """获取指定城市的天气信息""" return f"{city} 今天的天气是晴天，25°C" ``` 资料来源：[python/samples/01-get-started/02_add_tools.py](https://github.com/microsoft/agent-framework/blob/main/python/samples/01-get-started/02_add_tools.py) ### .NET 工具定义 在 .NET 中，工具通过 `AITool` 接口实现，并可在创建 Agent 时传入： ```csharp AIAgent agent = client.AsAIAgent( tools: new List { customTool }, instructions: "Instructions here" ); ``` ## 多轮对话与会话管理 ### Python 会话管理 Python Agent 通过 `AgentSession` 类管理多轮对话： ```python from agent_framework import AgentSession async with AgentSession(agent=agent) as session: response1 = await session.run("你好") response2 = await session.run("请帮我查询天气") ``` 会话自动维护消息历史，支持跨多次交互的上下文理解。 资料来源：[python/samples/01-get-started/03_multi_turn.py](https://github.com/microsoft/agent-framework/blob/main/python/samples/01-get-started/03_multi_turn.py) ### .NET 会话管理 ```csharp // 使用 AIProjectClient 的 AsAIAgent 返回 AIAgent // AIAgent 内部管理会话状态 string response = await agent.RunAsync("Hello, how are you?"); ``` ### 会话状态流转 ```mermaid stateDiagram-v2 [*] --> 初始化: 创建 Agent 初始化 --> 就绪: 客户端连接 就绪 --> 处理中: 接收用户消息 处理中 --> 等待工具: 需要调用工具 等待工具 --> 处理中: 工具返回结果 处理中 --> 就绪: 生成最终响应 就绪 --> [*]: 会话结束 ``` ## 流式响应支持 Agent 支持流式输出模式，适合需要实时反馈的场景： ### Python 流式调用 ```python async for event in agent.run("讲一个故事", stream=True): print(event.delta, end="", flush=True) ``` ### .NET 流式调用 ```csharp await foreach (var update in agent.RunAsync("Tell me a story", stream: true)) { Console.Write(update.Content); } ``` ## 上下文提供者 Agent 支持通过 `ContextProvider` 接口注入动态上下文： ```python from agent_framework import ContextProvider class CustomContextProvider(ContextProvider): async def get_context(self) -> str: # 返回动态生成的上下文 return "当前时间: 2024-01-01" ``` 资料来源：[python/samples/01-get-started/04_memory.py](https://github.com/microsoft/agent-framework/blob/main/python/samples/01-get-started/04_memory.py) ## 错误处理与日志 ### 异常处理 Agent 运行时可能遇到以下异常类型： | 异常 | 说明 | |------|------| | `AgentException` | Agent 执行基础异常 | | `ToolExecutionException` | 工具执行失败 | | `AuthenticationException` | 认证失败 | | `RateLimitException` | 速率限制触发 | ### 日志配置 ```csharp // .NET 日志配置 var loggerFactory = LoggerFactory.Create(builder => builder.AddConsole()); AIAgent agent = new ChatClientAgent(client, loggerFactory: loggerFactory); ``` ```python # Python 日志配置 import logging logging.basicConfig(level=logging.DEBUG) ``` ## 最佳实践 ### 设计原则 1. **清晰的指令设计**：编写明确、简洁的系统指令，避免歧义 2. **合理的工具粒度**：工具应职责单一，便于 AI 理解和调用 3. **适当的超时设置**：为长时间运行的操作设置超时 4. **状态管理**：善用会话管理维护对话上下文 ### 性能优化 | 策略 | 说明 | |------|------| | 工具缓存 | 避免重复初始化昂贵的工具资源 | | 上下文压缩 | 长对话中适当压缩历史消息 | | 并行工具调用 | 支持 AI 并行调用多个独立工具 | ### 安全考虑 - 对具有副作用的工具强制要求用户确认 - 敏感操作实施访问控制 - 验证工具返回结果的合法性 ## 相关资源 - [Agent Framework 官方文档](https://github.com/microsoft/agent-framework) - [Python SDK 快速开始](https://github.com/microsoft/agent-framework/blob/main/python/samples/01-get-started/README.md) - [示例代码库](../samples/) --- ## 模型提供商集成 ### 相关页面 相关主题：[Agent 基础](#agent-basics)
相关源码文件 以下源码文件用于生成本页说明： - [python/packages/openai/agent_framework_openai/_chat_client.py](https://github.com/microsoft/agent-framework/blob/main/python/packages/openai/agent_framework_openai/_chat_client.py) - [python/packages/foundry/agent_framework_foundry/_chat_client.py](https://github.com/microsoft/agent-framework/blob/main/python/packages/foundry/agent_framework_foundry/_chat_client.py) - [python/packages/anthropic/agent_framework_anthropic/_chat_client.py](https://github.com/microsoft/agent-framework/blob/main/python/packages/anthropic/agent_framework_anthropic/_chat_client.py) - [dotnet/src/Microsoft.Agents.AI.Foundry/FoundryAgent.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI.Foundry/FoundryAgent.cs) - [dotnet/src/Microsoft.Agents.AI.OpenAI/Extensions/OpenAIChatClientExtensions.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI.OpenAI/Extensions/OpenAIChatClientExtensions.cs)
# 模型提供商集成 ## 概述 模型提供商集成（Model Provider Integration）是 Microsoft Agent Framework 的核心架构特性，允许框架通过统一的抽象接口接入多种大语言模型（LLM）提供商。该设计使开发者能够在不修改核心业务逻辑的情况下，灵活切换不同的 AI 后端服务。 Agent Framework 的模型提供商集成具有以下核心目标： - **统一抽象**：为不同提供商提供一致的 API 接口 - **多后端支持**：支持 OpenAI、Azure OpenAI、Azure AI Foundry、Anthropic Claude 等主流服务商 - **配置灵活性**：通过环境变量或代码配置多种参数 - **流式响应**：支持流式和非流式两种响应模式 - **工具调用**：统一的函数调用（Function Calling）能力抽象 资料来源：[python/packages/openai/README.md](https://github.com/microsoft/agent-framework/blob/main/python/packages/openai/README.md) ## 架构设计 ### 整体架构 Agent Framework 采用分层架构设计，模型提供商作为独立的包存在，通过标准化的接口与核心框架解耦： ```mermaid graph TD A[Agent / 业务逻辑层] --> B[核心框架层
agent_framework.core] B --> C[聊天客户端抽象层
IChatClient / ChatClientBase] C --> D[提供商特定实现层] D --> E[OpenAI] D --> F[Azure OpenAI] D --> G[Azure AI Foundry] D --> H[Anthropic Claude] E --> E1[Responses API] E --> E2[Chat Completions API] ``` 资料来源：[python/packages/core/README.md](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/README.md) ### Python 生态中的聊天客户端 Python 版本的 Agent Framework 为每个提供商提供了独立的聊天客户端类，这些类均继承自统一的基类或实现相同的接口： | 提供商 | 包名 | 主要类 | API 类型 | |--------|------|--------|----------| | OpenAI | `agent-framework-openai` | `OpenAIChatClient` | Responses API（推荐） | | OpenAI | `agent-framework-openai` | `OpenAIChatCompletionClient` | Chat Completions API | | Azure AI Foundry | `agent-framework-foundry` | `FoundryChatClient` | Azure Foundry 原生 | | Anthropic | `agent-framework-anthropic` | `AnthropicChatClient` | Claude API | 资料来源：[python/packages/openai/README.md](https://github.com/microsoft/agent-framework/blob/main/python/packages/openai/README.md) ### .NET 生态中的聊天客户端 .NET 版本采用类似的架构，通过扩展方法将聊天客户端转换为代理： ```mermaid graph LR A[IChatClient] --> B[ChatClientAgent] B --> C[AsAIAgent 扩展方法] D[OpenAI ChatClient] --> C E[Azure OpenAI Client] --> C F[FoundryChatClient] --> C ``` 资料来源：[dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs) ## OpenAI 集成 ### Python 实现 Python 的 `agent-framework-openai` 包提供了两个聊天客户端类，分别对应 OpenAI 的两种 API： #### OpenAIChatClient（Responses API） 这是推荐使用的客户端，使用 OpenAI 的 Responses API： ```python from agent_framework.openai import OpenAIChatClient client = OpenAIChatClient( api_key="sk-...", model="gpt-4o" ) ``` 模型优先级：`OPENAI_CHAT_MODEL` → `OPENAI_MODEL` 资料来源：[python/packages/openai/README.md](https://github.com/microsoft/agent-framework/blob/main/python/packages/openai/README.md) #### OpenAIChatCompletionClient（Chat Completions API） 此客户端使用传统的 Chat Completions API，主要用于兼容现有集成： ```python from agent_framework.openai import OpenAIChatCompletionClient client = OpenAIChatCompletionClient( api_key="sk-...", model="gpt-4o-mini" ) ``` 模型优先级：`OPENAI_CHAT_COMPLETION_MODEL` → `OPENAI_MODEL` 资料来源：[python/packages/openai/README.md](https://github.com/microsoft/agent-framework/blob/main/python/packages/openai/README.md) ### 环境变量配置 | 变量名 | 用途 | |--------|------| | `OPENAI_API_KEY` | OpenAI API 密钥 | | `OPENAI_ORG_ID` | OpenAI 组织 ID | | `OPENAI_BASE_URL` | 自定义 OpenAI 兼容 API 地址 | | `OPENAI_MODEL` | 通用默认模型 | | `OPENAI_CHAT_MODEL` | `OpenAIChatClient` 首选模型 | | `OPENAI_CHAT_COMPLETION_MODEL` | `OpenAIChatCompletionClient` 首选模型 | | `OPENAI_EMBEDDING_MODEL` | `OpenAIEmbeddingClient` 首选模型 | 资料来源：[python/packages/openai/README.md](https://github.com/microsoft/agent-framework/blob/main/python/packages/openai/README.md) ### .NET 实现 在 .NET 生态中，通过 `OpenAIChatClientExtensions` 扩展方法将 `ChatClient` 转换为 `Agent`： ```csharp using Microsoft.Agents.AI.OpenAI.Extensions; ChatClientAgent agent = chatClient.AsAIAgent( name: "ChatAssistant", instructions: "You are a helpful coding assistant specializing in C# and .NET."); ``` 资料来源：[dotnet/src/Microsoft.Agents.AI.OpenAI/Extensions/OpenAIChatClientExtensions.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI.OpenAI/Extensions/OpenAIChatClientExtensions.cs) ## Azure AI Foundry 集成 ### Python 实现 `agent-framework-foundry` 包提供了与 Azure AI Foundry 的深度集成： ```python from agent_framework_foundry import FoundryChatClient client = FoundryChatClient( project_endpoint="https://your-project.services.ai.azure.com", model="gpt-4o" ) ``` Azure AI Foundry 集成主要使用环境变量配置： | 变量名 | 用途 | |--------|------| | `FOUNDRY_PROJECT_ENDPOINT` | Foundry 项目端点 | | `FOUNDRY_MODEL` | 使用的模型名称 | 资料来源：[python/packages/core/README.md](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/README.md) ### .NET 实现 ```csharp using Microsoft.Agents.AI.Foundry; FoundryAgent agent = new FoundryAgent( projectEndpoint: "https://your-project.services.ai.azure.com", deploymentName: "gpt-4o" ); ``` 资料来源：[dotnet/src/Microsoft.Agents.AI.Foundry/FoundryAgent.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI.Foundry/FoundryAgent.cs) ## Anthropic Claude 集成 ### Python 实现 `agent-framework-anthropic` 包提供了 Claude 模型的集成： ```python from agent_framework_anthropic import AnthropicChatClient client = AnthropicChatClient( api_key="sk-ant-...", model="claude-3-5-sonnet-20241022" ) ``` Anthropic 集成允许开发者使用 Claude 系列模型，与 OpenAI 风格的接口保持一致。 资料来源：[python/packages/anthropic/agent_framework_anthropic/_chat_client.py](https://github.com/microsoft/agent-framework/blob/main/python/packages/anthropic/agent_framework_anthropic/_chat_client.py) ## 核心使用模式 ### 模式一：直接使用聊天客户端 适用于高级工作流，直接与聊天 API 交互： ```python import asyncio from agent_framework.openai import OpenAIChatClient from agent_framework import Message, Role async def main(): client = OpenAIChatClient() response = await client.get_response([ Message("system", ["You are a helpful assistant."]), Message("user", ["Write a haiku about Agent Framework."]) ]) print(response.messages[0].text) asyncio.run(main()) ``` 资料来源：[python/packages/core/README.md](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/README.md) ### 模式二：创建代理 使用聊天客户端创建 Agent，让框架处理对话管理： ```python from agent_framework import Agent from agent_framework.openai import OpenAIChatClient agent = Agent( client=OpenAIChatClient(), instructions="你是一个有帮助的编程助手。" ) result = await agent.run("解释什么是函数调用") ``` 资料来源：[python/packages/core/README.md](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/README.md) ### 模式三：带工具的代理 为代理添加工具（函数调用）能力： ```python from typing import Annotated from agent_framework import Agent from agent_framework.openai import OpenAIChatClient def get_weather( location: Annotated[str, "要查询天气的城市"] ) -> str: """获取指定城市的天气信息""" return f"{location} 今天天气晴朗，温度 22°C" agent = Agent( client=OpenAIChatClient(), instructions="你是一个天气助手。", tools=[get_weather] ) ``` 资料来源：[python/packages/core/README.md](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/README.md) ## 代理创建参数 ### ChatClientAgent 参数说明 | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | `chatClient` | `IChatClient` | 是 | 用于执行聊天的客户端实例 | | `instructions` | `string?` | 否 | 系统指令，指导代理行为 | | `name` | `string?` | 否 | 代理名称，用于识别和日志记录 | | `description` | `string?` | 否 | 人类可读的代理描述 | | `tools` | `IReadOnlyList?` | 否 | 代理可调用的工具集合 | | `loggerFactory` | `ILoggerFactory?` | 否 | 日志工厂实例 | | `services` | `IServiceProvider?` | 否 | 依赖注入服务提供者 | 资料来源：[dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs) ## 提供商选择指南 ### 选择 OpenAI 的场景 - 新项目推荐使用 Responses API（`OpenAIChatClient`） - 需要兼容现有 Chat Completions 代码时使用 `OpenAIChatCompletionClient` - 需要快速原型开发 ### 选择 Azure OpenAI 的场景 - 企业已有 Azure 订阅 - 需要 Azure 的安全合规特性 - 与其他 Azure 服务集成 ### 选择 Azure AI Foundry 的场景 - 使用 Azure AI Foundry 作为主要推理服务 - 需要 Foundry 特有的功能（如高级模型路由） ### 选择 Anthropic Claude 的场景 - 需要 Claude 的长上下文能力 - 偏好 Anthropic 的安全对齐特性 - 特定场景下 Claude 表现更优 ## 流式响应支持 所有聊天客户端均支持流式响应模式： ### Python 流式调用 ```python async for chunk in client.stream([Message("user", ["你好"])]): print(chunk.content, end="", flush=True) ``` ### .NET 流式调用 ```csharp await foreach (var update in agent.RunAsyncStreaming( new ChatMessage(ChatRole.User, "Hello"))) { Console.Write(update.Content); } ``` ## 多提供商工作流 Agent Framework 支持在同一应用中混合使用多个提供商： ```python from agent_framework.openai import OpenAIChatClient from agent_framework_foundry import FoundryChatClient from agent_framework import Agent # 不同任务使用不同提供商 router_agent = Agent( client=OpenAIChatClient(), instructions="你是任务路由器，将问题分类并路由到合适的处理代理。" ) # 编码任务使用 Claude coding_agent = Agent( client=AnthropicChatClient(), instructions="你是一个专业程序员。" ) # 简单问答使用轻量模型 qa_agent = Agent( client=OpenAIChatCompletionClient(model="gpt-4o-mini"), instructions="你是一个简洁的问答助手。" ) ``` ## 配置最佳实践 ### 开发环境 ```bash # .env 文件 OPENAI_API_KEY=sk-... OPENAI_CHAT_MODEL=gpt-4o-mini # 或使用 Azure AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/ AZURE_OPENAI_API_KEY=... AZURE_OPENAI_MODEL=gpt-4o ``` ### 生产环境 建议使用密钥管理服务： - Azure: 使用 Azure Key Vault - AWS: 使用 AWS Secrets Manager - 通用: 环境变量或配置服务 ### 客户端配置覆盖 环境变量可以被代码参数覆盖： ```python client = OpenAIChatClient( api_key="from-secret-manager", model="gpt-4o" ) ``` 资料来源：[python/packages/core/README.md](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/README.md) ## 相关资源 - [Python 快速开始示例](https://github.com/microsoft/agent-framework/tree/main/python/samples/01-get-started) - [OpenAI 包文档](https://github.com/microsoft/agent-framework/tree/main/python/packages/openai) - [Foundry 包文档](https://github.com/microsoft/agent-framework/tree/main/python/packages/foundry) - [Anthropic 包文档](https://github.com/microsoft/agent-framework/tree/main/python/packages/anthropic) - [.NET 示例：OpenAI Responses](https://github.com/microsoft/agent-framework/tree/main/dotnet/samples/02-agents/AgentProviders/Agent_With_OpenAIResponses) - [.NET 示例：OpenAI Chat Completion](https://github.com/microsoft/agent-framework/tree/main/dotnet/samples/02-agents/AgentProviders/Agent_With_OpenAIChatCompletion) --- ## 工具与技能系统 ### 相关页面 相关主题：[Agent 基础](#agent-basics)
相关源码文件 以下源码文件用于生成本页说明： - [python/packages/core/agent_framework/_tools.py](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/agent_framework/_tools.py) - [python/packages/core/agent_framework/_skills.py](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/agent_framework/_skills.py) - [dotnet/src/Microsoft.Agents.AI/Skills/AgentSkill.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Skills/AgentSkill.cs) - [dotnet/src/Microsoft.Agents.AI/Skills/AgentSkillsProvider.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Skills/AgentSkillsProvider.cs) - [dotnet/src/Microsoft.Agents.AI/Skills/Programmatic/AgentInlineSkill.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Skills/Programmatic/AgentInlineSkill.cs) - [dotnet/src/Microsoft.Agents.AI/Skills/Programmatic/AgentInlineSkillContentBuilder.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Skills/Programmatic/AgentInlineSkillContentBuilder.cs)
# 工具与技能系统 ## 概述 Agent Framework 的**工具与技能系统**是框架的核心扩展机制，旨在赋予 AI Agent 执行特定任务和访问领域知识的能力。该系统由两个相互关联但功能独立的子系统组成： - **工具系统 (Tools)**：为 Agent 提供可调用的函数能力，实现与外部系统的交互 - **技能系统 (Skills)**：为 Agent 提供领域特定的指令、文档和资源，实现知识驱动的任务执行 资料来源：[python/samples/01-get-started/README.md](https://github.com/microsoft/agent-framework/blob/main/python/samples/01-get-started/README.md) ## 系统架构 ```mermaid graph TD subgraph "Agent Framework 工具与技能系统" subgraph "工具层 (Tools)" A[Function Tool] --> B[ToolDefinition] C[FileMemory Tool] --> B D[Custom Tools] --> B end subgraph "技能层 (Skills)" E[AgentSkill 抽象基类] --> F[FileBasedSkill] E --> G[AgentInlineSkill] G --> H[AgentInlineSkillContentBuilder] end subgraph "技能提供者" I[AgentSkillsProvider] --> E J[AIContext] --> I end subgraph "Agent 核心" K[ChatClientAgent] --> L[工具调用] K --> M[技能加载] L --> B M --> I end end ``` ## 工具系统 ### 工具定义 工具系统基于函数工具定义，Agent 可以通过调用这些工具执行特定操作。工具定义包含以下核心属性： | 属性 | 类型 | 说明 | |------|------|------| | name | string | 工具名称，用于标识和调用 | | description | string | 工具功能描述，供 LLM 理解何时使用 | | parameters | JSON Schema | 工具参数规范 | | handler | Function | 工具执行逻辑 | 资料来源：[dotnet/src/Microsoft.Agents.AI/Harness/FileMemory/FileMemoryProvider.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Harness/FileMemory/FileMemoryProvider.cs) ### 内置工具示例 #### FileMemory 工具集 FileMemory 系统提供了一套完整的文件管理工具，Agent 可以使用这些工具进行持久化存储和知识检索： | 工具名称 | 功能 | |----------|------| | FileMemory_ReadFile | 读取内存文件内容 | | FileMemory_ListFiles | 列出可用的内存文件 | | FileMemory_SaveFile | 保存或更新内存文件 | | FileMemory_SearchFiles | 搜索内存文件内容 | ```csharp [Description("Save a memory file with the given name and content. Overwrites the file if it already exists. Include a description for large files to provide a summary that helps with discovery.")] private async Task SaveFileAsync( string fileName, string content, string? description = null, CancellationToken cancellationToken = default) ``` 资料来源：[dotnet/src/Microsoft.Agents.AI/Harness/FileMemory/FileMemoryProvider.cs:54-60](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Harness/FileMemory/FileMemoryProvider.cs) ### 工具注册与调用流程 ```mermaid sequenceDiagram participant User as 用户 participant Agent as ChatClientAgent participant Tools as 工具系统 participant LLM as 语言模型 User->>Agent: 发送请求 Agent->>LLM: 发送包含工具定义的请求 LLM->>LLM: 分析任务，决定调用工具 LLM->>Agent: 返回工具调用请求 Agent->>Tools: 执行工具函数 Tools->>Tools: 处理业务逻辑 Tools-->>Agent: 返回执行结果 Agent->>LLM: 发送工具结果 LLM-->>Agent: 生成最终响应 Agent-->>User: 返回结果 ``` ## 技能系统 ### 技能架构概述 技能系统采用抽象基类设计，支持多种技能定义方式： ```mermaid classDiagram class AgentSkill { <> +Content: string {abstract} +Resources: IReadOnlyList~AgentSkillResource~? +Scripts: IReadOnlyList~AgentSkillScript~? } class FileBasedSkill { +Content: string } class AgentInlineSkill { +Name: string +Description: string +Instructions: string +License: string? +Compatibility: string? +AllowedTools: string? +Metadata: AdditionalPropertiesDictionary? } AgentSkill <|-- FileBasedSkill AgentSkill <|-- AgentInlineSkill ``` 资料来源：[dotnet/src/Microsoft.Agents.AI/Skills/AgentSkill.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Skills/AgentSkill.cs) ### AgentSkill 抽象基类 `AgentSkill` 是所有技能类型的基类，定义了技能的通用接口： ```csharp /// /// For file-based skills this is the raw SKILL.md file content, optionally /// augmented with a synthesized scripts block when scripts are present. /// For code-defined skills this is a synthesized XML document /// containing name, description, and body (instructions, resources, scripts). /// public abstract string Content { get; } /// /// Gets the resources associated with this skill, or null if none. /// public virtual IReadOnlyList? Resources => null; /// /// Gets the scripts associated with this skill, or null if none. /// public virtual IReadOnlyList? Scripts => null; ``` 资料来源：[dotnet/src/Microsoft.Agents.AI/Skills/AgentSkill.cs:15-35](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Skills/AgentSkill.cs) ### 代码定义技能 (AgentInlineSkill) `AgentInlineSkill` 允许开发者以编程方式定义技能，无需使用外部文件： ```csharp public AgentInlineSkill( string name, string description, string instructions, string? license = null, string? compatibility = null, string? allowedTools = null, AdditionalPropertiesDictionary? metadata = null, JsonSerializerOptions? serializerOptions = null) ``` #### 构造函数参数说明 | 参数 | 类型 | 必需 | 说明 | |------|------|------|------| | name | string | 是 | 技能名称，使用 kebab-case 格式 | | description | string | 是 | 技能描述，用于发现和选择 | | instructions | string | 是 | 技能指令文本 | | license | string? | 否 | 许可证名称或引用 | | compatibility | string? | 否 | 兼容性信息（最多 500 字符） | | allowedTools | string? | 否 | 预批准工具的空格分隔列表 | | metadata | AdditionalPropertiesDictionary? | 否 | 任意键值元数据 | | serializerOptions | JsonSerializerOptions? | 否 | 脚本和资源序列化选项 | 资料来源：[dotnet/src/Microsoft.Agents.AI/Skills/Programmatic/AgentInlineSkill.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Skills/Programmatic/AgentInlineSkill.cs) ### 技能内容构建器 `AgentInlineSkillContentBuilder` 内部类负责将代码定义的技能转换为 XML 格式的内容字符串： ```csharp public static string Build( string name, string description, string instructions, IReadOnlyList? resources, IReadOnlyList? scripts) { var sb = new StringBuilder(); sb.Append($"{EscapeXmlString(name)}\n") .Append($"{EscapeXmlString(description)}\n\n") .Append("\n") .Append(EscapeXmlString(instructions)) .Append("\n"); // ... } ``` 生成的 XML 结构示例： ```xml code-defined-skill A code-defined skill example Your skill instructions here... ``` 资料来源：[dotnet/src/Microsoft.Agents.AI/Skills/Programmatic/AgentInlineSkillContentBuilder.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Skills/Programmatic/AgentInlineSkillContentBuilder.cs) ### AgentSkillsProvider 技能提供者 `AgentSkillsProvider` 是 AI 上下文提供者，负责将技能信息注入到 Agent 的执行上下文中： ```mermaid graph LR subgraph "AgentSkillsProvider 内部机制" A[技能源] -->|读取| B[AgentSkillsSource] C[提示模板] -->|格式化| D[SkillsPlaceholder] B -->|注入| D D --> E[AIContext] end ``` #### 默认技能指令模板 ```csharp private const string DefaultSkillsInstructionPrompt = """ You have access to skills containing domain-specific knowledge and capabilities. Each skill provides specialized instructions, reference documents, and assets for specific tasks. {skills} When a task aligns with a skill's domain, follow these steps in exact order: - Use `load_skill` to retrieve the skill's instructions. - Follow the provided guidance. {resource_instructions} {script_instructions} Only load what is needed, when it is needed. """; ``` #### 模板占位符说明 | 占位符 | 说明 | |--------|------| | `{skills}` | 可用技能列表 | | `{resource_instructions}` | 资源相关指令 | | `{script_instructions}` | 脚本执行指令 | 资料来源：[dotnet/src/Microsoft.Agents.AI/Skills/AgentSkillsProvider.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Skills/AgentSkillsProvider.cs) ### 技能与 Agent 的集成流程 ```mermaid flowchart TD A[定义技能] --> B{技能类型选择} B -->|文件型| C[创建 SKILL.md] B -->|代码型| D[实例化 AgentInlineSkill] C --> E[注册到 AgentSkillsProvider] D --> E E --> F[Agent 执行时加载技能] F --> G{技能是否匹配任务} G -->|是| H[加载技能指令] G -->|否| I[跳过技能] H --> J[执行技能任务] I --> K[继续其他任务] J --> L[返回执行结果] K --> L ``` ## 工具与技能协同 ### 工具调用链 当技能包含脚本时，系统会通过 `run_skill_script` 工具执行脚本： ```mermaid sequenceDiagram participant Agent as Agent participant LLM as Language Model participant Provider as AgentSkillsProvider participant Script as 技能脚本 Agent->>LLM: 请求执行任务 LLM->>Agent: 识别需要使用技能 Agent->>Provider: 加载技能 Provider-->>Agent: 返回技能内容 Agent->>LLM: 传递技能指令 LLM->>Agent: 决定调用工具 Agent->>Script: 执行 run_skill_script Script-->>Agent: 返回执行结果 ``` 资料来源：[dotnet/src/Microsoft.Agents.AI/Skills/AgentSkill.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Skills/AgentSkill.cs) ### 能力说明 | 能力 | 工具支持 | 技能支持 | 说明 | |------|----------|----------|------| | 函数调用 | ✅ | ❌ | 工具通过函数定义实现调用 | | 知识注入 | ❌ | ✅ | 技能通过指令和资源注入知识 | | 持久化存储 | ✅ | ❌ | FileMemory 工具提供文件操作 | | 脚本执行 | ❌ | ✅ | 技能脚本通过专用工具执行 | | 动态发现 | ✅ | ✅ | 两者都支持描述性元数据 | ## 使用示例 ### .NET 代码定义技能 ```csharp var mySkill = new AgentInlineSkill( name: "code-defined-skill", description: "A skill defined in code", instructions: "Follow these steps to complete the task...", license: "MIT", compatibility: "Agent Framework v1.0+", allowedTools: "FileMemory_ReadFile FileMemory_SaveFile", metadata: new AdditionalPropertiesDictionary { { "author", "developer@example.com" }, { "version", "1.0.0" } } ); ``` ### Python 工具装饰器 ```python from agent_framework import tool @tool def add_numbers(a: int, b: int) -> int: """Add two numbers together.""" return a + b ``` ## 最佳实践 ### 技能设计原则 1. **单一职责**：每个技能应专注于特定领域 2. **清晰描述**：使用准确的描述帮助 LLM 选择合适的技能 3. **版本管理**：通过元数据跟踪技能版本 4. **权限控制**：使用 `allowedTools` 限制技能可访问的工具 ### 工具设计原则 1. **原子性**：每个工具应执行单一操作 2. **幂等性**：工具应能安全地重复执行 3. **错误处理**：提供清晰的错误消息 4. **参数验证**：使用 JSON Schema 严格定义参数 ## 相关资源 - [Agent Skills Specification](https://agentskills.io/) - [Microsoft Agent Framework 文档](https://github.com/microsoft/agent-framework) - [入门示例](../samples/01-get-started/) --- ## 工作流系统概述 ### 相关页面 相关主题：[工作流编排模式](#workflow-patterns), [检查点与恢复机制](#checkpoint-recovery)
相关源码文件 以下源码文件用于生成本页说明： - [python/packages/core/agent_framework/_workflows/_workflow.py](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/agent_framework/_workflows/_workflow.py) - [python/packages/core/agent_framework/_workflows/_workflow_builder.py](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/agent_framework/_workflows/_workflow_builder.py) - [dotnet/src/Microsoft.Agents.AI.Workflows/WorkflowBuilder.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI.Workflows/WorkflowBuilder.cs) - [dotnet/src/Microsoft.Agents.AI.Workflows/Executor.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI.Workflows/Executor.cs) - [python/samples/03-workflows/README.md](https://github.com/microsoft/agent-framework/blob/main/python/samples/03-workflows/README.md) - [dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/DeclarativeWorkflowBuilder.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/DeclarativeWorkflowBuilder.cs) - [python/samples/03-workflows/declarative/README.md](https://github.com/microsoft/agent-framework/blob/main/python/samples/03-workflows/declarative/README.md)
# 工作流系统概述 ## 1. 系统简介 Microsoft Agent Framework 的工作流系统（Workflow System）是一个用于编排多代理（Multi-Agent）协作的核心模块。该系统提供了两种互补的工作流定义方式：**命令式工作流（Imperative Workflow）** 和 **声明式工作流（Declarative Workflow）**。通过工作流系统，开发者可以将多个代理（Agent）、执行器（Executor）、工具（Tool）以及控制流逻辑组合成复杂的自动化流程。 命令式工作流允许开发者使用 Python 或 C# 等编程语言直接编写工作流逻辑，而声明式工作流则支持通过 YAML 配置文件定义工作流，实现业务逻辑与代码的解耦。资料来源：[python/samples/03-workflows/README.md]()、[python/samples/03-workflows/declarative/README.md]() ## 2. 核心概念 ### 2.1 执行器（Executor） 执行器是工作流系统的基本构建单元，负责执行具体的任务或调用代理。每个执行器接收输入、执行逻辑并产生输出，输出可以传递给后续的执行器形成链条。 在 .NET 实现中，`Executor` 类是执行器的基类，提供了异步执行能力。资料来源：[dotnet/src/Microsoft.Agents.AI.Workflows/Executor.cs]() ### 2.2 工作流（Workflow） 工作流是执行器的容器，定义了执行器的组织结构和执行顺序。工作流可以包含： - **起始执行器（Start Executor）**：工作流的入口点 - **执行器图（Executor Graph）**：执行器之间的连接关系 - **状态管理（State Management）**：工作流执行过程中的状态存储 ```mermaid graph LR A[用户输入] --> B[起始执行器] B --> C[执行器 1] C --> D[执行器 2] D --> E[执行器 N] E --> F[工作流输出] ``` 资料来源：[python/packages/core/agent_framework/_workflows/_workflow.py]() ### 2.3 状态（State） 工作流状态用于在工作流执行过程中存储和传递数据。状态可以包含： | 状态字段 | 描述 | |---------|------| | `turn.*` | 当前轮次相关的变量，如 `turn.greeting` | | `user.*` | 用户相关数据 | | `agent.*` | 代理生成的数据 | | `_executor_state` | 执行器内部状态（系统保留） | 资料来源：[python/samples/03-workflows/declarative/README.md]() ## 3. 工作流类型 ### 3.1 命令式工作流（Imperative Workflow） 命令式工作流使用代码直接定义，允许开发者使用完整的编程语言能力。 #### 3.1.1 函数式工作流（Functional Workflow） 函数式工作流将工作流编写为普通的异步函数，使用原生的 `if/else`、循环和 `asyncio.gather` 等控制流语法。 ```python async def my_workflow(input_data: dict) -> dict: # 原生 Python 异步控制流 if input_data.get("type") == "A": result = await agent_a.invoke(input_data) else: results = await asyncio.gather( agent_b.invoke(input_data), agent_c.invoke(input_data) ) result = combine_results(results) return result ``` 资料来源：[python/samples/03-workflows/README.md]() #### 3.1.2 图工作流（Graph Workflow） 图工作流通过连接执行器和边（Edge）来构建有向无环图（DAG）结构。 ```mermaid graph TD Start[起始执行器] --> AgentA[代理 A] AgentA -->|条件分支| Condition{条件判断} Condition -->|true| AgentB[代理 B] Condition -->|false| AgentC[代理 C] AgentB --> End[结束] AgentC --> End ``` 资料来源：[python/samples/03-workflows/README.md]() ### 3.2 声明式工作流（Declarative Workflow） 声明式工作流通过 YAML 文件定义，适合业务逻辑稳定、频繁变更的场景。 #### 3.2.1 基本结构 ```yaml name: my-workflow description: 工作流描述 actions: - kind: SetValue path: turn.greeting value: "你好" - kind: SendActivity activity: text: "=turn.greeting" ``` 资料来源：[python/samples/03-workflows/declarative/README.md]() #### 3.2.2 支持的动作类型 | 动作类型 | 功能描述 | |---------|---------| | `SetValue` | 设置变量值 | | `SetVariable` | 设置变量（.NET 风格命名） | | `AppendValue` | 向列表追加值 | | `If` | 条件分支 | | `Switch` | 多路分支 | | `Foreach` | 遍历集合 | | `RepeatUntil` | 循环直到条件满足 | | `SendActivity` | 向用户发送消息 | | `GotoAction` | 跳转到指定标签动作 | 资料来源：[python/samples/03-workflows/declarative/README.md]() ## 4. 系统架构 ### 4.1 架构组件 ```mermaid graph TD subgraph "Python SDK" PYWF[Python 工作流] PYFB[函数式构建器] PYGB[图构建器] PYDB[声明式构建器] end subgraph ".NET SDK" DNFWF[.NET 工作流] DNFB[WorkflowBuilder] DNDTB[DeclarativeWorkflowBuilder] end subgraph "共享组件" EX[Executor 执行器] ST[State 状态管理] CK[Checkpoint 检查点] end PYWF --> EX PYFB --> EX PYGB --> EX DNFWF --> EX DNFB --> EX DNDTB --> EX EX --> ST ST --> CK ``` ### 4.2 工作流构建器 #### 4.2.1 Python WorkflowBuilder Python 版本的 `WorkflowBuilder` 提供链式 API 构建工作流： ```python workflow = WorkflowBuilder( start_executor=my_start_executor ).add_edge( from_executor=my_start_executor, to_executor=my_next_executor ).build() ``` 资料来源：[python/packages/core/agent_framework/_workflows/_workflow_builder.py]() #### 4.2.2 .NET WorkflowBuilder .NET 版本的 `WorkflowBuilder` 支持依赖注入和配置驱动： ```csharp services.AddAgentsWorkflows(options => { options.WorkflowBuilder = workflowBuilder; }); ``` 资料来源：[dotnet/src/Microsoft.Agents.AI.Workflows/WorkflowBuilder.cs]() #### 4.2.3 DeclarativeWorkflowBuilder 声明式构建器从 YAML 加载工作流定义： ```csharp var workflow = DeclarativeWorkflowBuilder.Build("workflow.yaml", options); ``` ```python # Python 版本 from agent_framework_declarative import load_workflow workflow = load_workflow("workflow.yaml") ``` 资料来源：[dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/DeclarativeWorkflowBuilder.cs]() ## 5. 执行模型 ### 5.1 同步与异步执行 工作流支持同步和异步两种执行模式： ```python # 非流式执行 result = await workflow.execute(input_data) # 流式执行 async for event in workflow.stream(input_data): print(event) ``` 资料来源：[python/packages/core/agent_framework/_workflows/_workflow.py]() ### 5.2 代理调用链 在多代理工作流中，代理可以按顺序调用，形成处理链： ```mermaid graph LR A[用户输入] --> B[翻译代理
French Agent] B --> C[翻译代理
Spanish Agent] C --> D[翻译代理
English Agent] D --> E[最终输出] ``` 每个代理接收前一个代理的输出作为输入，实现管道式处理。资料来源：[dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Workflow-Simple/README.md]() ### 5.3 人机交互（HITL） 声明式工作流支持人类在环（Human-in-the-Loop）模式，允许工作流暂停等待人工输入： ```yaml actions: - kind: If condition: "turn.needsApproval == true" then: - kind: WaitForHumanInput timeout: 300 ``` 资料来源：[python/samples/04-hosting/durabletask/07_single_agent_orchestration_hitl/README.md]() ## 6. 状态持久化与检查点 ### 6.1 检查点机制 工作流系统支持检查点（Checkpoint）功能，用于保存和恢复工作流执行状态： ```mermaid graph LR A[执行中] -->|保存| B[检查点] B -->|恢复| C[继续执行] B -->|重启| D[从起始执行] ``` DevUI 可以显示工作流的检查点信息，包括完整的状态快照。资料来源：[python/packages/devui/frontend/src/components/features/workflow/checkpoint-info-modal.tsx]() ### 6.2 状态查看 工作流状态可以通过 DevUI 的工作流视图组件查看： | 组件 | 功能 | |-----|------| | 状态徽章 | 显示当前状态变量 | | 原始 JSON | 展开查看完整状态 | | 检查点列表 | 历史状态快照 | 资料来源：[python/packages/devui/frontend/src/components/features/workflow/workflow-view.tsx]() ## 7. 工具与技能集成 ### 7.1 函数工具 工作流中的代理可以调用函数工具（Function Tool）： ```python @tool def get_weather(location: str) -> str: """获取指定位置的天气信息""" return f"{location} 今天天气晴朗" ``` 资料来源：[python/samples/01-get-started/README.md]() ### 7.2 技能（Skills） 技能是一种结构化的工具定义方式，支持代码定义和文件定义两种形式： | 类型 | 描述 | |-----|------| | 代码定义技能 | 直接在代码中定义 | | 文件定义技能 | 通过 `SKILL.md` 文件定义 | 技能可以包含脚本、参考资料和执行命令。资料来源：[python/samples/02-agents/skills/mixed_skills/README.md]() ## 8. 开发工具 ### 8.1 DevUI DevUI 提供了工作流的图形化开发界面： | 功能 | 说明 | |-----|-----| | 可视化编辑器 | 编辑和测试工作流 | | 实时执行 | 流式显示执行结果 | | 检查点查看 | 查看历史状态快照 | | 示例库 | 预置工作流示例 | 资料来源：[python/packages/devui/README.md]() ### 8.2 代码导出（Eject） 声明式工作流支持导出为代码，便于进一步定制： ```csharp var code = DeclarativeWorkflowBuilder.Eject( "workflow.yaml", DeclarativeWorkflowLanguage.CSharp, "MyNamespace" ); ``` 支持的目标语言： | 语言 | 枚举值 | |-----|-------| | Python | `DeclarativeWorkflowLanguage.Python` | | C# | `DeclarativeWorkflowLanguage.CSharp` | | JavaScript | `DeclarativeWorkflowLanguage.JavaScript` | 资料来源：[dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/DeclarativeWorkflowBuilder.cs]() ## 9. 快速开始 ### 9.1 Python 入门示例 ```bash pip install agent-framework ``` | 示例 | 文件 | 学习内容 | |-----|------|---------| | 1 | `01_hello_agent.py` | 创建第一个代理 | | 2 | `02_add_tools.py` | 添加函数工具 | | 3 | `03_multi_turn.py` | 多轮对话 | | 4 | `04_memory.py` | 自定义上下文 | | 5 | `05_functional_workflow_with_agents.py` | 函数式工作流 | | 6 | `06_functional_workflow_basics.py` | 工作流基础 | | 7 | `07_first_graph_workflow.py` | 图工作流 | | 8 | `08_host_your_agent.py` | 部署代理 | 资料来源：[python/samples/01-get-started/README.md]() ### 9.2 .NET 入门示例 ```bash cd dotnet/samples dotnet run --project 01-hello-agent ``` ## 10. 最佳实践 1. **选择合适的工作流类型**：业务逻辑稳定时使用声明式工作流，需要复杂逻辑时使用命令式工作流 2. **合理设计状态结构**：使用清晰的前缀命名（如 `turn.`、`user.`）区分不同来源的数据 3. **使用检查点恢复**：对于长时间运行的工作流，定期保存检查点便于故障恢复 4. **流式输出优化**：对延迟敏感的应用使用流式执行模式 5. **工具封装**：将常用功能封装为工具，便于在多个工作流中复用 ## 11. 相关资源 | 资源类型 | 链接 | |---------|------| | Python 包 | `pip install agent-framework` | | 声明式包 | `pip install agent-framework-declarative` | | 可视化支持 | `pip install agent-framework[viz]` | | 官方文档 | [Agent Framework 文档](https://github.com/microsoft/agent-framework) | --- ## 工作流编排模式 ### 相关页面 相关主题：[工作流系统概述](#workflow-overview), [检查点与恢复机制](#checkpoint-recovery)
相关源码文件 以下源码文件用于生成本页说明： - [python/packages/orchestrations/agent_framework_orchestrations/_sequential.py](https://github.com/microsoft/agent-framework/blob/main/python/packages/orchestrations/agent_framework_orchestrations/_sequential.py) - [python/packages/orchestrations/agent_framework_orchestrations/_concurrent.py](https://github.com/microsoft/agent-framework/blob/main/python/packages/orchestrations/agent_framework_orchestrations/_concurrent.py) - [python/packages/orchestrations/agent_framework_orchestrations/_handoff.py](https://github.com/microsoft/agent-framework/blob/main/python/packages/orchestrations/agent_framework_orchestrations/_handoff.py) - [dotnet/src/Microsoft.Agents.AI.Workflows/GroupChatManager.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI.Workflows/GroupChatManager.cs) - [dotnet/src/Microsoft.Agents.AI.Workflows/HandoffWorkflowBuilder.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI.Workflows/HandoffWorkflowBuilder.cs)
# 工作流编排模式 ## 概述 工作流编排（Workflow Orchestration）是Microsoft Agent Framework中的核心能力，它允许开发者将多个代理（Agent）、工具（Tool）和功能组件组合成复杂的自动化流程。Agent Framework提供了多种编排模式，包括顺序执行、并发执行和交接（Handoff）机制，使开发者能够构建从简单到复杂的各种自动化工作流。 工作流编排系统的主要特点包括： - **声明式定义**：通过Python装饰器或C#构建器模式声明工作流结构 - **状态管理**：内置的状态传递和上下文共享机制 - **异步支持**：完整的异步执行模型，支持流式和非流式响应 - **错误处理**：统一的异常捕获和恢复机制 - **可扩展性**：支持自定义执行器和节点类型 ## 核心组件 ### 执行器（Executor） 执行器是工作流编排的基本构建单元，负责执行具体的任务或调用代理。每个执行器可以包含输入参数、执行逻辑和输出处理。 ```mermaid graph LR A[输入数据] --> B[执行器 Executor] B --> C{执行类型} C -->|同步| D[同步执行] C -->|异步| E[异步执行] C -->|流式| F[流式执行] D --> G[输出结果] E --> G F --> G ``` ### 顺序工作流（Sequential Workflow） 顺序工作流按照定义的顺序依次执行各个执行器，前一个执行器的输出作为下一个执行器的输入。这种模式适用于步骤之间存在依赖关系的场景。 **Python实现**： ```python from agent_framework_orchestrations import SequentialWorkflow, Step workflow = SequentialWorkflow( steps=[ Step(executor=data_loader, name="load_data"), Step(executor=processor, name="process_data"), Step(executor=formatter, name="format_output") ] ) ``` **C#实现**： ```csharp var workflow = new SequentialWorkflowBuilder() .AddStep(dataLoader) .AddStep(processor) .AddStep(formatter) .Build(); ``` ### 并发工作流（Concurrent Workflow） 并发工作流允许同时执行多个执行器，通过并行处理提高整体效率。适用于彼此独立、可同时运行的任务。 ```mermaid graph TD A[开始] --> B[并发执行] B --> C[执行器 A] B --> D[执行器 B] B --> E[执行器 N] C --> F[收集结果] D --> F E --> F F --> G[聚合输出] G --> H[结束] ``` **关键参数**： | 参数 | 类型 | 说明 | |------|------|------| | `max_concurrency` | int | 最大并发数，限制同时运行的任务数量 | | `timeout` | timedelta | 单个任务的最大执行时间 | | `fail_fast` | bool | 任何任务失败时是否立即停止 | ### 交接工作流（Handoff Workflow） 交接工作流实现了代理之间的上下文传递，允许一个代理将控制权和会话状态移交给另一个代理。这是构建多代理协作系统的核心机制。 ```mermaid graph LR A[Agent A] -->|Handoff| B[上下文传递] B --> C[Agent B] B --> D[消息队列] D --> C C --> E[继续执行] ``` ## 交接机制（Handoff） ### 工作原理 交接机制是Agent Framework中最核心的编排模式之一，它允许： 1. **上下文转移**：当前代理的状态、记忆和对话历史完整传递给下一个代理 2. **控制权移交**：执行流程从源代理平滑转移到目标代理 3. **消息传递**：支持通过消息队列进行异步交接 ### HandoffWorkflowBuilder（C#） `HandoffWorkflowBuilder`提供了声明式的交接工作流构建方式： ```csharp var handoffWorkflow = new HandoffWorkflowBuilder("transfer_to_specialist") .WithSourceAgent("general_agent") .WithTargetAgent("specialist_agent") .WithContextMapping(mappings => { mappings.Map("user_preferences", "preferences"); mappings.Map("conversation_history", "history"); }) .WithHandoffMessage("正在将您的请求转交给专家代理...") .Build(); ``` **配置选项**： | 选项 | 说明 | |------|------| | `WithSourceAgent` | 指定源代理标识符 | | `WithTargetAgent` | 指定目标代理标识符 | | `WithContextMapping` | 配置上下文字段映射规则 | | `WithHandoffMessage` | 设置交接时的提示消息 | | `WithRetryPolicy` | 配置交接失败重试策略 | ## 群组聊天管理器（GroupChatManager） `GroupChatManager`是.NET实现中的群组聊天协调器，负责管理多个代理之间的对话交互和消息路由。 ### 核心职责 ```mermaid graph TD A[用户消息] --> B[GroupChatManager] B --> C{路由决策} C -->|选择代理| D[代理 A] C -->|选择代理| E[代理 B] C -->|选择代理| F[代理 N] D --> G[响应] E --> G F --> G G --> H[消息汇总] H --> I[返回用户] ``` ### 管理功能 | 功能 | 说明 | |------|------| | 代理注册 | 允许动态注册和注销参与对话的代理 | | 消息路由 | 根据规则或AI判断将消息路由到合适的代理 | | 状态同步 | 维护所有参与代理的当前状态 | | 发言控制 | 管理多代理场景下的发言顺序和权限 | ## 最佳实践 ### 1. 工作流设计原则 - **单一职责**：每个执行器应专注于单一任务 - **松耦合**：执行器之间通过明确定义的接口通信 - **错误边界**：为关键步骤添加错误处理和回退逻辑 ### 2. 性能优化 - **识别并行机会**：分析工作流中的独立步骤，尽量并行化 - **设置合理超时**：防止单个任务长时间阻塞整个工作流 - **资源限制**：使用`max_concurrency`控制并发资源使用 ### 3. 调试技巧 - **启用详细日志**：使用日志记录每个步骤的输入输出 - **状态检查点**：在关键节点保存工作流状态便于恢复 - **逐步执行**：开发阶段使用单步模式验证逻辑 ## 相关示例 | 示例文件 | 模式 | 说明 | |----------|------|------| | `05_functional_workflow_with_agents.py` | 功能工作流 | 在函数式工作流中调用代理 | | `06_functional_workflow_basics.py` | 基础功能工作流 | 纯函数组合的工作流 | | `07_first_graph_workflow.py` | 图工作流 | 使用边连接执行器构建图 | | `08_host_your_agent.py` | 托管代理 | 将代理部署到生产环境 | ## 总结 工作流编排模式是构建复杂AI应用的基础，Agent Framework提供了从简单顺序处理到复杂多代理协作的完整解决方案。开发者可以根据业务需求选择合适的编排模式，并通过框架提供的丰富API实现高效、可靠的工作流系统。 --- ## 检查点与恢复机制 ### 相关页面 相关主题：[工作流系统概述](#workflow-overview), [工作流编排模式](#workflow-patterns)
相关源码文件 以下源码文件用于生成本页说明： - [python/packages/core/agent_framework/_workflows/_checkpoint.py](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/agent_framework/_workflows/_checkpoint.py) - [python/samples/03-workflows/checkpoint/checkpoint_with_resume.py](https://github.com/microsoft/agent-framework/blob/main/python/samples/03-workflows/checkpoint/checkpoint_with_resume.py) - [dotnet/src/Microsoft.Agents.AI.Workflows/Checkpointing/CheckpointManagerImpl.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI.Workflows/Checkpointing/CheckpointManagerImpl.cs) - [dotnet/samples/03-workflows/Checkpoint/CheckpointAndRehydrate/Program.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/samples/03-workflows/Checkpoint/CheckpointAndRehydrate/Program.cs)
# 检查点与恢复机制 ## 概述 检查点（Checkpoint）与恢复（Resume）机制是 Agent Framework 工作流系统的核心功能之一，它允许长时间运行的工作流在中断后从上一个保存点继续执行，而无需重新开始整个流程。 ### 核心能力 | 能力 | 描述 | |------|------| | 状态持久化 | 保存工作流的完整执行状态到外部存储 | | 断点恢复 | 从任意检查点恢复工作流执行 | | 会话管理 | 通过会话ID关联多个检查点 | | HIL 支持 | 支持人类在环（Human-in-the-Loop）场景下的暂停与恢复 | 资料来源：[dotnet/src/Microsoft.Agents.AI.Workflows/Checkpointing/ICheckpointManager.cs:1-15]() --- ## 架构设计 ### 系统组件图 ```mermaid graph TD subgraph "客户端层" A[Workflow 执行环境] --> B[Checkpoint Manager] end subgraph "核心接口" C[ICheckpointManager] D[IWorkflowExecutionEnvironment] end subgraph "存储层" E[(检查点存储)] F[(会话状态)] end B --> C B --> E A --> D D -->|ResumeAsync| B C -->|CommitCheckpointAsync| E C -->|LookupCheckpointAsync| F G[工作流执行器] -->|创建检查点| B B -->|返回 CheckpointInfo| G ``` ### 检查点生命周期 ```mermaid stateDiagram-v2 [*] --> 执行中: 开始工作流 执行中 --> 暂停: 遇到 HIL / 中断 暂停 --> 保存检查点: CommitCheckpointAsync 保存检查点 --> 已保存: 返回 CheckpointInfo 已保存 --> 恢复执行: ResumeAsync 恢复执行 --> 执行中: 加载检查点状态 执行中 --> 完成: 正常结束 暂停 --> 取消: 用户取消 已保存 --> [*]: 清理 ``` 资料来源：[python/packages/core/agent_framework/_workflows/_checkpoint.py:1-50]() --- ## 核心数据模型 ### CheckpointInfo 检查点信息模型，用于唯一标识和检索检查点。 | 属性 | 类型 | 说明 | |------|------|------| | `SessionId` | `string` | 会话唯一标识符 | | `CheckpointId` | `string` | 检查点唯一标识符（自动生成） | 资料来源：[dotnet/src/Microsoft.Agents.AI.Workflows/CheckpointInfo.cs:10-20]() ```csharp public sealed class CheckpointInfo : IEquatable { public string SessionId { get; } public string CheckpointId { get; } internal CheckpointInfo(string sessionId) : this(sessionId, Guid.NewGuid().ToString("N")) { } public CheckpointInfo(string sessionId, string checkpointId) { this.SessionId = Throw.IfNullOrEmpty(sessionId); this.CheckpointId = Throw.IfNullOrEmpty(checkpointId); } } ``` ### Checkpoint 接口模型 ```mermaid classDiagram class Checkpoint { +string SessionId +string CheckpointId +Dictionary state +WorkflowTaskMetadata metadata +string serialized_state } class CheckpointInfo { +string SessionId +string CheckpointId } Checkpoint --> CheckpointInfo : 通过 CommitCheckpointAsync 返回 ``` 资料来源：[python/packages/core/agent_framework/_workflows/_checkpoint.py:15-35]() --- ## 接口定义 ### ICheckpointManager 检查点管理器接口，定义检查点的提交和检索操作。 资料来源：[dotnet/src/Microsoft.Agents.AI.Workflows/Checkpointing/ICheckpointManager.cs:10-40]() | 方法 | 返回类型 | 说明 | |------|----------|------| | `CommitCheckpointAsync` | `ValueTask` | 提交检查点并返回检索信息 | | `LookupCheckpointAsync` | `ValueTask` | 根据检查点信息检索完整状态 | #### CommitCheckpointAsync ```csharp /// /// 提交指定的检查点并返回可用于后续检索的信息 /// /// 当前会话或执行上下文的标识符 /// 要提交的检查点 /// 表示传入检查点的 CheckpointInfo ValueTask CommitCheckpointAsync(string sessionId, Checkpoint checkpoint); ``` #### LookupCheckpointAsync ```csharp /// /// 检索与指定检查点信息关联的检查点 /// /// 当前会话的标识符 /// 用于标识检查点的信息 /// 包含关联 Checkpoint 的 ValueTask /// 如果未找到检查点 ValueTask LookupCheckpointAsync(string sessionId, CheckpointInfo checkpointInfo); ``` ### IWorkflowExecutionEnvironment 工作流执行环境接口，提供从检查点恢复执行的能力。 资料来源：[dotnet/src/Microsoft.Agents.AI.Workflows/IWorkflowExecutionEnvironment.cs:1-20]() ```csharp /// /// 从检查点恢复工作流执行 /// /// 要执行的工作流 /// 要恢复的检查点对应的 CheckpointInfo /// 取消令牌 /// 包含 Run 实例的 ValueTask ValueTask ResumeAsync( Workflow workflow, CheckpointInfo fromCheckpoint, CancellationToken cancellationToken = default); ``` --- ## Python 实现 ### 检查点类结构 资料来源：[python/packages/core/agent_framework/_workflows/_checkpoint.py:1-80]() ```python class Checkpoint: """工作流执行检查点""" def __init__( self, state: dict[str, Any], checkpoint_id: str, session_id: str, metadata: Optional[WorkflowTaskMetadata] = None, ): self.checkpoint_id = checkpoint_id self.session_id = session_id self.state = state self.metadata = metadata class CheckpointInfo: """检查点元信息，用于恢复""" def __init__( self, checkpoint_id: str, session_id: str, created_at: datetime, ): self.checkpoint_id = checkpoint_id self.session_id = session_id self.created_at = created_at ``` ### 异步检查点管理器 ```python class AsyncCheckpointManager(ABC): """异步检查点管理器基类""" @abstractmethod async def commit(self, session_id: str, checkpoint: Checkpoint) -> CheckpointInfo: """提交检查点""" pass @abstractmethod async def lookup(self, session_id: str, checkpoint_info: CheckpointInfo) -> Checkpoint: """检索检查点""" pass @abstractmethod async def list_checkpoints(self, session_id: str) -> list[CheckpointInfo]: """列出所有检查点""" pass ``` 资料来源：[python/packages/core/agent_framework/_workflows/_checkpoint.py:80-100]() --- ## 使用示例 ### Python 示例：检查点与恢复 资料来源：[python/samples/03-workflows/checkpoint/checkpoint_with_resume.py:1-120]() ```python import asyncio from agent_framework import Agent, WorkflowBuilder from agent_framework.workflows import ( CheckpointManager, Checkpoint, CheckpointInfo, ) # 创建带检查点支持的工作流 workflow = WorkflowBuilder(start_executor=my_executor)\ .with_checkpointing()\ .build() async def run_with_checkpoint(): # 运行工作流并获取检查点 run = await workflow.run(input_data) # 在 HIL 暂停点保存检查点 checkpoint_info = await run.save_checkpoint() print(f"检查点已保存: {checkpoint_info.checkpoint_id}") # 模拟中断后恢复 resumed_run = await workflow.resume( from_checkpoint=checkpoint_info ) return resumed_run asyncio.run(run_with_checkpoint()) ``` ### .NET 示例：检查点与重新水化 资料来源：[dotnet/samples/03-workflows/Checkpoint/CheckpointAndRehydrate/Program.cs:1-80]() ```csharp using Microsoft.Agents.AI.Workflows; using Microsoft.Agents.AI.Workflows.Checkpointing; // 创建检查点管理器 ICheckpointManager checkpointManager = new CheckpointManagerImpl(storageProvider); // 执行工作流并获取检查点 Workflow workflow = BuildWorkflow(); var run = await workflow.RunAsync(inputData); // 在适当位置提交检查点 var checkpointInfo = await checkpointManager.CommitCheckpointAsync( sessionId: run.SessionId, checkpoint: new Checkpoint { SessionId = run.SessionId, State = run.GetState(), Metadata = run.GetMetadata() }); Console.WriteLine($"检查点已保存: {checkpointInfo.CheckpointId}"); // 模拟应用重启后恢复 var checkpointToResume = new CheckpointInfo( sessionId: "previous-session-id", checkpointId: checkpointInfo.CheckpointId ); var resumedRun = await workflow.ResumeAsync(checkpointToResume); ``` --- ## 检查点管理器实现 ### CheckpointManagerImpl 资料来源：[dotnet/src/Microsoft.Agents.AI.Workflows/Checkpointing/CheckpointManagerImpl.cs:1-100]() ```csharp internal sealed class CheckpointManagerImpl : ICheckpointManager { private readonly IWorkflowStorage _storage; private readonly IWorkflowStateSerializer _serializer; public async ValueTask CommitCheckpointAsync( string sessionId, Checkpoint checkpoint) { // 生成新的检查点ID var checkpointInfo = new CheckpointInfo(sessionId); // 序列化检查点数据 var serialized = _serializer.Serialize(checkpoint); // 存储到持久化层 await _storage.StoreAsync( key: GetStorageKey(sessionId, checkpointInfo.CheckpointId), data: serialized); // 更新会话索引 await UpdateSessionIndexAsync(sessionId, checkpointInfo); return checkpointInfo; } public async ValueTask LookupCheckpointAsync( string sessionId, CheckpointInfo checkpointInfo) { var key = GetStorageKey(sessionId, checkpointInfo.CheckpointId); var data = await _storage.RetrieveAsync(key); if (data == null) { throw new KeyNotFoundException( $"Checkpoint not found: {checkpointInfo.CheckpointId}"); } return _serializer.Deserialize(data); } } ``` --- ## DevUI 集成 ### 检查点信息模态框 Agent Framework 的 DevUI 组件提供了检查点可视化功能。 资料来源：[python/packages/devui/frontend/src/components/features/workflow/checkpoint-info-modal.tsx:1-80]() ```tsx interface CheckpointInfoModalProps { session: WorkflowSession | null; checkpoints: CheckpointInfo[]; open: boolean; onOpenChange: (open: boolean) => void; } ``` ### 检查点列表展示 DevUI 中的检查点信息模态框包含以下功能： | 功能 | 说明 | |------|------| | 时间线视图 | 按创建顺序展示所有检查点 | | 状态预览 | 显示每个检查点的工作流状态摘要 | | HIL 标识 | 高亮显示待处理 HIL 请求的检查点 | | 原始 JSON | 可展开的检查点完整数据视图 | ```tsx // 检查点渲染逻辑 checkpoints.map((checkpoint, index) => { const isSelected = checkpoint.checkpoint_id === selectedCheckpointId; const hasHil = checkpoint.metadata?.has_pending_hil; return (
); }) ``` ### 工作流视图中的检查点集成 资料来源：[python/packages/devui/frontend/src/components/features/workflow/workflow-view.tsx:1-100]() ```tsx interface WorkflowViewProps { // ... 其他属性 checkpoints: CheckpointInfo[]; showCheckpoints?: boolean; } // 检查点状态显示 0 ? "completed" : "ready" } checkpoints={sessionCheckpoints} showCheckpoints={true} /> ``` --- ## 配置选项 ### 检查点存储配置 | 选项 | 类型 | 默认值 | 说明 | |------|------|--------|------| | `storage_type` | `string` | `memory` | 存储类型：memory、file、database | | `storage_path` | `string` | `./checkpoints` | 文件系统存储路径 | | `max_checkpoints` | `int` | `100` | 单个会话最大检查点数量 | | `checkpoint_interval` | `int` | `60` | 自动检查点保存间隔（秒） | ### 序列化配置 | 选项 | 类型 | 说明 | |------|------|------| | `serializer` | `ISerializer` | 检查点序列化器实现 | | `compression` | `bool` | 是否启用压缩 | | `encryption` | `bool` | 是否启用加密 | --- ## 最佳实践 ### 1. 合理设置检查点频率 ```mermaid graph LR A[工作流执行] --> B{检查点频率} B -->|过密| C[存储开销增加] B -->|过疏| D[恢复时数据丢失风险] C --> E[建议：HIL 点 + 关键步骤] D --> E ``` ### 2. HIL 场景下的检查点 ```python async def workflow_with_hil(): workflow = WorkflowBuilder(start_executor=process_executor) # 在 HIL 点自动保存检查点 workflow.on_hil_request(lambda ctx: ctx.save_checkpoint()) run = await workflow.run(user_input) # 等待人类输入 user_response = await wait_for_user_input() # 恢复执行 resumed = await run.resume(user_response) ``` ### 3. 错误恢复策略 ```csharp try { var resumedRun = await workflow.ResumeAsync(checkpointInfo); } catch (KeyNotFoundException) { // 检查点不存在，尝试从头开始 var freshRun = await workflow.RunAsync(inputData); } catch (CorruptedDataException) { // 检查点数据损坏，尝试上一个有效检查点 var previousCheckpoint = await FindValidCheckpoint(sessionId); var recoveredRun = await workflow.ResumeAsync(previousCheckpoint); } ``` --- ## 相关文件索引 | 类别 | 文件路径 | |------|----------| | Python 核心 | `python/packages/core/agent_framework/_workflows/_checkpoint.py` | | Python 示例 | `python/samples/03-workflows/checkpoint/checkpoint_with_resume.py` | | .NET 接口 | `dotnet/src/Microsoft.Agents.AI.Workflows/Checkpointing/ICheckpointManager.cs` | | .NET 实现 | `dotnet/src/Microsoft.Agents.AI.Workflows/Checkpointing/CheckpointManagerImpl.cs` | | .NET 数据模型 | `dotnet/src/Microsoft.Agents.AI.Workflows/CheckpointInfo.cs` | | .NET 执行环境 | `dotnet/src/Microsoft.Agents.AI.Workflows/IWorkflowExecutionEnvironment.cs` | | .NET 示例 | `dotnet/samples/03-workflows/Checkpoint/CheckpointAndRehydrate/Program.cs` | | DevUI 组件 | `python/packages/devui/frontend/src/components/features/workflow/checkpoint-info-modal.tsx` | --- --- ## Doramagic 踩坑日志 项目：microsoft/agent-framework 摘要：发现 23 个潜在踩坑项，其中 7 个为 high/blocking；最高优先级：安装坑 - 来源证据：.NET: [Bug]: TextContent.AdditionalProperties dropped by AsAGUIEventStreamAsync for TEXT_MESSAGE_START/TEXT_MESSAGE_CON…。 ## 1. 安装坑 · 来源证据：.NET: [Bug]: TextContent.AdditionalProperties dropped by AsAGUIEventStreamAsync for TEXT_MESSAGE_START/TEXT_MESSAGE_CON… - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：.NET: [Bug]: TextContent.AdditionalProperties dropped by AsAGUIEventStreamAsync for TEXT_MESSAGE_START/TEXT_MESSAGE_CONTENT events - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_d329260309954749a2b3b2a9e7135d56 | https://github.com/microsoft/agent-framework/issues/4923 | 来源类型 github_issue 暴露的待验证使用条件。 ## 2. 配置坑 · 来源证据：Bug: Agent responses lose structured JSON metadata in multi-agent orchestration (MAF 1.x.x) - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Bug: Agent responses lose structured JSON metadata in multi-agent orchestration (MAF 1.x.x) - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_8f9f05dcb7564f34bdd5902dcea6be27 | https://github.com/microsoft/agent-framework/issues/5785 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。 ## 3. 安全/权限坑 · 来源证据：.NET: OpenAI-compatible extra body field thinking is not forwarded when using Microsoft.Agents.AI.OpenAI - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：.NET: OpenAI-compatible extra body field thinking is not forwarded when using Microsoft.Agents.AI.OpenAI - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_49875a7dd60f480a99718cfa30b12723 | https://github.com/microsoft/agent-framework/issues/5708 | 来源类型 github_issue 暴露的待验证使用条件。 ## 4. 安全/权限坑 · 来源证据：.NET: [Bug]: In v. 1.5.0 Microsoft.Agents.AI.Anthropic (and Google.GenAI) do not work [Regression] - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：.NET: [Bug]: In v. 1.5.0 Microsoft.Agents.AI.Anthropic (and Google.GenAI) do not work [Regression] - 对用户的影响：可能影响升级、迁移或版本选择。 - 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_58594f7966b84d81924da21ad789effd | https://github.com/microsoft/agent-framework/issues/5707 | 来源类型 github_issue 暴露的待验证使用条件。 ## 5. 安全/权限坑 · 来源证据：.NET: [Bug]: Regression - Tool Events not being emitted correctly to the front end - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：.NET: [Bug]: Regression - Tool Events not being emitted correctly to the front end - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_644a3ed07d2d4bfd8188392b4af687c2 | https://github.com/microsoft/agent-framework/issues/5794 | 来源类型 github_issue 暴露的待验证使用条件。 ## 6. 安全/权限坑 · 来源证据：Anthropic function limit fallback can return empty final response - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Anthropic function limit fallback can return empty final response - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_b61b91ca16094a448f8c0eab5e2daaa1 | https://github.com/microsoft/agent-framework/issues/5769 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 7. 安全/权限坑 · 来源证据：Python: Add tutorial for building a custom chat client / LLM provider - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Python: Add tutorial for building a custom chat client / LLM provider - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_959e1eeb912a469c89f68f7f12275690 | https://github.com/microsoft/agent-framework/issues/5505 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 8. 安装坑 · 来源证据：python-1.2.1 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：python-1.2.1 - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_f22ed66ae1f44b28b893aa5cbe439c92 | https://github.com/microsoft/agent-framework/releases/tag/python-1.2.1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 9. 配置坑 · 来源证据：.NET: [Bug]: DurableTask: SuperstepState.AccumulatedEvents overflows CustomStatus 16 KB cap on multi-executor workflows… - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：.NET: [Bug]: DurableTask: SuperstepState.AccumulatedEvents overflows CustomStatus 16 KB cap on multi-executor workflows with typed outputs - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_52da26ae3ace4acb9913ac780bfb6cd0 | https://github.com/microsoft/agent-framework/issues/5745 | 来源类型 github_issue 暴露的待验证使用条件。 ## 10. 配置坑 · 来源证据：Python: CosmosHistoryProvider Code interpreter tool calls are saved chunk by chunk - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Python: CosmosHistoryProvider Code interpreter tool calls are saved chunk by chunk - 对用户的影响：可能影响升级、迁移或版本选择。 - 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_48aaa2f1026c4afd9e1a1da3a1a862a6 | https://github.com/microsoft/agent-framework/issues/5793 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 11. 配置坑 · 来源证据：dotnet-1.5.0 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：dotnet-1.5.0 - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_2b3d3127c36f41798428b164b5444cbb | https://github.com/microsoft/agent-framework/releases/tag/dotnet-1.5.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 12. 配置坑 · 来源证据：python-1.2.2 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：python-1.2.2 - 对用户的影响：可能影响升级、迁移或版本选择。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_fb88b6cd86e04e199a03cfcf8a97dde6 | https://github.com/microsoft/agent-framework/releases/tag/python-1.2.2 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 13. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 建议检查：将假设转成下游验证清单。 - 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。 - 证据：capability.assumptions | github_repo:974445592 | https://github.com/microsoft/agent-framework | README/documentation is current enough for a first validation pass. ## 14. 维护坑 · 来源证据：dotnet-1.4.0 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：dotnet-1.4.0 - 对用户的影响：可能影响升级、迁移或版本选择。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_e25f39a7081848689e086b1f98f92675 | https://github.com/microsoft/agent-framework/releases/tag/dotnet-1.4.0 | 来源类型 github_release 暴露的待验证使用条件。 ## 15. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。 - 防护动作：维护活跃度未知时，推荐强度不能标为高信任。 - 证据：evidence.maintainer_signals | github_repo:974445592 | https://github.com/microsoft/agent-framework | last_activity_observed missing ## 16. 安全/权限坑 · 下游验证发现风险项 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：下游已经要求复核，不能在页面中弱化。 - 建议检查：进入安全/权限治理复核队列。 - 防护动作：下游风险存在时必须保持 review/recommendation 降级。 - 证据：downstream_validation.risk_items | github_repo:974445592 | https://github.com/microsoft/agent-framework | no_demo; severity=medium ## 17. 安全/权限坑 · 存在安全注意事项 - 严重度：medium - 证据强度：source_linked - 发现：No sandbox install has been executed yet; downstream must verify before user use. - 对用户的影响：用户安装前需要知道权限边界和敏感操作。 - 建议检查：转成明确权限清单和安全审查提示。 - 防护动作：安全注意事项必须面向用户前置展示。 - 证据：risks.safety_notes | github_repo:974445592 | https://github.com/microsoft/agent-framework | No sandbox install has been executed yet; downstream must verify before user use. ## 18. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 建议检查：把风险写入边界卡，并确认是否需要人工复核。 - 防护动作：评分风险必须进入边界卡，不能只作为内部分数。 - 证据：risks.scoring_risks | github_repo:974445592 | https://github.com/microsoft/agent-framework | no_demo; severity=medium ## 19. 安全/权限坑 · 来源证据：Python: OpenAI store=True can silently bypass external HistoryProvider persistence - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Python: OpenAI store=True can silently bypass external HistoryProvider persistence - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_36cbde33c0a64127b95d953c65d49c54 | https://github.com/microsoft/agent-framework/issues/5798 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 20. 安全/权限坑 · 来源证据：python-1.2.0 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：python-1.2.0 - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_aa3fc8cfbbad40f98ea1da9e68eeaa3f | https://github.com/microsoft/agent-framework/releases/tag/python-1.2.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 21. 安全/权限坑 · 来源证据：python-1.3.0 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：python-1.3.0 - 对用户的影响：可能影响升级、迁移或版本选择。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_6df4ed99139d4fb0bc182d80b34e9d45 | https://github.com/microsoft/agent-framework/releases/tag/python-1.3.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 22. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 建议检查：抽样最近 issue/PR，判断是否长期无人处理。 - 防护动作：issue/PR 响应未知时，必须提示维护风险。 - 证据：evidence.maintainer_signals | github_repo:974445592 | https://github.com/microsoft/agent-framework | issue_or_pr_quality=unknown ## 23. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 建议检查：确认最近 release/tag 和 README 安装命令是否一致。 - 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。 - 证据：evidence.maintainer_signals | github_repo:974445592 | https://github.com/microsoft/agent-framework | release_recency=unknown