作者卢建晖 - 微软高级云技术布道师排版Alan Wang改变一切的一个关键洞察大多数“如何构建 AI Agent”的教程都会把两项完全不同的工作混在一起构建智能体编写代码、定义工具、评估、打包以及运行智能体规划、推理、调用工具、记住用户信息并交付最终结果。一旦将它们拆分开现代智能体开发就会变成一个清晰的双层架构上层是编码智能体——它负责生产智能体下层是运行时智能体——它才是真正为业务运行的智能体。Microsoft Agent Framework 是连接这两层的 SDK而 Microsoft Foundry 则是这两层共同发布和运行的平台。但真正的秘诀——也是让一个通用 Copilot 变成领域专家工程师的关键——就是SKILL。SKILL 是编码智能体在写下第一行代码之前首先读取的内容。它将需求转化为真正符合你的框架、开发规范和测试数据的交付物。本文将按照最合理的学习顺序完整介绍整个双层架构并将 SKILL 作为第一层的核心内容进行讲解。文中的所有概念都会结合虚构的全球电商公司 ZavaShop 进行说明它拥有 5 个履约中心、数十家供应商而 CEO 希望通过一个实时仪表盘统一管理所有业务。Python和 **.NETC#**均获得完整支持你可以根据团队实际生产环境所使用的语言进行选择。第一层—— 编码智能体构建阶段编码智能体并不是与你的客户直接交互的智能体。它负责构建那个真正与客户交互的智能体。它的输出是一整套交付物包括代码、智能体定义、工作流、Skills、连接器、评测、测试、配置和文档这些内容都会经过验证最终发布到 Microsoft Foundry。整个构建阶段可以分为五个部分。第一阶段 —— 需求与规划在编码智能体写下第一行代码之前你需要先提供三样东西一个真实的业务痛点。不是“我们来做一个智能体”而是“西雅图配送中心的主管 Mei 每天都会因为库存查询被打断 60 次。”一组验收标准。什么才算完成例如“智能体能够回答我们 10 个 SKU 商品目录中的库存问题P95 响应延迟低于 4 秒在评测数据集上的错误工具调用率低于 5%。”它将运行的数据集。使用真实或接近真实的数据例如仓库、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。什么是 SKILLSKILL 是一份结构化契约用来告诉编码智能体如何按照你的框架、编码规范以及业务领域来编写代码。它是整个构建阶段中最重要的文件——没有它GitHub Copilot 只是一个知识广泛的通才有了它它就会变成一位熟悉你业务领域的专家写出的代码就像你的技术负责人亲自完成的一样。从概念上来说一份 SKILL 包含以下内容部分作用适用范围与使用场景“当基于 Foundry / Azure AI 构建智能体时使用本 SKILL包括 Tools、MCP、Toolbox、Skills、Memory、Threads 等。”框架最佳实践如何正确创建 AzureAIAgentClient、注册 Function Tool、配置 HostedMCPTool、创建 Thread 等框架最佳实践。代码模式编码智能体参考的代码片段包括命名方式、Import 顺序、错误处理、类型注解等。测试数据与数据契约如何加载workshop/data/有哪些数据加载器如find_stock、find_po以及在哪里添加sys.path。反模式哪些事情不要做例如不要硬编码模型名称、不要写内联 Mock 字典、不要绕过数据加载器。验收启发式规则如何将 LAB 的验收标准映射为可执行检查例如 Eval 数据或 Smoke Test。SKILL 会与代码库一起进行版本管理。当框架引入新的最佳实践时你只需要更新一次 SKILL之后所有新构建出来的智能体都会自动采用这些新规范。这也是避免团队开发规范逐渐漂移的最重要原因。ZavaShop Workshop 中提供的六个 SKILLWorkshop 提供了六份 SKILL——每种语言各三份——覆盖三个相互独立的能力领域技术栈SKILL用途 Pythonagent-framework-azure-ai-py基于 Foundry 构建单智能体Tools、MCP、Toolbox、Skills、Memory、Threads Pythonagent-framework-workflows-py多智能体工作流WorkflowBuilder、Executors、HITL、Checkpoint Pythonagent-framework-agui-pyAG-UI 服务端与客户端SSE、前后端工具、共享状态、HITL .NETagent-framework-azure-ai-csharpPython azure-ai SKILL 的 C# 版本 .NETagent-framework-workflows-csharpPython workflows SKILL 的 C# 版本 .NETagent-framework-agui-csharp基于 ASP.NET Core 的 AG-UIMapAGUI、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 已经定义好了开发模式因此最终生成的代码会自然地遵循你现有代码库的风格和规范。# 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_endpointos.environ[FOUNDRY_PROJECT_ENDPOINT], model_deployment_nameos.environ[FOUNDRY_MODEL], # gpt-5.5 from env async_credentialDefaultAzureCredential(), ) agent client.create_agent( nameZara, 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( namewarehouse-docs, urlos.environ[WAREHOUSE_DOCS_MCP_URL], ), ], ) thread agent.get_new_thread() print(await agent.run(How many SKU-7421 are at SEA-01?, threadthread))请注意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 修改后的回归测试目标测试与配置单元测试、.envSchema、部署清单保证可复现性文档README、运行手册方便未来维护和运营智能体这里需要区分两种不同含义的“Skill”。SKILL 文件全部大写位于.github/skills/是在构建阶段用于指导编码智能体的而 Agent SkillFoundry 中的概念则是运行时智能体在运行时调用的一项具名能力。这两个名称并非巧合——第一层的 SKILL会生成包括第二层 Agent Skills 在内的多种交付物。第五阶段 —— 验证在任何交付物发布到 Microsoft Foundry 之前都需要通过四道验证关卡测试——包括单元测试和集成测试。例如find_stock(SKU-7421, SEA-01)是否返回测试数据中对应的库存值312代码检查与类型检查——Python 使用ruff和mypy.NET 检查dotnet build的警告信息。模型同样需要理解这些类型签名设计粗糙的类型定义会导致真实的 Bug。评估——运行评测数据集。是否调用了正确的工具回答是否包含预期的信息你需要的是一个可以量化的评分而不是一种“感觉不错”的主观判断。红队测试——使用对抗性输入尝试诱导智能体偏离任务目标或获取其他客户的数据。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 的智能体部署在 TeamsCEO 专属管控大屏是基于 AG-UI 开发的 React 应用。两套前端背后使用编码智能体生成的同一套底层智能体资源文件。模块二运行时智能体本体你反复接触的智能体循环推理流程在本层落地为标准化架构实体AI 智能体 大模型 系统指令集 工具集 对话线程推理循环完整流程大模型规划任务、逻辑推演确定下一步执行动作通过 MCP 协议、工具工具箱或本地函数调用外部能力读写持久化记忆库将推理结果流式推送至前端交互渠道# Python — the runtime shape (exactly what the Coding Agent produced) agent client.create_agent( nameZara, instructionsYou are Zara, the warehouse assistant for Seattle DC., tools[stock_lookup, po_lookup, warehouse_docs_mcp], )模块三工具与集成能力运行时能力载体运行阶段智能体通过四类能力对接外部系统选型需结合工程场景综合判断能力运行载体适用场景本地函数工具智能体自身进程内部计算、数据库查询、本地静态数据查询等轻量化本地代码MCP 协议工具独立外部 MCP 服务端能力归属第三方系统通过 MCP 标准化协议对外暴露公共工具箱工具Foundry 平台项目服务端、多租户共享多智能体共用能力需统一权限管控与审计智能体 SkillFoundry 平台项目多工具 权限策略封装为独立命名业务能力单元落地演进思路初期可直接使用本地函数工具一旦第二个智能体需要复用同一业务能力立即迁移至公共工具箱统一管理。ZavaShop 业务示例。本地静态库存数据查询 → 本地函数工具。仓储操作手册文档检索 → MCP 协议工具。采购、履约、财务多部门共用供应商门户连接器 → 公共工具箱工具。“依据合同校验采购单”完整业务流程 → 封装为独立智能体 Skill。模块四记忆与状态管理运行时分为两类状态数据对话线程单次对话内临时上下文状态thread agent.get_new_thread() await agent.run(Look up PO-1043., threadthread) await agent.run(And its supplier?, threadthread) # knows which PO全局记忆跨多轮对话持久化状态Foundry 记忆库存储用户长期稳定业务信息客户 VIP 等级、包装偏好、收货时段等仅留存固定业务事实与偏好不存储完整聊天记录。ZavaShop 业务示例。客服智能体 Aria 可跨会话记住客户 C-204 为 VIP、拒绝纸箱包装、偏好 18:00–20:00 送货。模块五执行与输出生产级智能体执行操作会变更业务状态并产出可供其他系统消费的结果触发事件启动自动化工作流、推送人工预警生成业务单据创建采购单、草拟邮件、写入业务数据库渠道消息推送回传 Teams 消息、更新可视化面板、调用外部 Webhook全链路可观测所有操作日志实时推送至应用洞察 / Azure 监控平台。工作流编排能力同样部署在本层WorkflowBuilder 是智能体框架原生流程编排核心组件三大核心能力能力复用开发阶段定义的工具运行时直接作为流程节点无需重复开发人机协同HITL流程可暂停、推送人工审批审批完成后从暂停节点继续执行断点续跑服务重启后工作流可从最近检查点恢复执行。ZavaShop 业务示例。履约总监 Diego 团队每日处理上万美金级异常订单。优化前跨5个部门邮件来回沟通优化后基于 WorkflowBuilder 搭建可视化流程内置人工审批节点完整留存全链路审计日志。跨层公共支撑企业级安全共享服务两层架构均依赖平台底层标准化服务企业部署不可或缺平台服务智能体赋能能力Microsoft Entra ID用户 / 智能体身份鉴权工具调用托管身份认证微软云防护中心智能体计算、数据链路全链路威胁检测Microsoft Sentinel安全信息事件管理关联智能体操作与安全告警Azure 密钥保管库统一托管密钥、连接字符串、凭证禁止硬编码 / 提交代码仓库Azure 监控 / 应用洞察智能体每一轮推理、每一次工具调用、每一步流程均可观测、检索分析Azure 策略管控部署权限、资源访问范围的硬性管控规则注意缺失以上服务仅能作为演示 Demo无法投入正式生产。ZavaShop 案例架构分层对应第一层开发层仓库资源文件.github/agents/zavashop-coding-agent.agent.md编码智能体配置定义.github/skills/agent-framework-{azure-ai,workflows,agui}-{py,csharp}/6套标准化智能体技能库workshop/data/全项目共用静态业务测试数据各实验目录说明文档 eval_queries.jsonl第一层自动化校验测试用例第二层运行层实操产出文件仓储智能体Zara本地函数工具 托管 MCP 工具 对话线程能力采购智能体Pierre公共工具箱 业务技能 审批权限策略客服智能体AriaFoundry 全局记忆 自动化评测 红蓝安全测试多智能体协同履约流程DiegoWorkflowBuilder 人机审批 断点续跑CEO 可视化管控大屏AG-UI覆盖 AG-UI 全部7项核心特性全架构统一基座模型Foundry 平台 GPT-5.5 文本嵌入模型 text-embedding-3-small。仅修改环境变量整套资源文件即可切换 Python / C# 双语言运行。资深智能体工程师三大工作规范先阅读 SKILL形成固定工作习惯。编码智能体会自动读取技能库生成代码人工调试智能体输出时也必须先查阅技能定义将工具视作公共 API命名、入参出参、注释、返回数据结构统一标准化。模型通过工具接口读取业务系统工具需像常规 API 一样持续迭代重构先量化评估再调优提示词无量化指标支撑的提示词修改仅为主观感受配套评测数据的迭代才是标准化工程实践。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_ENDPOINThttps://your-project.services.ai.azure.com/api/projects/project-name FOUNDRY_MODELgpt-5.5 AZURE_OPENAI_EMBEDDING_MODELtext-embedding-3-small AGUI_SERVER_URLhttp://127.0.0.1:5100/ AG_UI_API_KEYzava-control-tower-demo-key EOF # In VS Code → Copilot Chat → Agent Mode → pick zavashop-coding-agent # Then say: Im working on the inventory agent in Python — meet Mei.核心工作准则“先阅读 SKILL。”总结思考现代智能体开发分为两大核心分工编码智能体负责设计与构建运行时智能体负责线上落地与业务交付。Microsoft Agent Framework 提供统一 SDK打通两层架构的设计逻辑Microsoft Foundry 是两层智能体统一发布、运行的底层平台。而将通用 Copilot 转化为行业专属工程工具、仅靠一句业务需求即可生成可运行、可校验、可部署完整资源文件的核心载体正是SKILL。一套标准化技能库搭建完成后后续所有智能体都会复用团队统一的代码规范、测试数据、架构模式与管控标准。ZavaShop 实战项目是最小可落地端到端示例完整覆盖两层架构配套6套开箱即用 Skill 库。完整走通该案例后当团队询问“企业该如何搭建自研智能体”时你无需仅提供零散教程而是能输出一套完整落地架构方案。 在 GitHub 实践这一项目
技术速递｜智能体构建智能体：基于 Microsoft Agent Framework 与 Foundry 的 Skill 优先架构蓝图
作者卢建晖 - 微软高级云技术布道师排版Alan Wang改变一切的一个关键洞察大多数“如何构建 AI Agent”的教程都会把两项完全不同的工作混在一起构建智能体编写代码、定义工具、评估、打包以及运行智能体规划、推理、调用工具、记住用户信息并交付最终结果。一旦将它们拆分开现代智能体开发就会变成一个清晰的双层架构上层是编码智能体——它负责生产智能体下层是运行时智能体——它才是真正为业务运行的智能体。Microsoft Agent Framework 是连接这两层的 SDK而 Microsoft Foundry 则是这两层共同发布和运行的平台。但真正的秘诀——也是让一个通用 Copilot 变成领域专家工程师的关键——就是SKILL。SKILL 是编码智能体在写下第一行代码之前首先读取的内容。它将需求转化为真正符合你的框架、开发规范和测试数据的交付物。本文将按照最合理的学习顺序完整介绍整个双层架构并将 SKILL 作为第一层的核心内容进行讲解。文中的所有概念都会结合虚构的全球电商公司 ZavaShop 进行说明它拥有 5 个履约中心、数十家供应商而 CEO 希望通过一个实时仪表盘统一管理所有业务。Python和 **.NETC#**均获得完整支持你可以根据团队实际生产环境所使用的语言进行选择。第一层—— 编码智能体构建阶段编码智能体并不是与你的客户直接交互的智能体。它负责构建那个真正与客户交互的智能体。它的输出是一整套交付物包括代码、智能体定义、工作流、Skills、连接器、评测、测试、配置和文档这些内容都会经过验证最终发布到 Microsoft Foundry。整个构建阶段可以分为五个部分。第一阶段 —— 需求与规划在编码智能体写下第一行代码之前你需要先提供三样东西一个真实的业务痛点。不是“我们来做一个智能体”而是“西雅图配送中心的主管 Mei 每天都会因为库存查询被打断 60 次。”一组验收标准。什么才算完成例如“智能体能够回答我们 10 个 SKU 商品目录中的库存问题P95 响应延迟低于 4 秒在评测数据集上的错误工具调用率低于 5%。”它将运行的数据集。使用真实或接近真实的数据例如仓库、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。什么是 SKILLSKILL 是一份结构化契约用来告诉编码智能体如何按照你的框架、编码规范以及业务领域来编写代码。它是整个构建阶段中最重要的文件——没有它GitHub Copilot 只是一个知识广泛的通才有了它它就会变成一位熟悉你业务领域的专家写出的代码就像你的技术负责人亲自完成的一样。从概念上来说一份 SKILL 包含以下内容部分作用适用范围与使用场景“当基于 Foundry / Azure AI 构建智能体时使用本 SKILL包括 Tools、MCP、Toolbox、Skills、Memory、Threads 等。”框架最佳实践如何正确创建 AzureAIAgentClient、注册 Function Tool、配置 HostedMCPTool、创建 Thread 等框架最佳实践。代码模式编码智能体参考的代码片段包括命名方式、Import 顺序、错误处理、类型注解等。测试数据与数据契约如何加载workshop/data/有哪些数据加载器如find_stock、find_po以及在哪里添加sys.path。反模式哪些事情不要做例如不要硬编码模型名称、不要写内联 Mock 字典、不要绕过数据加载器。验收启发式规则如何将 LAB 的验收标准映射为可执行检查例如 Eval 数据或 Smoke Test。SKILL 会与代码库一起进行版本管理。当框架引入新的最佳实践时你只需要更新一次 SKILL之后所有新构建出来的智能体都会自动采用这些新规范。这也是避免团队开发规范逐渐漂移的最重要原因。ZavaShop Workshop 中提供的六个 SKILLWorkshop 提供了六份 SKILL——每种语言各三份——覆盖三个相互独立的能力领域技术栈SKILL用途 Pythonagent-framework-azure-ai-py基于 Foundry 构建单智能体Tools、MCP、Toolbox、Skills、Memory、Threads Pythonagent-framework-workflows-py多智能体工作流WorkflowBuilder、Executors、HITL、Checkpoint Pythonagent-framework-agui-pyAG-UI 服务端与客户端SSE、前后端工具、共享状态、HITL .NETagent-framework-azure-ai-csharpPython azure-ai SKILL 的 C# 版本 .NETagent-framework-workflows-csharpPython workflows SKILL 的 C# 版本 .NETagent-framework-agui-csharp基于 ASP.NET Core 的 AG-UIMapAGUI、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 已经定义好了开发模式因此最终生成的代码会自然地遵循你现有代码库的风格和规范。# 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_endpointos.environ[FOUNDRY_PROJECT_ENDPOINT], model_deployment_nameos.environ[FOUNDRY_MODEL], # gpt-5.5 from env async_credentialDefaultAzureCredential(), ) agent client.create_agent( nameZara, 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( namewarehouse-docs, urlos.environ[WAREHOUSE_DOCS_MCP_URL], ), ], ) thread agent.get_new_thread() print(await agent.run(How many SKU-7421 are at SEA-01?, threadthread))请注意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 修改后的回归测试目标测试与配置单元测试、.envSchema、部署清单保证可复现性文档README、运行手册方便未来维护和运营智能体这里需要区分两种不同含义的“Skill”。SKILL 文件全部大写位于.github/skills/是在构建阶段用于指导编码智能体的而 Agent SkillFoundry 中的概念则是运行时智能体在运行时调用的一项具名能力。这两个名称并非巧合——第一层的 SKILL会生成包括第二层 Agent Skills 在内的多种交付物。第五阶段 —— 验证在任何交付物发布到 Microsoft Foundry 之前都需要通过四道验证关卡测试——包括单元测试和集成测试。例如find_stock(SKU-7421, SEA-01)是否返回测试数据中对应的库存值312代码检查与类型检查——Python 使用ruff和mypy.NET 检查dotnet build的警告信息。模型同样需要理解这些类型签名设计粗糙的类型定义会导致真实的 Bug。评估——运行评测数据集。是否调用了正确的工具回答是否包含预期的信息你需要的是一个可以量化的评分而不是一种“感觉不错”的主观判断。红队测试——使用对抗性输入尝试诱导智能体偏离任务目标或获取其他客户的数据。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 的智能体部署在 TeamsCEO 专属管控大屏是基于 AG-UI 开发的 React 应用。两套前端背后使用编码智能体生成的同一套底层智能体资源文件。模块二运行时智能体本体你反复接触的智能体循环推理流程在本层落地为标准化架构实体AI 智能体 大模型 系统指令集 工具集 对话线程推理循环完整流程大模型规划任务、逻辑推演确定下一步执行动作通过 MCP 协议、工具工具箱或本地函数调用外部能力读写持久化记忆库将推理结果流式推送至前端交互渠道# Python — the runtime shape (exactly what the Coding Agent produced) agent client.create_agent( nameZara, instructionsYou are Zara, the warehouse assistant for Seattle DC., tools[stock_lookup, po_lookup, warehouse_docs_mcp], )模块三工具与集成能力运行时能力载体运行阶段智能体通过四类能力对接外部系统选型需结合工程场景综合判断能力运行载体适用场景本地函数工具智能体自身进程内部计算、数据库查询、本地静态数据查询等轻量化本地代码MCP 协议工具独立外部 MCP 服务端能力归属第三方系统通过 MCP 标准化协议对外暴露公共工具箱工具Foundry 平台项目服务端、多租户共享多智能体共用能力需统一权限管控与审计智能体 SkillFoundry 平台项目多工具 权限策略封装为独立命名业务能力单元落地演进思路初期可直接使用本地函数工具一旦第二个智能体需要复用同一业务能力立即迁移至公共工具箱统一管理。ZavaShop 业务示例。本地静态库存数据查询 → 本地函数工具。仓储操作手册文档检索 → MCP 协议工具。采购、履约、财务多部门共用供应商门户连接器 → 公共工具箱工具。“依据合同校验采购单”完整业务流程 → 封装为独立智能体 Skill。模块四记忆与状态管理运行时分为两类状态数据对话线程单次对话内临时上下文状态thread agent.get_new_thread() await agent.run(Look up PO-1043., threadthread) await agent.run(And its supplier?, threadthread) # knows which PO全局记忆跨多轮对话持久化状态Foundry 记忆库存储用户长期稳定业务信息客户 VIP 等级、包装偏好、收货时段等仅留存固定业务事实与偏好不存储完整聊天记录。ZavaShop 业务示例。客服智能体 Aria 可跨会话记住客户 C-204 为 VIP、拒绝纸箱包装、偏好 18:00–20:00 送货。模块五执行与输出生产级智能体执行操作会变更业务状态并产出可供其他系统消费的结果触发事件启动自动化工作流、推送人工预警生成业务单据创建采购单、草拟邮件、写入业务数据库渠道消息推送回传 Teams 消息、更新可视化面板、调用外部 Webhook全链路可观测所有操作日志实时推送至应用洞察 / Azure 监控平台。工作流编排能力同样部署在本层WorkflowBuilder 是智能体框架原生流程编排核心组件三大核心能力能力复用开发阶段定义的工具运行时直接作为流程节点无需重复开发人机协同HITL流程可暂停、推送人工审批审批完成后从暂停节点继续执行断点续跑服务重启后工作流可从最近检查点恢复执行。ZavaShop 业务示例。履约总监 Diego 团队每日处理上万美金级异常订单。优化前跨5个部门邮件来回沟通优化后基于 WorkflowBuilder 搭建可视化流程内置人工审批节点完整留存全链路审计日志。跨层公共支撑企业级安全共享服务两层架构均依赖平台底层标准化服务企业部署不可或缺平台服务智能体赋能能力Microsoft Entra ID用户 / 智能体身份鉴权工具调用托管身份认证微软云防护中心智能体计算、数据链路全链路威胁检测Microsoft Sentinel安全信息事件管理关联智能体操作与安全告警Azure 密钥保管库统一托管密钥、连接字符串、凭证禁止硬编码 / 提交代码仓库Azure 监控 / 应用洞察智能体每一轮推理、每一次工具调用、每一步流程均可观测、检索分析Azure 策略管控部署权限、资源访问范围的硬性管控规则注意缺失以上服务仅能作为演示 Demo无法投入正式生产。ZavaShop 案例架构分层对应第一层开发层仓库资源文件.github/agents/zavashop-coding-agent.agent.md编码智能体配置定义.github/skills/agent-framework-{azure-ai,workflows,agui}-{py,csharp}/6套标准化智能体技能库workshop/data/全项目共用静态业务测试数据各实验目录说明文档 eval_queries.jsonl第一层自动化校验测试用例第二层运行层实操产出文件仓储智能体Zara本地函数工具 托管 MCP 工具 对话线程能力采购智能体Pierre公共工具箱 业务技能 审批权限策略客服智能体AriaFoundry 全局记忆 自动化评测 红蓝安全测试多智能体协同履约流程DiegoWorkflowBuilder 人机审批 断点续跑CEO 可视化管控大屏AG-UI覆盖 AG-UI 全部7项核心特性全架构统一基座模型Foundry 平台 GPT-5.5 文本嵌入模型 text-embedding-3-small。仅修改环境变量整套资源文件即可切换 Python / C# 双语言运行。资深智能体工程师三大工作规范先阅读 SKILL形成固定工作习惯。编码智能体会自动读取技能库生成代码人工调试智能体输出时也必须先查阅技能定义将工具视作公共 API命名、入参出参、注释、返回数据结构统一标准化。模型通过工具接口读取业务系统工具需像常规 API 一样持续迭代重构先量化评估再调优提示词无量化指标支撑的提示词修改仅为主观感受配套评测数据的迭代才是标准化工程实践。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_ENDPOINThttps://your-project.services.ai.azure.com/api/projects/project-name FOUNDRY_MODELgpt-5.5 AZURE_OPENAI_EMBEDDING_MODELtext-embedding-3-small AGUI_SERVER_URLhttp://127.0.0.1:5100/ AG_UI_API_KEYzava-control-tower-demo-key EOF # In VS Code → Copilot Chat → Agent Mode → pick zavashop-coding-agent # Then say: Im working on the inventory agent in Python — meet Mei.核心工作准则“先阅读 SKILL。”总结思考现代智能体开发分为两大核心分工编码智能体负责设计与构建运行时智能体负责线上落地与业务交付。Microsoft Agent Framework 提供统一 SDK打通两层架构的设计逻辑Microsoft Foundry 是两层智能体统一发布、运行的底层平台。而将通用 Copilot 转化为行业专属工程工具、仅靠一句业务需求即可生成可运行、可校验、可部署完整资源文件的核心载体正是SKILL。一套标准化技能库搭建完成后后续所有智能体都会复用团队统一的代码规范、测试数据、架构模式与管控标准。ZavaShop 实战项目是最小可落地端到端示例完整覆盖两层架构配套6套开箱即用 Skill 库。完整走通该案例后当团队询问“企业该如何搭建自研智能体”时你无需仅提供零散教程而是能输出一套完整落地架构方案。 在 GitHub 实践这一项目
