框架概述

Agent Framework 由微软开发维护，是一个现代化的 AI 智能体开发平台。框架的核心设计理念是提供一个统一且灵活的架构，使开发者能够轻松创建具有对话能力、工具调用能力、工作流编排能力的高级 AI 应用。

该框架支持两种主要的开发语言生态：

资料来源：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 服务和托管选项。

资料来源：dotnet/AGENTS.md:1

智能体（Agent）体系

智能体是框架的核心抽象单元，代表一个能够理解自然语言、执行工具调用、维护对话状态的 AI 实例。

ChatClientAgent

ChatClientAgent 是框架中最基础的智能体类型，它通过 IChatClient 接口与底层聊天服务交互。这种设计实现了智能体逻辑与底层 AI 服务的解耦。

// 创建一个基础智能体的核心参数
public class ChatClientAgent
{
    string? Instructions { get; }    // 系统指令
    string? Name { get; }           // 智能体名称
    string? Description { get; }     // 智能体描述
    IList<AITool>? 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 标识模型

每个智能体都有一个唯一的标识符，用于在分布式系统中追踪和管理智能体实例。

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）

工具系统使智能体能够执行外部操作，扩展了纯对话的能力边界。

工具定义结构

框架支持两种工具定义方式：

1. 代码定义工具 - 通过装饰器或接口直接在代码中实现
2. 文件定义工具 - 通过 YAML/JSON 配置文件声明

资料来源：python/samples/01-get-started/README.md:1

工具资源管理

智能体的工具可以关联资源（Resources），这些资源在运行时被注入到工具执行上下文中。

public abstract class AgentSkill
{
    // 技能关联的资源列表
    public virtual IReadOnlyList<AgentSkillResource>? Resources => null;
    
    // 技能关联的脚本列表
    public virtual IReadOnlyList<AgentSkillScript>? Scripts => null;
}

资料来源：dotnet/src/Microsoft.Agents.AI/Skills/AgentSkill.cs:1

技能系统（Skills）

技能系统是框架的高级特性，允许开发者将领域知识、操作流程和资源打包成可复用的模块。

AgentSkillsProvider

AgentSkillsProvider 是技能系统的核心组件，它负责：

• 加载和组织技能定义
• 将技能转换为 AI 可理解的提示词
• 管理技能相关的工具和脚本执行
• 提供上下文感知的技能推荐

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

技能指令模板

框架使用预定义的提示词模板来组织技能信息：

你有权访问包含领域特定知识和能力的技能。
每个技能为特定任务提供专业指导、参考文档和资源。

<available_skills>
{skills}
</available_skills>

当任务与某个技能的领域匹配时，按以下步骤操作：
- 使用 `load_skill` 加载技能指令
- 遵循提供的指导
{resource_instructions}
{script_instructions}
只加载所需内容，按需加载。

资料来源：dotnet/src/Microsoft.Agents.AI/Skills/AgentSkillsProvider.cs:1

技能类型

资料来源：python/packages/declarative/README.md:1

技能配置选项

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）

框架提供了两种工作流编写范式，满足不同复杂度和可维护性需求。

函数式工作流

函数式工作流将工作流定义为普通的异步函数，简洁直观。

# 简单示例：异步函数即工作流
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

图工作流的核心概念：

资料来源：python/samples/01-get-started/README.md:1

会话管理（Session）

AgentSession 管理智能体的对话状态，支持多轮对话和上下文维护。

# 建立会话
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 允许开发者自定义上下文注入逻辑，为智能体提供动态的补充信息。

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 服务的深度集成。

// 已废弃，请使用最新的 Foundry Agents 服务
[Obsolete("Please use the latest Foundry Agents service via the Microsoft.Agents.AI.AzureAI package.")]
public static async Task<ChatClientAgent> CreateAIAgentAsync(
    this PersistentAgentsClient persistentAgentsClient,
    string model,
    string? name = null,
    string? description = null,
    string? instructions = null,
    IEnumerable<ToolDefinition>? tools = null,
    ToolResources? toolResources = null,
    float? temperature = null,
    float? topP = null,
    string? responseFormat = null,
    IDictionary<string, string>? 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 后端：

public static AIAgent AsAIAgent(
    this CopilotClient client,
    bool ownsClient = false,
    string? id = null,
    string? name = null,
    string? description = null,
    IList<AITool>? 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

部署模式

框架支持多种部署场景：

客户端托管

智能体作为客户端应用的一部分运行，轻量级部署。

# 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 环境准备

# 安装核心包
pip install agent-framework

# 设置环境变量
export FOUNDRY_PROJECT_ENDPOINT="https://your-project-endpoint"
export FOUNDRY_MODEL="gpt-4o"   # 可选，默认 gpt-4o

创建第一个智能体

from agent_framework import Agent

# 创建智能体
agent = Agent(
    name="我的助手",
    instructions="你是一个有帮助的助手。",
    model="gpt-4o"
)

# 运行智能体
result = await agent.run("你好，请介绍一下你自己。")
print(result)

添加工具

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

相关资源

• 官方文档
• Agent Skills 规范
• Python SDK 仓库
• .NET SDK 仓库
• 示例代码库

概述

Agent Framework 是微软开发的一个跨平台智能代理框架，支持 Python 和 .NET 两种运行时环境。框架提供了完整的代理（Agent）开发、部署和管理能力，涵盖从基础代理创建到复杂工作流编排的完整功能链。

本页面详细介绍框架的安装方法、配置选项以及开发环境搭建指南。

1. 架构概览

Agent Framework 采用分层架构设计，核心层负责 Agent 的生命周期管理和运行时调度，工作流层提供组合多个 Agent 的能力，外围层则包含工具系统、技能系统、会话管理等功能扩展。

graph TB
    subgraph "外围层"
        Tools["工具系统<br/>@tool 装饰器"]
        Skills["技能系统<br/>AgentSkill"]
        Memory["会话记忆<br/>AgentSession"]
    end
    
    subgraph "核心层"
        Agent["Agent / AIAgent"]
        Runtime["运行时调度器"]
    end
    
    subgraph "工作流层"
        Workflow["工作流<br/>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 中均有对应实现。

Python 实现：agent_framework._agents 模块

# 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

// .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<AITool>? Tools { get; }
    public string? Instructions { get; }
}

2.2 工作流系统

工作流（Workflow）是组合多个 Agent 或任务的编排机制。框架支持三种工作流模式：

Python 工作流基类 (来源：python/packages/core/agent_framework/_workflows/_workflow.py)：

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)：

public abstract class Workflow
{
    public abstract Task<WorkflowState> RunAsync(
        WorkflowState input, 
        CancellationToken cancellationToken = default);
}

2.3 工具系统

工具是 Agent 调用外部能力的接口，支持函数定义和资源绑定。

# @tool 装饰器示例 (来源：python/samples/01-get-started/README.md)
from agent_framework import tool

@tool
def get_weather(location: str) -> str:
    """获取指定位置的天气信息"""
    # 工具实现
    return f"{location} 的天气是晴天"

工具定义包含以下属性：

3. 会话与上下文管理

3.1 AgentSession 多轮会话

AgentSession 维护对话历史，支持跨请求的上下文保持。

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 接口动态注入额外上下文：

class ContextProvider(Protocol):
    """上下文提供者协议"""
    
    async def get_context(self) -> str:
        """获取额外上下文"""
        pass

使用示例 (来源：python/samples/01-get-started/04_memory.py)：

agent = Agent(
    name="my_agent",
    context_providers=[MyCustomContextProvider()]
)

4. 技能系统

技能（Skill）是一种可复用的 Agent 能力封装，支持文件和代码两种定义方式。

4.1 技能结构

技能抽象定义 (来源：dotnet/src/Microsoft.Agents.AI/Skills/AgentSkill.cs)：

public abstract class AgentSkill
{
    public abstract string Name { get; }
    public abstract string Description { get; }
    public abstract string Content { get; }
    public virtual IReadOnlyList<AgentSkillResource>? Resources => null;
    public virtual IReadOnlyList<AgentSkillScript>? Scripts => null;
}

4.2 技能加载流程

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)：

// 默认技能指令模板
private const string DefaultSkillsInstructionPrompt =
    """
    You have access to skills containing domain-specific knowledge and capabilities.
    <available_skills>
    {skills}
    </available_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. 部署与托管

框架支持多种部署模式：

托管示例项目 (来源：dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Workflow-Simple/README.md)：

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)：

7. 集成扩展

7.1 LLM 提供商支持

框架通过抽象接口支持多种 LLM 提供商：

7.2 Azure 服务集成

框架深度集成 Azure AI 服务：

• Azure AI Foundry：Agent 部署和托管
• Azure Content Understanding：文档、图像、音视频理解
• Azure AI Search：知识检索增强

集成示例 (来源：python/packages/azure-contentunderstanding/samples/README.md)：

# 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 创建、工作流编排、工具集成、会话管理的完整功能闭环。

框架架构概览

Agent Framework 采用分层架构设计，核心层负责会话状态管理和响应处理，应用层提供 Agent 的构建和工具集成能力。

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 是框架中管理多轮对话状态的核心抽象，封装了对话历史、用户标识和会话元数据。

// 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<string, string>? Metadata { get; set; }
    public IList<AgentMessage>? Messages { get; set; }
}

资料来源：dotnet/src/Microsoft.Agents.AI.Abstractions/AgentSession.cs

AgentResponse（Agent 响应）

AgentResponse 封装了 Agent 执行结果的完整信息，包括响应内容、工具调用、Token 使用统计等。

// dotnet/src/Microsoft.Agents.AI.Abstractions/AgentResponse.cs
public class AgentResponse
{
    public string? Content { get; set; }
    public IList<ToolCall>? ToolCalls { get; set; }
    public CompletionUsage? Usage { get; set; }
    public string? FinishReason { get; set; }
}

资料来源：dotnet/src/Microsoft.Agents.AI.Abstractions/AgentResponse.cs

Python 类型定义

Python SDK 提供了等效的类型定义，通过数据类实现会话和消息的建模。

# 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 实现，支持流式和非流式两种运行模式。

// 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<AITool>? tools = null,
        ILoggerFactory? loggerFactory = null,
        IServiceProvider? services = null);
}

资料来源：dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs

AgentSkill（技能）

AgentSkill 是框架中的技能抽象基类，支持文件定义和代码定义两种方式。

classDiagram
    class AgentSkill {
        <<abstract>>
        +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 支持通过代码直接定义技能：

// 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

会话管理

AgentSession 的生命周期

stateDiagram-v2
    [*] --> 创建会话: 首次交互
    创建会话 --> 活跃: 添加用户消息
    活跃 --> 活跃: 多轮对话
    活跃 --> 结束: 显式关闭或超时
    结束 --> [*]: 资源释放
    
    创建会话 --> 错误: 参数验证失败
    活跃 --> 错误: 服务不可用
    错误 --> [*]: 错误处理

Python 会话管理

Python SDK 提供了 AgentSession 类的完整实现：

# 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

Agent 模式（AgentMode）

AgentMode 定义了 Agent 的运行模式，支持交互式规划和自主执行两种模式。

// 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<AgentMode>? Modes { get; set; }
    public string? DefaultMode { get; set; }
}

资料来源：dotnet/src/Microsoft.Agents.AI/Harness/AgentMode/AgentModeProviderOptions.cs

工作流程集成

多 Agent 协作

框架支持将多个 Agent 组合成工作流，实现复杂的任务分解和执行：

graph LR
    subgraph "工作流"
        W1[主 Agent]
        W2[子 Agent 1]
        W3[子 Agent 2]
        W4[聚合器]
    end
    
    W1 --> W2
    W1 --> W3
    W2 --> W4
    W3 --> W4

工具系统

框架的工具系统支持两种调用方式：

[!NOTE]

默认情况下，所有提供的工具都会自动调用。AI 选择调用的函数和参数应被视为不受信任的输入。开发者应为具有副作用、访问敏感数据或执行不可逆操作的工具要求显式批准。

资料来源：dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs

快速入门示例

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 示例

// 创建 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?");

核心概念总结

概述

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

Agent 的核心组件

Python 实现架构

Python Agent 由以下核心类组成：

资料来源：python/packages/core/agent_framework/_agents.py:1-100

.NET 实现架构

在 .NET 侧，ChatClientAgent 类是核心实现：

public sealed class ChatClientAgent : AIAgent

资料来源：dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs:30-80

Agent 标识模型

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

Agent 的创建与初始化

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 构造函数接受以下核心参数：

资料来源：python/samples/01-get-started/01_hello_agent.py:1-50

.NET 创建模式

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

初始化流程

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 的运行机制

单轮对话执行

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

消息格式

Agent 使用结构化的消息格式进行通信：

工具集成

工具定义

Agent 通过工具扩展其能力范围。工具可以是：

• 函数工具：Python 函数或 .NET 方法，通过装饰器/属性暴露给 AI
• 外部 API：通过 HTTP 调用的远程服务
• 脚本：可执行的代码片段

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

.NET 工具定义

在 .NET 中，工具通过 AITool 接口实现，并可在创建 Agent 时传入：

AIAgent agent = client.AsAIAgent(
    tools: new List<AITool> { customTool },
    instructions: "Instructions here"
);

多轮对话与会话管理

Python 会话管理

Python Agent 通过 AgentSession 类管理多轮对话：

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

.NET 会话管理

// 使用 AIProjectClient 的 AsAIAgent 返回 AIAgent
// AIAgent 内部管理会话状态
string response = await agent.RunAsync("Hello, how are you?");

会话状态流转

stateDiagram-v2
    [*] --> 初始化: 创建 Agent
    初始化 --> 就绪: 客户端连接
    就绪 --> 处理中: 接收用户消息
    处理中 --> 等待工具: 需要调用工具
    等待工具 --> 处理中: 工具返回结果
    处理中 --> 就绪: 生成最终响应
    就绪 --> [*]: 会话结束

流式响应支持

Agent 支持流式输出模式，适合需要实时反馈的场景：

Python 流式调用

async for event in agent.run("讲一个故事", stream=True):
    print(event.delta, end="", flush=True)

.NET 流式调用

await foreach (var update in agent.RunAsync("Tell me a story", stream: true))
{
    Console.Write(update.Content);
}

上下文提供者

Agent 支持通过 ContextProvider 接口注入动态上下文：

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

错误处理与日志

异常处理

Agent 运行时可能遇到以下异常类型：

日志配置

// .NET 日志配置
var loggerFactory = LoggerFactory.Create(builder => 
    builder.AddConsole());

AIAgent agent = new ChatClientAgent(client, loggerFactory: loggerFactory);

# Python 日志配置
import logging
logging.basicConfig(level=logging.DEBUG)

最佳实践

设计原则

1. 清晰的指令设计：编写明确、简洁的系统指令，避免歧义
2. 合理的工具粒度：工具应职责单一，便于 AI 理解和调用
3. 适当的超时设置：为长时间运行的操作设置超时
4. 状态管理：善用会话管理维护对话上下文

性能优化

安全考虑

• 对具有副作用的工具强制要求用户确认
• 敏感操作实施访问控制
• 验证工具返回结果的合法性

相关资源

• Agent Framework 官方文档
• Python SDK 快速开始
• 示例代码库

概述

模型提供商集成（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

架构设计

整体架构

Agent Framework 采用分层架构设计，模型提供商作为独立的包存在，通过标准化的接口与核心框架解耦：

graph TD
    A[Agent / 业务逻辑层] --> B[核心框架层<br/>agent_framework.core]
    B --> C[聊天客户端抽象层<br/>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

Python 生态中的聊天客户端

Python 版本的 Agent Framework 为每个提供商提供了独立的聊天客户端类，这些类均继承自统一的基类或实现相同的接口：

资料来源：python/packages/openai/README.md

.NET 生态中的聊天客户端

.NET 版本采用类似的架构，通过扩展方法将聊天客户端转换为代理：

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

OpenAI 集成

Python 实现

Python 的 agent-framework-openai 包提供了两个聊天客户端类，分别对应 OpenAI 的两种 API：

#### OpenAIChatClient（Responses API）

这是推荐使用的客户端，使用 OpenAI 的 Responses API：

from agent_framework.openai import OpenAIChatClient

client = OpenAIChatClient(
    api_key="sk-...",
    model="gpt-4o"
)

模型优先级：OPENAI_CHAT_MODEL → OPENAI_MODEL

资料来源：python/packages/openai/README.md

#### OpenAIChatCompletionClient（Chat Completions API）

此客户端使用传统的 Chat Completions API，主要用于兼容现有集成：

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

环境变量配置

资料来源：python/packages/openai/README.md

.NET 实现

在 .NET 生态中，通过 OpenAIChatClientExtensions 扩展方法将 ChatClient 转换为 Agent：

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

Azure AI Foundry 集成

Python 实现

agent-framework-foundry 包提供了与 Azure AI Foundry 的深度集成：

from agent_framework_foundry import FoundryChatClient

client = FoundryChatClient(
    project_endpoint="https://your-project.services.ai.azure.com",
    model="gpt-4o"
)

Azure AI Foundry 集成主要使用环境变量配置：

资料来源：python/packages/core/README.md

.NET 实现

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

Anthropic Claude 集成

Python 实现

agent-framework-anthropic 包提供了 Claude 模型的集成：

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

核心使用模式

模式一：直接使用聊天客户端

适用于高级工作流，直接与聊天 API 交互：

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

模式二：创建代理

使用聊天客户端创建 Agent，让框架处理对话管理：

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

模式三：带工具的代理

为代理添加工具（函数调用）能力：

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

代理创建参数

ChatClientAgent 参数说明

资料来源：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 流式调用

async for chunk in client.stream([Message("user", ["你好"])]):
    print(chunk.content, end="", flush=True)

.NET 流式调用

await foreach (var update in agent.RunAsyncStreaming(
    new ChatMessage(ChatRole.User, "Hello")))
{
    Console.Write(update.Content);
}

多提供商工作流

Agent Framework 支持在同一应用中混合使用多个提供商：

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="你是一个简洁的问答助手。"
)

配置最佳实践

开发环境

# .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
• 通用: 环境变量或配置服务

客户端配置覆盖

环境变量可以被代码参数覆盖：

client = OpenAIChatClient(
    api_key="from-secret-manager",
    model="gpt-4o"
)

资料来源：python/packages/core/README.md

相关资源

• Python 快速开始示例
• OpenAI 包文档
• Foundry 包文档
• Anthropic 包文档
• .NET 示例：OpenAI Responses
• .NET 示例：OpenAI Chat Completion

概述

Agent Framework 的工具与技能系统是框架的核心扩展机制，旨在赋予 AI Agent 执行特定任务和访问领域知识的能力。该系统由两个相互关联但功能独立的子系统组成：

• 工具系统 (Tools)：为 Agent 提供可调用的函数能力，实现与外部系统的交互
• 技能系统 (Skills)：为 Agent 提供领域特定的指令、文档和资源，实现知识驱动的任务执行

资料来源：python/samples/01-get-started/README.md

系统架构

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 可以通过调用这些工具执行特定操作。工具定义包含以下核心属性：

资料来源：dotnet/src/Microsoft.Agents.AI/Harness/FileMemory/FileMemoryProvider.cs

内置工具示例

#### FileMemory 工具集

FileMemory 系统提供了一套完整的文件管理工具，Agent 可以使用这些工具进行持久化存储和知识检索：

[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<string> SaveFileAsync(
    string fileName, 
    string content, 
    string? description = null, 
    CancellationToken cancellationToken = default)

资料来源：dotnet/src/Microsoft.Agents.AI/Harness/FileMemory/FileMemoryProvider.cs:54-60

工具注册与调用流程

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: 返回结果

技能系统

技能架构概述

技能系统采用抽象基类设计，支持多种技能定义方式：

classDiagram
    class AgentSkill {
        <<abstract>>
        +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

AgentSkill 抽象基类

AgentSkill 是所有技能类型的基类，定义了技能的通用接口：

/// <remarks>
/// 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).
/// </remarks>
public abstract string Content { get; }

/// <summary>
/// Gets the resources associated with this skill, or null if none.
/// </summary>
public virtual IReadOnlyList<AgentSkillResource>? Resources => null;

/// <summary>
/// Gets the scripts associated with this skill, or null if none.
/// </summary>
public virtual IReadOnlyList<AgentSkillScript>? Scripts => null;

资料来源：dotnet/src/Microsoft.Agents.AI/Skills/AgentSkill.cs:15-35

代码定义技能 (AgentInlineSkill)

AgentInlineSkill 允许开发者以编程方式定义技能，无需使用外部文件：

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

技能内容构建器

AgentInlineSkillContentBuilder 内部类负责将代码定义的技能转换为 XML 格式的内容字符串：

public static string Build(
    string name,
    string description,
    string instructions,
    IReadOnlyList<AgentSkillResource>? resources,
    IReadOnlyList<AgentSkillScript>? scripts)
{
    var sb = new StringBuilder();
    
    sb.Append($"<name>{EscapeXmlString(name)}</name>\n")
      .Append($"<description>{EscapeXmlString(description)}</description>\n\n")
      .Append("<instructions>\n")
      .Append(EscapeXmlString(instructions))
      .Append("\n</instructions>");
    // ...
}

生成的 XML 结构示例：

<name>code-defined-skill</name>
<description>A code-defined skill example</description>

<instructions>
Your skill instructions here...
</instructions>

<resources>
<!-- 技能资源内容 -->
</resources>

资料来源：dotnet/src/Microsoft.Agents.AI/Skills/Programmatic/AgentInlineSkillContentBuilder.cs

AgentSkillsProvider 技能提供者

AgentSkillsProvider 是 AI 上下文提供者，负责将技能信息注入到 Agent 的执行上下文中：

graph LR
    subgraph "AgentSkillsProvider 内部机制"
        A[技能源] -->|读取| B[AgentSkillsSource]
        C[提示模板] -->|格式化| D[SkillsPlaceholder]
        B -->|注入| D
        D --> E[AIContext]
    end

#### 默认技能指令模板

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.

    <available_skills>
    {skills}
    </available_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.
    """;

#### 模板占位符说明

资料来源：dotnet/src/Microsoft.Agents.AI/Skills/AgentSkillsProvider.cs

技能与 Agent 的集成流程

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 工具执行脚本：

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

能力说明

使用示例

.NET 代码定义技能

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", "[email protected]" },
        { "version", "1.0.0" }
    }
);

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
• Microsoft Agent Framework 文档
• 入门示例

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）：工作流执行过程中的状态存储

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）

工作流状态用于在工作流执行过程中存储和传递数据。状态可以包含：

资料来源：python/samples/03-workflows/declarative/README.md

3. 工作流类型

3.1 命令式工作流（Imperative Workflow）

命令式工作流使用代码直接定义，允许开发者使用完整的编程语言能力。

#### 3.1.1 函数式工作流（Functional Workflow）

函数式工作流将工作流编写为普通的异步函数，使用原生的 if/else、循环和 asyncio.gather 等控制流语法。

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）结构。

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 基本结构

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 支持的动作类型

资料来源：python/samples/03-workflows/declarative/README.md

4. 系统架构

4.1 架构组件

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 构建工作流：

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 支持依赖注入和配置驱动：

services.AddAgentsWorkflows(options =>
{
    options.WorkflowBuilder = workflowBuilder;
});

资料来源：dotnet/src/Microsoft.Agents.AI.Workflows/WorkflowBuilder.cs

#### 4.2.3 DeclarativeWorkflowBuilder

声明式构建器从 YAML 加载工作流定义：

var workflow = DeclarativeWorkflowBuilder.Build("workflow.yaml", options);

# 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 同步与异步执行

工作流支持同步和异步两种执行模式：

# 非流式执行
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 代理调用链

在多代理工作流中，代理可以按顺序调用，形成处理链：

graph LR
    A[用户输入] --> B[翻译代理<br/>French Agent]
    B --> C[翻译代理<br/>Spanish Agent]
    C --> D[翻译代理<br/>English Agent]
    D --> E[最终输出]

每个代理接收前一个代理的输出作为输入，实现管道式处理。资料来源：dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Workflow-Simple/README.md

5.3 人机交互（HITL）

声明式工作流支持人类在环（Human-in-the-Loop）模式，允许工作流暂停等待人工输入：

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）功能，用于保存和恢复工作流执行状态：

graph LR
    A[执行中] -->|保存| B[检查点]
    B -->|恢复| C[继续执行]
    B -->|重启| D[从起始执行]

DevUI 可以显示工作流的检查点信息，包括完整的状态快照。资料来源：python/packages/devui/frontend/src/components/features/workflow/checkpoint-info-modal.tsx

6.2 状态查看

工作流状态可以通过 DevUI 的工作流视图组件查看：

资料来源：python/packages/devui/frontend/src/components/features/workflow/workflow-view.tsx

7. 工具与技能集成

7.1 函数工具

工作流中的代理可以调用函数工具（Function Tool）：

@tool
def get_weather(location: str) -> str:
    """获取指定位置的天气信息"""
    return f"{location} 今天天气晴朗"

资料来源：python/samples/01-get-started/README.md

7.2 技能（Skills）

技能是一种结构化的工具定义方式，支持代码定义和文件定义两种形式：

技能可以包含脚本、参考资料和执行命令。资料来源：python/samples/02-agents/skills/mixed_skills/README.md

8. 开发工具

8.1 DevUI

DevUI 提供了工作流的图形化开发界面：

资料来源：python/packages/devui/README.md

8.2 代码导出（Eject）

声明式工作流支持导出为代码，便于进一步定制：

var code = DeclarativeWorkflowBuilder.Eject(
    "workflow.yaml",
    DeclarativeWorkflowLanguage.CSharp,
    "MyNamespace"
);

支持的目标语言：

资料来源：dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/DeclarativeWorkflowBuilder.cs

9. 快速开始

9.1 Python 入门示例

pip install agent-framework

资料来源：python/samples/01-get-started/README.md

9.2 .NET 入门示例

cd dotnet/samples
dotnet run --project 01-hello-agent

10. 最佳实践

1. 选择合适的工作流类型：业务逻辑稳定时使用声明式工作流，需要复杂逻辑时使用命令式工作流
2. 合理设计状态结构：使用清晰的前缀命名（如 turn.、user.）区分不同来源的数据
3. 使用检查点恢复：对于长时间运行的工作流，定期保存检查点便于故障恢复
4. 流式输出优化：对延迟敏感的应用使用流式执行模式
5. 工具封装：将常用功能封装为工具，便于在多个工作流中复用

11. 相关资源

概述

工作流编排（Workflow Orchestration）是Microsoft Agent Framework中的核心能力，它允许开发者将多个代理（Agent）、工具（Tool）和功能组件组合成复杂的自动化流程。Agent Framework提供了多种编排模式，包括顺序执行、并发执行和交接（Handoff）机制，使开发者能够构建从简单到复杂的各种自动化工作流。

工作流编排系统的主要特点包括：

• 声明式定义：通过Python装饰器或C#构建器模式声明工作流结构
• 状态管理：内置的状态传递和上下文共享机制
• 异步支持：完整的异步执行模型，支持流式和非流式响应
• 错误处理：统一的异常捕获和恢复机制
• 可扩展性：支持自定义执行器和节点类型

核心组件

执行器（Executor）

执行器是工作流编排的基本构建单元，负责执行具体的任务或调用代理。每个执行器可以包含输入参数、执行逻辑和输出处理。

graph LR
    A[输入数据] --> B[执行器 Executor]
    B --> C{执行类型}
    C -->|同步| D[同步执行]
    C -->|异步| E[异步执行]
    C -->|流式| F[流式执行]
    D --> G[输出结果]
    E --> G
    F --> G

顺序工作流（Sequential Workflow）

顺序工作流按照定义的顺序依次执行各个执行器，前一个执行器的输出作为下一个执行器的输入。这种模式适用于步骤之间存在依赖关系的场景。

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#实现：

var workflow = new SequentialWorkflowBuilder()
    .AddStep(dataLoader)
    .AddStep(processor)
    .AddStep(formatter)
    .Build();

并发工作流（Concurrent Workflow）

并发工作流允许同时执行多个执行器，通过并行处理提高整体效率。适用于彼此独立、可同时运行的任务。

graph TD
    A[开始] --> B[并发执行]
    B --> C[执行器 A]
    B --> D[执行器 B]
    B --> E[执行器 N]
    C --> F[收集结果]
    D --> F
    E --> F
    F --> G[聚合输出]
    G --> H[结束]

关键参数：

交接工作流（Handoff Workflow）

交接工作流实现了代理之间的上下文传递，允许一个代理将控制权和会话状态移交给另一个代理。这是构建多代理协作系统的核心机制。

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提供了声明式的交接工作流构建方式：

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();

配置选项：

群组聊天管理器（GroupChatManager）

GroupChatManager是.NET实现中的群组聊天协调器，负责管理多个代理之间的对话交互和消息路由。

核心职责

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[返回用户]

管理功能

最佳实践

1. 工作流设计原则

• 单一职责：每个执行器应专注于单一任务
• 松耦合：执行器之间通过明确定义的接口通信
• 错误边界：为关键步骤添加错误处理和回退逻辑

2. 性能优化

• 识别并行机会：分析工作流中的独立步骤，尽量并行化
• 设置合理超时：防止单个任务长时间阻塞整个工作流
• 资源限制：使用max_concurrency控制并发资源使用

3. 调试技巧

• 启用详细日志：使用日志记录每个步骤的输入输出
• 状态检查点：在关键节点保存工作流状态便于恢复
• 逐步执行：开发阶段使用单步模式验证逻辑

相关示例

总结

工作流编排模式是构建复杂AI应用的基础，Agent Framework提供了从简单顺序处理到复杂多代理协作的完整解决方案。开发者可以根据业务需求选择合适的编排模式，并通过框架提供的丰富API实现高效、可靠的工作流系统。

概述

检查点（Checkpoint）与恢复（Resume）机制是 Agent Framework 工作流系统的核心功能之一，它允许长时间运行的工作流在中断后从上一个保存点继续执行，而无需重新开始整个流程。

核心能力

资料来源：dotnet/src/Microsoft.Agents.AI.Workflows/Checkpointing/ICheckpointManager.cs:1-15

Pitfall Log / 踩坑日志

项目：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