技术速递｜智能体构建智能体：基于 Microsoft Agent Framework 与 Foundry 的 Skill 优先架构蓝图

作者：卢建晖 - 微软高级云技术布道师
排版：Alan Wang

改变一切的一个关键洞察

大多数“如何构建 AI Agent”的教程，都会把两项完全不同的工作混在一起：

• 构建智能体（编写代码、定义工具、评估、打包），以及

• 运行智能体（规划、推理、调用工具、记住用户信息并交付最终结果）。

一旦将它们拆分开，现代智能体开发就会变成一个清晰的双层架构：

上层是编码智能体——它负责生产智能体；下层是运行时智能体——它才是真正为业务运行的智能体。Microsoft Agent Framework 是连接这两层的 SDK，而 Microsoft Foundry 则是这两层共同发布和运行的平台。

但真正的秘诀——也是让一个通用 Copilot 变成领域专家工程师的关键——就是SKILL。SKILL 是编码智能体在写下第一行代码之前首先读取的内容。它将需求转化为真正符合你的框架、开发规范和测试数据的交付物。

本文将按照最合理的学习顺序，完整介绍整个双层架构，并将 SKILL 作为第一层的核心内容进行讲解。文中的所有概念都会结合虚构的全球电商公司 ZavaShop 进行说明：它拥有 5 个履约中心、数十家供应商，而 CEO 希望通过一个实时仪表盘统一管理所有业务。Python和 **.NET（C#）**均获得完整支持，你可以根据团队实际生产环境所使用的语言进行选择。

第一层—— 编码智能体（构建阶段）

编码智能体并不是与你的客户直接交互的智能体。它负责构建那个真正与客户交互的智能体。它的输出是一整套交付物，包括代码、智能体定义、工作流、Skills、连接器、评测、测试、配置和文档，这些内容都会经过验证，最终发布到 Microsoft Foundry。

整个构建阶段可以分为五个部分。

第一阶段 —— 需求与规划

在编码智能体写下第一行代码之前，你需要先提供三样东西：

1. 一个真实的业务痛点。不是“我们来做一个智能体”，而是“西雅图配送中心的主管 Mei 每天都会因为库存查询被打断 60 次。”

2. 一组验收标准。什么才算完成？例如：“智能体能够回答我们 10 个 SKU 商品目录中的库存问题；P95 响应延迟低于 4 秒；在评测数据集上的错误工具调用率低于 5%。”

3. 它将运行的数据集。使用真实或接近真实的数据，例如仓库、SKU、采购订单、客户等，这样编码智能体就不会在真空环境中推理。

ZavaShop 业务示例。整个 Workshop 提供了workshop/data/数据集，包括 5 个仓库、10 个 SKU、6 个采购订单、8 家供应商、5 份合同、4 位客户（其中 3 位 VIP）、6 个订单、5 家承运商以及 4 个待处理异常。编码智能体生成的所有交付物都会基于这一套共享测试数据，因此整个系统中的数据始终保持一致。

第二阶段 ——编码智能体与它的 SKILL（构建阶段的核心）

这是绝大多数团队都会跳过的一步，但恰恰也是决定最终生成的是专业工程代码，还是“ChatGPT 风格代码”的关键所在。

编码智能体到底是什么

编码智能体本质上就是运行在 Agent Mode 下的 GitHub Copilot Chat，并配置了一份具备领域知识的智能体定义。在 ZavaShop Workshop 中，它位于.github/agents/zavashop-coding-agent.agent.md，并通过 VS Code 的 Agent 选择器进行启用。每次开始开发时，你只需要输入一句简单的话：

“我正在使用 Python 开发库存智能体，请基于测试数据集接入库存和采购订单查询，并添加一个用于仓库手册的 HostedMCPTool。”

请注意，这句话里没有出现任何库名、类名或文件路径。编码智能体需要自己补全这些内容，而它所依赖的机制，就是SKILL。

什么是 SKILL

SKILL 是一份结构化契约，用来告诉编码智能体如何按照你的框架、编码规范以及业务领域来编写代码。它是整个构建阶段中最重要的文件——没有它，GitHub Copilot 只是一个知识广泛的通才；有了它，它就会变成一位熟悉你业务领域的专家，写出的代码就像你的技术负责人亲自完成的一样。

从概念上来说，一份 SKILL 包含以下内容：

SKILL 会与代码库一起进行版本管理。当框架引入新的最佳实践时，你只需要更新一次 SKILL，之后所有新构建出来的智能体都会自动采用这些新规范。这也是避免团队开发规范逐渐漂移的最重要原因。

ZavaShop Workshop 中提供的六个 SKILL

Workshop 提供了六份 SKILL——每种语言各三份——覆盖三个相互独立的能力领域：

编码智能体如何使用 SKILL

编码智能体的工作流程遵循SKILL 优先，代码其次的原则：

这一开发原则可以归纳为 Workshop 中反复强调的一句话：

“先阅读 SKILL。”

这不是可选项。如果跳过这一步，你得到的就只是通用 Copilot 生成的代码，而不是符合团队规范的代码。

第三阶段 —— 一个完整示例：从一句话到一个可运行的智能体

下面，我们来看一个完整的过程：当你面对 Coding Agent，只输入一句话时，会发生什么。

“我正在使用 Python 开发库存智能体，请基于测试数据集接入库存和采购订单查询，并添加一个用于仓库手册的 HostedMCPTool。”

步骤 1 —— 编码智能体路由

编码智能体的定义文件（.github/agents/zavashop-coding-agent.agent.md）中包含了一张路由表：

在执行任何操作之前，它会先将这两个文件加载到上下文中。

步骤 2 —— 编码智能体制定计划

编码智能体会结合 SKILL 中定义的开发模式以及 LAB 的验收标准，生成如下执行计划：

计划中的每一项内容，都可以追溯到 SKILL（告诉它如何实现）或 LAB README（告诉它需要实现什么）。整个过程没有凭空创造，也没有猜测。

步骤 3—— 编码智能体生成代码

直到这一步，它才真正开始编写代码。由于 SKILL 已经定义好了开发模式，因此最终生成的代码会自然地遵循你现有代码库的风格和规范。

# scripts/inventory_agent.py import os import sys from pathlib import Path # Pattern from SKILL: add data folder to sys.path, import named loaders sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "data")) from zava_data import find_stock, find_po # noqa: E402 from agent_framework import HostedMCPTool from agent_framework_azure_ai import AzureAIAgentClient from azure.identity import DefaultAzureCredential def stock_lookup(sku: str, warehouse: str) -> dict: """Return on-hand quantity for a SKU at a warehouse.""" return find_stock(sku, warehouse) def po_lookup(po_id: str) -> dict: """Return the status of a purchase order.""" return find_po(po_id) async def main() -> None: client = AzureAIAgentClient( project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"], model_deployment_name=os.environ["FOUNDRY_MODEL"], # gpt-5.5 from env async_credential=DefaultAzureCredential(), ) agent = client.create_agent( name="Zara", instructions=( "You are Zara, the warehouse assistant for Seattle DC (SEA-01). " "Use the tools when asked about stock or POs. " "Answer briefly." ), tools=[ stock_lookup, po_lookup, HostedMCPTool( name="warehouse-docs", url=os.environ["WAREHOUSE_DOCS_MCP_URL"], ), ], ) thread = agent.get_new_thread() print(await agent.run("How many SKU-7421 are at SEA-01?", thread=thread))

请注意，SKILL 在无需你额外说明的情况下，就已经强制约束了许多内容：基于环境变量的配置、带有文档字符串的命名函数工具、基于sys.path的数据加载模式、与函数工具并列配置的 HostedMCPTool，以及用于支持多轮对话的线程机制。

步骤 4 —— 编码智能体执行验证

SKILL 同样定义了验证方式。编码智能体会执行以下验证：

• 针对测试数据运行冒烟测试（例如：SKU-7421 @ SEA-01 → 312）。

• 运行评测数据集（eval_queries.jsonl）——是否调用了正确的工具？回答中是否包含预期的信息？

• 执行一轮红队测试。

随后，它会返回验证结果：“3/3 项验收标准全部通过。Eval 得分 5/5。Red-Team：未发现成功的 Prompt 注入攻击。”

步骤 5 —— 完成

最终提交到代码仓库中的，不仅仅是一段脚本，而是一整套交付物——代码、智能体定义、工具、评测数据、一页式 README——它们完全符合团队构建智能体的开发规范。这套交付物也将进入接下来的三个阶段。

第四阶段 —— 智能体交付物

一个经过良好指导的编码智能体会生成八类交付物，它们共同组成了一个可以部署的智能体：

这里需要区分两种不同含义的“Skill”。SKILL 文件（全部大写，位于.github/skills/）是在构建阶段用于指导编码智能体的；而 Agent Skill（Foundry 中的概念）则是运行时智能体在运行时调用的一项具名能力。这两个名称并非巧合——第一层的 SKILL，会生成包括第二层 Agent Skills 在内的多种交付物。

第五阶段 —— 验证

在任何交付物发布到 Microsoft Foundry 之前，都需要通过四道验证关卡：

1. 测试——包括单元测试和集成测试。例如，find_stock("SKU-7421", "SEA-01")是否返回测试数据中对应的库存值312？

2. 代码检查与类型检查——Python 使用ruff和mypy，.NET 检查dotnet build的警告信息。模型同样需要理解这些类型签名，设计粗糙的类型定义会导致真实的 Bug。

3. 评估——运行评测数据集。是否调用了正确的工具？回答是否包含预期的信息？你需要的是一个可以量化的评分，而不是一种“感觉不错”的主观判断。

4. 红队测试——使用对抗性输入，尝试诱导智能体偏离任务目标，或获取其他客户的数据。Microsoft Foundry 的 Red-Team SDK 已经内置了大量此类测试用例。

总结：“我们构建了一个智能体”并不是一个完整的交付成果；“我们构建了一个智能体，并且这里有它在版本化评测集上的通过率，以及对应的红队测试报告”，这才是真正的交付成果。验证应该属于构建阶段，而不是留到以后再补。

第六阶段 —— 发布与部署

当所有验证全部通过后，编码智能体生成的交付物便会流向 Microsoft Foundry 和 Azure：

• 发布到 Microsoft Foundry——智能体定义、Skills、Toolbox 工具以及自定义评测都会注册到对应的 Foundry 项目中，随后统一进行治理、版本管理和可观测性管理。

• 部署到 Azure——运行时宿主程序（AG-UI Server、Workflow Worker、Teams 应用、API 服务等）将部署到对应的 Azure 目标环境（App Service、Container Apps、AKS 或 Functions）。本地开发和云端运行共用同一套环境变量配置。

同一套交付物可以部署到开发、预发布和生产环境。你的智能体不存在所谓“仅生产环境使用”的代码。

第二层——运行时智能体（运行时）

智能体正式上线运行后，所有对话、针对业务数据执行的各类操作、写入的记忆数据，全部归属第二层架构。本层由五大核心模块构成。

模块一：用户与交互渠道

运行时智能体依托用户日常使用的各类渠道触达终端用户：

• Microsoft Teams：智能体嵌入日常办公场景，无需切换工具；

• Outlook：自动邮件分拣、回复撰写、内容总结、日程排期；

• 定制网页 / 移动端 / 语音端：基于AG-UI界面框架搭建，配套 React 客户端，原生支持流式文本、前端工具、后端工具、全局共享状态、生成式 UI、预测式界面更新、人机交互提示词等能力。

交互渠道仅为部署选型，不改变底层架构逻辑。同一套智能体配置文件，可同时部署在 Teams 与 React 可视化管理面板。

ZavaShop 业务示例。运营专员 Mei 的智能体部署在 Teams；CEO 专属管控大屏是基于 AG-UI 开发的 React 应用。两套前端背后，使用编码智能体生成的同一套底层智能体资源文件。

模块二：运行时智能体本体

你反复接触的智能体循环推理流程，在本层落地为标准化架构实体：

AI 智能体 = 大模型 + 系统指令集 + 工具集 + 对话线程

推理循环完整流程：

1. 大模型规划任务、逻辑推演，确定下一步执行动作

2. 通过 MCP 协议、工具工具箱或本地函数调用外部能力

3. 读写持久化记忆库

4. 将推理结果流式推送至前端交互渠道

# Python — the runtime shape (exactly what the Coding Agent produced) agent = client.create_agent( name="Zara", instructions="You are Zara, the warehouse assistant for Seattle DC.", tools=[stock_lookup, po_lookup, warehouse_docs_mcp], )

模块三：工具与集成能力（运行时能力载体）

运行阶段，智能体通过四类能力对接外部系统，选型需结合工程场景综合判断：

落地演进思路：

初期可直接使用本地函数工具；一旦第二个智能体需要复用同一业务能力，立即迁移至公共工具箱统一管理。

ZavaShop 业务示例。本地静态库存数据查询 → 本地函数工具。仓储操作手册文档检索 → MCP 协议工具。采购、履约、财务多部门共用供应商门户连接器 → 公共工具箱工具。“依据合同校验采购单”完整业务流程 → 封装为独立智能体 Skill。

模块四：记忆与状态管理

运行时分为两类状态数据：

对话线程：单次对话内临时上下文状态

thread = agent.get_new_thread() await agent.run("Look up PO-1043.", thread=thread) await agent.run("And its supplier?", thread=thread) # knows which PO

全局记忆：跨多轮对话持久化状态

Foundry 记忆库存储用户长期稳定业务信息：客户 VIP 等级、包装偏好、收货时段等，仅留存固定业务事实与偏好，不存储完整聊天记录。

ZavaShop 业务示例。客服智能体 Aria 可跨会话记住客户 C-204 为 VIP、拒绝纸箱包装、偏好 18:00–20:00 送货。

模块五：执行与输出

生产级智能体执行操作会变更业务状态，并产出可供其他系统消费的结果：

• 触发事件：启动自动化工作流、推送人工预警；

• 生成业务单据：创建采购单、草拟邮件、写入业务数据库；

• 渠道消息推送：回传 Teams 消息、更新可视化面板、调用外部 Webhook；

• 全链路可观测：所有操作日志实时推送至应用洞察 / Azure 监控平台。

工作流编排能力同样部署在本层，WorkflowBuilder 是智能体框架原生流程编排核心组件：

三大核心能力：

1. 能力复用：开发阶段定义的工具，运行时直接作为流程节点，无需重复开发；

2. 人机协同（HITL）：流程可暂停、推送人工审批，审批完成后从暂停节点继续执行；

3. 断点续跑：服务重启后，工作流可从最近检查点恢复执行。

ZavaShop 业务示例。履约总监 Diego 团队每日处理上万美金级异常订单。优化前：跨5个部门邮件来回沟通；优化后：基于 WorkflowBuilder 搭建可视化流程，内置人工审批节点，完整留存全链路审计日志。

跨层公共支撑：企业级安全共享服务

两层架构均依赖平台底层标准化服务，企业部署不可或缺：

注意：缺失以上服务，仅能作为演示 Demo，无法投入正式生产。

ZavaShop 案例架构分层对应

第一层（开发层）仓库资源文件

1. .github/agents/zavashop-coding-agent.agent.md：编码智能体配置定义

2. .github/skills/agent-framework-{azure-ai,workflows,agui}-{py,csharp}/：6套标准化智能体技能库

3. workshop/data/：全项目共用静态业务测试数据

4. 各实验目录说明文档 + eval_queries.jsonl：第一层自动化校验测试用例

第二层（运行层）实操产出文件

1. 仓储智能体（Zara）：本地函数工具 + 托管 MCP 工具 + 对话线程能力

2. 采购智能体（Pierre）：公共工具箱 + 业务技能 + 审批权限策略

3. 客服智能体（Aria）：Foundry 全局记忆 + 自动化评测 + 红蓝安全测试

4. 多智能体协同履约流程（Diego）：WorkflowBuilder + 人机审批 + 断点续跑

5. CEO 可视化管控大屏（AG-UI）：覆盖 AG-UI 全部7项核心特性

全架构统一基座模型：Foundry 平台 GPT-5.5 + 文本嵌入模型 text-embedding-3-small。仅修改环境变量，整套资源文件即可切换 Python / C# 双语言运行。

资深智能体工程师三大工作规范

1. 先阅读 SKILL：形成固定工作习惯。编码智能体会自动读取技能库生成代码，人工调试智能体输出时也必须先查阅技能定义；

2. 将工具视作公共 API：命名、入参出参、注释、返回数据结构统一标准化。模型通过工具接口读取业务系统，工具需像常规 API 一样持续迭代重构；

3. 先量化评估，再调优提示词：无量化指标支撑的提示词修改仅为主观感受；配套评测数据的迭代，才是标准化工程实践。

60秒快速启动项目

git clone https://github.com/microsoft/Learn-Microsoft-Agent-Framework-with-Foundry-ZavaShop-Supply-Chain-Workshop cd Learn-Microsoft-Agent-Framework-with-Foundry-ZavaShop-Supply-Chain-Workshop # Foundry prereqs: gpt-5.5 + text-embedding-3-small deployed in your Foundry project az login --use-device-code # Python track python -m venv .venv && source .venv/bin/activate pip install agent-framework agent-framework-azure-ai agent-framework-ag-ui \ azure-identity python-dotenv fastapi "uvicorn[standard]" # .NET track dotnet --version # ≥ 10.0.100 # .env at repo root cat > .env <<EOF FOUNDRY_PROJECT_ENDPOINT=https://<your-project>.services.ai.azure.com/api/projects/<project-name> FOUNDRY_MODEL=gpt-5.5 AZURE_OPENAI_EMBEDDING_MODEL=text-embedding-3-small AGUI_SERVER_URL=http://127.0.0.1:5100/ AG_UI_API_KEY=zava-control-tower-demo-key EOF # In VS Code → Copilot Chat → Agent Mode → pick zavashop-coding-agent # Then say: "I'm working on the inventory agent in Python — meet Mei."

核心工作准则：“先阅读 SKILL。”

总结思考

现代智能体开发分为两大核心分工：编码智能体负责设计与构建；运行时智能体负责线上落地与业务交付。Microsoft Agent Framework 提供统一 SDK，打通两层架构的设计逻辑；Microsoft Foundry 是两层智能体统一发布、运行的底层平台。

而将通用 Copilot 转化为行业专属工程工具、仅靠一句业务需求即可生成可运行、可校验、可部署完整资源文件的核心载体，正是SKILL。一套标准化技能库搭建完成后，后续所有智能体都会复用团队统一的代码规范、测试数据、架构模式与管控标准。

ZavaShop 实战项目是最小可落地端到端示例，完整覆盖两层架构，配套6套开箱即用 Skill 库。完整走通该案例后，当团队询问“企业该如何搭建自研智能体”时，你无需仅提供零散教程，而是能输出一套完整落地架构方案。

👉 在 GitHub 实践这一项目