Microsoft Agent Framework：统一智能体框架的上手与生产实践

为什么需要 Microsoft Agent Framework：智能体框架碎片化的解法

2023 至 2025 年间，智能体开发框架迅速碎片化：AutoGen 以双智能体对话流见长，适合快速原型，但可观测性、权限控制、人机审批等生产级能力几乎要全部外包给周边工具；Semantic Kernel 企业集成能力强（插件、规划器、云服务对接成熟），但多智能体协作要手动编排，复杂度高。社区还有 LangGraph 的状态图、CrewAI 的角色化 Crew 等方案，API 互不兼容。实际团队落地时往往同时维护两套框架代码：一套跑对话原型，一套做企业集成，选型争论和迁移成本长期消耗工程资源。

Agent Framework 的解法是「统一」而不是再添一个框架：把 Semantic Kernel 与 AutoGen 两套代码合并进一个仓库，1.0 版把生产级能力变成一等公民内置——中间件管道统一处理每条消息的进出，OpenTelemetry 遥测默认开启，Chats 与 Workflow 提供两种互补的编排原语，Agent Catalog + Agent Factory 支持「配置即部署」。C# 与 Python 两套 API 对齐，既有 AutoGen 与 Semantic Kernel 的代码可以平滑迁移，而不是推倒重来。

与同类工具相比，Agent Framework 的气质更像「带治理能力的智能体平台」而非单一编排器：LangGraph 是「图即一切」，CrewAI 是「角色即一切」，而 Agent Framework 把横切能力（中间件）、协作能力（Chats）、流程能力（Workflow）分层提供，再叠加运行时与云托管。它最适合已有微软技术投入（.NET、Visual Studio、Azure）的团队；若你是纯 Python 且深度绑定 LangChain 生态，LangGraph 仍是更顺的选择。

安装与环境配置：4 步就绪

前置条件：.NET 8 SDK（C#）或 Python 3.10+（推荐 3.11+），两者选其一即可。跑通示例还需一个 GitHub Token（GitHub 个人访问令牌，供 GitHub Models 调用默认模型）。

步骤一·安装 .NET 包（C# 项目）：核心安装 Microsoft.Agent.Core（智能体核心抽象）、Microsoft.Agent.Runtime（运行时）与 Microsoft.Agent.Configuration（配置与目录）三个包；需要语义内核或 AutoGen 兼容层时再追加对应运行时包。

步骤二·安装 Python 包：执行 pip install agent-framework。注意包名与旧版 AutoGen 的 autogen/pyautogen 完全不同，不要装混。

步骤三·配置模型凭据：快速开始默认使用 GitHub Models 上的 gpt-4o-mini，只需设置 GITHUB_TOKEN 环境变量；改走 Azure OpenAI 时设置 AZURE_OPENAI_API_KEY 等四个变量；本地模型则配置 Ollama 或 ONNX 路径。

步骤四·验证安装：运行下方「快速上手」的 hello_agent.py，看到模型回复即安装成功。python -c "import agent_framework" 不报错只说明包装上了，不代表模型链路通。

# 1) .NET 项目（.NET 8+）dotnet new console -o HelloAgentcd HelloAgentdotnet add package Microsoft.Agent.Coredotnet add package Microsoft.Agent.Runtimedotnet add package Microsoft.Agent.Configuration # 2) Python（Python 3.10+）pip install agent-framework # 3) 模型凭据：默认走 GitHub Models 调用 gpt-4o-miniexport GITHUB_TOKEN=ghp_xxxxxxxx# 或改用 Azure OpenAI：# export AZURE_OPENAI_API_KEY=xxx# export AZURE_OPENAI_ENDPOINT=https://xxx.openai.azure.com/# export AZURE_OPENAI_DEPLOYMENT=xxx# export AZURE_OPENAI_MODEL=gpt-4o-mini # 4) 验证：运行下面的 hello_agent.py，看到模型输出即成功python hello_agent.py

快速上手：10 分钟跑通 HelloAgent

最小编码路径：创建一个智能体 → 发一条消息 → 打印完整对话历史。这个示例不写工具、不画工作流、不接云服务，只验证「安装 + 模型链路 + 基础 API」三件事，是排查后续一切问题的最小基线。

操作步骤：

1. 建项目：Python 用户新建 hello_agent.py；.NET 用户执行 dotnet new console 生成 Program.cs。

2. 获取 Token：登录 GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic) → Generate new token 创建一个令牌，无需授予任何仓库权限，仅用于访问 GitHub Models。

3. 设置环境变量：把上面生成的令牌写入 GITHUB_TOKEN（或写入 .env 后加载）。

4. 粘贴代码并运行：Python 用户运行 python hello_agent.py；观察输出：先是 user: 你好…，随后出现 assistant: … 即成功。

5. 进阶改动：修改 description 改变智能体人设；在 create_agent 结果上调用 set_model 切换模型；本地有 Ollama 时可直接指向本地模型，不依赖任何云凭据。

运行结果中 chat_history 是完整消息列表，包含每一轮的角色与内容——这是 Agent 框架返回的统一数据结构，后续所有智能体的输出都遵循同一形态。C# 侧 API 与 Python 对齐：在 Microsoft.Agent 命名空间下使用 AgentFactory.CreateAgent(...) 创建智能体，调用 SendMessageAsync 发送消息，返回对象同样携带完整对话历史。

# hello_agent.py：Agent Framework 最小示例（Python）from agent_framework.agent import AgentBuilder # 创建智能体，默认模型 gpt-4o-mini（经 GitHub Models）agent = AgentBuilder.create_agent(    name="helloagent",    description="一个会打招呼并简要自我介绍的智能体",) # 发送消息，返回带完整对话历史的响应response = agent.send_message("你好，请介绍一下你自己。") for message in response.chat_history:    print(f"{message.role}: {message.content}")

核心能力详解：5 大支柱

支柱一·Middleware（中间件管道）。每条消息进出智能体时都会经过一条中间件链，用于承载日志、缓存、限流、权限校验、敏感词过滤等横切关注点（泛指与业务无关、横跨所有请求的通用逻辑）。中间件按注册顺序包裹执行，异常处理中间件必须调用 next 才会放行链路。这一设计取代了旧 Semantic Kernel 的 Filters 与 AutoGen 分散的 Hook，让「消息前后处理」有了统一模型。

支柱二·Chats（对话编排）。当多个智能体需要自由协作、任务边界模糊时，用声明式定义描述参与者与对话规则，框架自动调度发言顺序，支持在任意节点插入人类消息。典型场景是「研究员 + 写手 + 审校」三智能体协作：不需要手画流程图，通过 Chat.from_definition(...) 传入定义即可运行，框架负责多轮对话的推进行为。

支柱三·Workflow（工作流）。面向确定性子任务的图式编排：节点可以是智能体或工具，边表达条件与数据流，支持并行分支。它取代了 AutoGen 0.4 的 StateGraph 显式状态机——旧写法需手动声明节点与边，新写法更接近「定义步骤 + 依赖关系」的声明式风格。适合订单处理、质检流水线、工单路由等步骤固定的流程。

支柱四·Agent Runtime（运行时与迁移兼容）。框架核心内置两套运行时：Semantic Kernel 运行时与 AutoGen 运行时，既有代码可复用底层能力（插件、工具、规划器），不必彻底重写。Agent Catalog 负责集中注册智能体及其配置，Agent Factory 按目录项实例化——这是「配置即部署」的基础，也是后续推送到云端托管的前提。

支柱五·可观测性与治理。使用 OpenTelemetry 输出消息级追踪与指标：每次智能体调用的延迟、token 消耗、工具调用次数均可在标准遥测后端查看。人机协同是核心抽象而非插件——审批节点、人类反馈可插入任意流程位置。这些能力在 1.0 中是内建的，而非靠外部拼装。

生产部署与监控：从上线到运维

部署方式一：容器自托管。把智能体服务打包为 Docker 镜像，通过标准环境变量接入可观测性后端。设 OTEL_EXPORTER_OTLP_ENDPOINT 指向你的 OpenTelemetry Collector（如 Grafana Tempo/Prometheus 组合），框架会自动导出追踪与指标，无需改业务代码。中间件里可把业务上下文（订单号、租户 ID）注入 trace 的 span（追踪中的一次操作片段），便于按业务维度检索日志。

部署方式二：Azure AI Foundry Agent Service 云端托管。将本地 Agent Catalog 的配置同步上云，获得托管执行环境、配额管理、审计日志与版本管理。本地 Workflow 与 Chat 定义可平滑迁移，适合需要统一治理（密钥托管、审批策略、模型配额）的企业。托管环境下可启用 Bing 搜索 grounding（把搜索检索结果作为事实依据拼接给模型，降低幻觉），这是自托管需要自行实现的环节。

可观测性。上线后重点盯三类指标：消息级延迟（中间件是否引入额外开销）、token 消耗（按智能体与流程维度拆分）、工具调用成功率。人机协同节点要单独埋点统计「转人工率」——这是衡量智能体覆盖率的核心业务指标。

<p class="para-label">避坑清单：</p>

<ul class="dash-list"><li>包名与仓库更名：Python 新包是 agent-framework，旧 autogen/pyautogen 教程的代码无法直接运行；GitHub 上 microsoft/autogen 已重定向到 microsoft/agent-framework，收藏旧链接会失效。</li><li>默认模型依赖 GitHub Token：HelloAgent 默认经 GitHub Models 调用 gpt-4o-mini，未设 GITHUB_TOKEN 会报认证类错误，容易被误判为安装失败。</li><li>旧 API 不可照搬：AutoGen 0.4 的 StateGraph/Graph 写法在 1.0 中不存在，需改写为 Workflow 或 Chat，直接复制旧代码会编译或运行失败。</li><li>中间件顺序与性能：中间件按注册顺序包裹执行，不调用 next 会截断链路；数量越多单次消息延迟越高，只放真正的横切关注点。</li><li>双语言包名不同：C# 用 Microsoft.Agent.* 命名空间，Python 用 agent_framework 模块，混用会 import 失败；API 虽对齐但包名不互通。</li></ul>

版本迭代

该框架经历了「AutoGen 对话框架 → v0.4 事件驱动重构 → 与 Semantic Kernel 合并 → Agent Framework 1.0 正式版」四个阶段。2025 年 10 月 Ignite 大会发布预览版，仓库从 microsoft/autogen 更名为 microsoft/agent-framework；2025 年 11 月发布 1.0 GA，截至本稿整理时最新正式版为 1.0（补丁版本以 NuGet/PyPI 发布记录为准）。

AI 应用场景

常见误区

面试题

参考来源

• webpageNuGet：Microsoft.Agent.Core.NET 核心包下载与版本历史