深入探索微软代理框架

Agent Framework

课程介绍

本课程将涵盖以下内容：

了解微软代理框架（Microsoft Agent Framework，简称 MAF）的核心功能与价值
探索微软代理框架的关键概念
学习高级 MAF 模式：工作流、中间件与内存管理

学习目标

完成本课程后，您将能够：

使用微软代理框架构建可投入生产的 AI 代理
将微软代理框架的核心功能应用于您的代理场景
运用高级模式，包括工作流、中间件和可观测性

代码示例

微软代理框架的代码示例可在本仓库中找到，路径为 xx-python-agent-framework 和 xx-dotnet-agent-framework。

了解微软代理框架

Framework Intro

微软代理框架（MAF）是微软推出的统一 AI 代理构建框架，具备灵活性，能够满足生产和研究环境中多样化的代理需求，包括：

顺序代理编排：适用于需要逐步执行工作流的场景
并发编排：适用于多个代理同时完成任务的场景
群聊编排：多个代理协作完成同一任务
任务交接编排：代理间按子任务完成情况交接任务
磁性编排：管理代理创建和调整任务列表，协调子代理完成任务

为了支持生产环境中的 AI 代理，MAF 还提供了以下功能：

可观测性：通过 OpenTelemetry 实现，监控代理的每一步操作，包括工具调用、编排流程、推理过程和性能，支持微软 Foundry 仪表盘展示
安全性：代理原生托管于微软 Foundry，具备基于角色的访问控制、私有数据处理和内容安全机制
持久性：代理线程和工作流支持暂停、恢复及错误恢复，适合长时间运行的流程
控制能力：支持人工介入流程，任务可标记为需人工审批

此外，微软代理框架注重互操作性：

云无关性：代理可运行于容器、本地或多云环境
提供商无关性：支持多种 SDK 创建代理，包括 Azure OpenAI 和 OpenAI
开放标准集成：支持 Agent-to-Agent (A2A) 和 Model Context Protocol (MCP) 协议，便于发现和调用其他代理及工具
插件与连接器：支持连接 Microsoft Fabric、SharePoint、Pinecone、Qdrant 等数据和内存服务

接下来，我们将详细介绍微软代理框架的核心概念及其应用。

微软代理框架的关键概念

代理（Agents）

Agent Framework

创建代理

代理的创建包括定义推理服务（如 LLM 提供者）、代理执行的指令以及代理名称：

agent = AzureOpenAIChatClient(credential=AzureCliCredential()).create_agent(
    instructions="你擅长根据客户偏好推荐旅行方案。",
    name="TripRecommender"
)

以上示例使用 Azure OpenAI，代理也可以通过多种服务创建，如 Microsoft Foundry Agent Service：

AzureAIAgentClient(async_credential=credential).create_agent(
    name="HelperAgent",
    instructions="你是一个乐于助人的助手。"
) as agent

或者使用 OpenAI 的 Responses 和 ChatCompletion API：

agent = OpenAIResponsesClient().create_agent(
    name="WeatherBot",
    instructions="你是一个有用的天气助手。"
)

agent = OpenAIChatClient().create_agent(
    name="HelpfulAssistant",
    instructions="你是一个乐于助人的助手。"
)

还可以通过 A2A 协议创建远程代理：

agent = A2AAgent(
    name=agent_card.name,
    description=agent_card.description,
    agent_card=agent_card,
    url="https://your-a2a-agent-host"
)

运行代理

代理通过 .run 或 .run_stream 方法运行，分别支持非流式和流式响应：

result = await agent.run("阿姆斯特丹有哪些值得游览的地方？")
print(result.text)

async for update in agent.run_stream("阿姆斯特丹有哪些值得游览的地方？"):
    if update.text:
        print(update.text, end="", flush=True)

运行时可自定义参数，如 max_tokens、可调用的 tools 以及所用的 model，满足特定任务需求。

工具（Tools）

工具可在定义代理时指定：

def get_attractions(location: Annotated[str, Field(description="获取指定地点的热门景点")]) -> str:
    """获取指定地点的热门景点。"""
    return f"{location}的热门景点有。"

agent = ChatAgent(
    chat_client=OpenAIChatClient(),
    instructions="你是一个乐于助人的助手",
    tools=[get_attractions]
)

也可以在运行时临时传入工具：

result1 = await agent.run(
    "西雅图有哪些值得游览的地方？",
    tools=[get_attractions]  # 本次运行专用工具
)

代理线程（Agent Threads）

代理线程用于处理多轮对话，可通过 get_new_thread() 创建并保存线程状态，或在运行时自动创建临时线程：

thread = agent.get_new_thread()
response = await agent.run("你好，我可以帮你预订旅行。你想去哪儿？", thread=thread)

线程可序列化保存，方便后续恢复：

serialized_thread = await thread.serialize()
resumed_thread = await agent.deserialize_thread(serialized_thread)

代理中间件（Agent Middleware）

中间件用于在代理与工具或 LLM 交互时插入自定义逻辑，如日志记录。

函数中间件：在调用工具函数前后执行操作，例如日志记录。

async def logging_function_middleware(
    context: FunctionInvocationContext,
    next: Callable[[FunctionInvocationContext], Awaitable[None]],
) -> None:
    print(f"[Function] 调用 {context.function.name}")
    await next(context)
    print(f"[Function] {context.function.name} 执行完成")

聊天中间件：在代理与 LLM 交互请求前后执行操作，记录消息数量等信息。

async def logging_chat_middleware(
    context: ChatContext,
    next: Callable[[ChatContext], Awaitable[None]],
) -> None:
    print(f"[Chat] 发送 {len(context.messages)} 条消息到 AI")
    await next(context)
    print("[Chat] 收到 AI 响应")

代理内存（Agent Memory）

内存是代理跨上下文操作的关键，MAF 提供多种内存类型：

内存存储（In-Memory Storage）：线程运行时的临时内存。

thread = agent.get_new_thread()
response = await agent.run("你好，我可以帮你预订旅行。你想去哪儿？", thread=thread)

持久消息（Persistent Messages）：跨会话保存对话历史，使用 chat_message_store_factory 定义：

from agent_framework import ChatMessageStore

def create_message_store():
    return ChatMessageStore()

agent = ChatAgent(
    chat_client=OpenAIChatClient(),
    instructions="你是一个旅行助手。",
    chat_message_store_factory=create_message_store
)

动态内存（Dynamic Memory）：运行前添加到上下文，可存储于外部服务，如 mem0：

from agent_framework.mem0 import Mem0Provider

memory_provider = Mem0Provider(
    api_key="your-mem0-api-key",
    user_id="user_123",
    application_id="my_app"
)

agent = ChatAgent(
    chat_client=OpenAIChatClient(),
    instructions="你是一个有记忆的乐于助人助手。",
    context_providers=memory_provider
)

代理可观测性（Agent Observability）

MAF 集成 OpenTelemetry，支持追踪和指标监控，提升系统可靠性和可维护性：

from agent_framework.observability import get_tracer, get_meter

tracer = get_tracer()
meter = get_meter()
with tracer.start_as_current_span("my_custom_span"):
    pass
counter = meter.create_counter("my_custom_counter")
counter.add(1, {"key": "value"})

工作流（Workflows）

MAF 提供预定义步骤的工作流，包含 AI 代理作为组件，支持多代理编排和状态检查点保存。

工作流核心组件包括：

执行器（Executors）：接收输入消息，执行任务，输出消息推动工作流前进，执行器可为 AI 代理或自定义逻辑。
边（Edges）：定义消息流向，包括：
- 直接边（Direct Edges）：一对一连接
- 条件边（Conditional Edges）：满足条件后激活
- 分支边（Switch-case Edges）：根据条件路由消息
- 扇出边（Fan-out Edges）：一条消息发送至多个目标
- 扇入边（Fan-in Edges）：多个消息汇聚到一个目标

MAF 还提供内置事件以增强工作流可观测性，如：

WorkflowStartedEvent：工作流开始
WorkflowOutputEvent：工作流输出
WorkflowErrorEvent：工作流错误
ExecutorInvokeEvent：执行器开始处理
ExecutorCompleteEvent：执行器完成处理
RequestInfoEvent：请求发出

高级 MAF 模式

构建复杂代理时，可考虑以下高级模式：

中间件组合：链式调用多个中间件（日志、认证、限流），实现细粒度控制
工作流检查点：利用事件和序列化保存、恢复长时间运行的流程
动态工具选择：结合基于工具描述的检索增强生成（RAG）和 MAF 工具注册，针对查询动态呈现相关工具
多代理交接：通过工作流边和条件路由，实现专业代理间的任务交接

代码示例

微软代理框架的示例代码位于本仓库的 xx-python-agent-framework 和 xx-dotnet-agent-framework 文件夹中。

还有关于微软代理框架的问题？

欢迎加入微软 Foundry Discord，与其他学习者交流，参加答疑时间，解决您的 AI 代理相关疑问。

深入探索微软代理框架

深入探索微软代理框架

课程介绍

学习目标

代码示例

了解微软代理框架

微软代理框架的关键概念

代理（Agents）

工作流（Workflows）

高级 MAF 模式

代码示例

还有关于微软代理框架的问题？

标签

评论

相关阅读

2026 年的 DeepSeek：从 V2 到 V3.2 发生了什么变化，现在的用户该怎么看

如何为品牌拍摄撰写AI图像提示词

什么是Claude托管代理？