技术速递|智能体构建智能体:基于 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 包含以下内容:

部分 作用
适用范围与使用场景 "当基于 Foundry / Azure AI 构建智能体时使用本 SKILL,包括 Tools、MCP、Toolbox、Skills、Memory、Threads 等。"
框架最佳实践 如何正确创建 AzureAIAgentClient、注册 Function Tool、配置 HostedMCPTool、创建 Thread 等框架最佳实践。
代码模式 编码智能体参考的代码片段,包括命名方式、Import 顺序、错误处理、类型注解等。
测试数据与数据契约 如何加载 workshop/data/,有哪些数据加载器(如 find_stockfind_po),以及在哪里添加 sys.path
反模式 哪些事情不要做,例如不要硬编码模型名称、不要写内联 Mock 字典、不要绕过数据加载器。
验收启发式规则 如何将 LAB 的验收标准映射为可执行检查,例如 Eval 数据或 Smoke Test。

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

ZavaShop Workshop 中提供的六个 SKILL

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

技术栈 SKILL 用途
🐍 Python agent-framework-azure-ai-py 基于 Foundry 构建单智能体:Tools、MCP、Toolbox、Skills、Memory、Threads
🐍 Python agent-framework-workflows-py 多智能体工作流:WorkflowBuilder、Executors、HITL、Checkpoint
🐍 Python agent-framework-agui-py AG-UI 服务端与客户端:SSE、前后端工具、共享状态、HITL
🟦 .NET agent-framework-azure-ai-csharp Python azure-ai SKILL 的 C# 版本
🟦 .NET agent-framework-workflows-csharp Python workflows SKILL 的 C# 版本
🟦 .NET agent-framework-agui-csharp 基于 ASP.NET Core 的 AG-UI:MapAGUI、AGUIChatClient、HITL
编码智能体如何使用 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 已经定义好了开发模式,因此最终生成的代码会自然地遵循你现有代码库的风格和规范。

plain 复制代码
# 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------它们完全符合团队构建智能体的开发规范。这套交付物也将进入接下来的三个阶段。

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

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

交付物 内容 重要性
源代码 Agent / Workflow 程序 可进行版本管理、代码审查和差异比较
智能体定义 名称、指令、工具列表 智能体的"个性",可独立编辑
工作流 WorkflowBuilder 图 以代码形式实现多智能体编排
Skills 命名并封装好的能力 一次编写,可供多个智能体复用
连接器 MCP Server、Toolbox 注册 智能体与外部世界交互的入口
评估 eval_queries.jsonl 与评估框架 每次 Prompt 修改后的回归测试目标
测试与配置 单元测试、.env Schema、部署清单 保证可复现性
文档 README、运行手册 方便未来维护和运营智能体

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

第五阶段 ------ 验证

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

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

  2. 代码检查与类型检查 ------Python 使用 ruffmypy,.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. 将推理结果流式推送至前端交互渠道

plain 复制代码
# 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],
)

模块三:工具与集成能力(运行时能力载体)

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

能力 运行载体 适用场景
本地函数工具 智能体自身进程 内部计算、数据库查询、本地静态数据查询等轻量化本地代码
MCP 协议工具 独立外部 MCP 服务端 能力归属第三方系统,通过 MCP 标准化协议对外暴露
公共工具箱工具 Foundry 平台项目(服务端、多租户共享) 多智能体共用能力,需统一权限管控与审计
智能体 Skill Foundry 平台项目 多工具 + 权限策略封装为独立命名业务能力单元

落地演进思路:

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

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

模块四:记忆与状态管理

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

对话线程:单次对话内临时上下文状态
plain 复制代码
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 搭建可视化流程,内置人工审批节点,完整留存全链路审计日志。

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

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

平台服务 智能体赋能能力
Microsoft Entra ID 用户 / 智能体身份鉴权;工具调用托管身份认证
微软云防护中心 智能体计算、数据链路全链路威胁检测
Microsoft Sentinel 安全信息事件管理,关联智能体操作与安全告警
Azure 密钥保管库 统一托管密钥、连接字符串、凭证,禁止硬编码 / 提交代码仓库
Azure 监控 / 应用洞察 智能体每一轮推理、每一次工具调用、每一步流程均可观测、检索分析
Azure 策略管控 部署权限、资源访问范围的硬性管控规则

注意:缺失以上服务,仅能作为演示 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秒快速启动项目

plain 复制代码
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 实践这一项目

相关推荐
码农学院1 小时前
微信小程序云开发实战:扫码点餐系统的高并发订单处理与外卖接单架构
微信小程序·架构·notepad++
阿标在干嘛3 小时前
从HTTP到WebSocket:招投标信息实时推送系统的协议选型与架构设计
大数据·微服务·架构
To_OC9 小时前
大模型蒸馏是啥?说白了就是大厨带徒弟的学问
人工智能·llm·agent
Fzuim10 小时前
当 AI 也成为提交者:ThinkFlow 的 Git 提交规范,是怎么定的
git·agent·thinkflow
ALINX技术博客11 小时前
ALINX 亮相 2026 WAIC 世界人工智能大会,展示 AI 视觉 FPGA+GPU 异构计算与电子后视镜解决方案
人工智能·ai·fpga·世界人工智能大会·电子后视镜
JaydenAI11 小时前
[AG-UI详解-01]创建一个类似ChatGPT应用与Agent实时交互
ai·agent·ag-ui·maf
冬奇Lab12 小时前
每日一个开源项目(第164篇):毕昇(BISHENG)- 面向企业的开源 LLM DevOps 平台
人工智能·开源·agent
CCPC不拿奖不改名13 小时前
大模型推理架构与开源生态知识整理
数据库·windows·python·架构·langchain·开源·github
字节跳动开源14 小时前
30 分钟搞定个人情报站:Viking AI 搜索让前沿资讯实时推到面前
数据挖掘·开源·agent