在 Microsoft Foundry 上构建、部署、评估…

当任务涉及 Microsoft Foundry 的模型部署、agent 开发生命周期、评估优化、微调、CI/CD、配额/RBAC 或网络隔离时使用。

适用场景

解决思路

1. 技能加载后第一步：从 skill 根目录运行依赖检查与安装脚本；macOS/Linux 用 ./scripts/check-and-setup-dependencies.sh，Windows 用 ./scripts/check-and-setup-dependencies.ps1（pwsh）；等待完成；脚本先检查只安装缺失依赖，不重装已有依赖；严格按脚本输出继续。
2. 执行任何工作流特定步骤前，必须读取对应子技能文档；未读就不调用该工作流特定 MCP 工具，即使已知参数；每个新用户消息触发不同工作流时都要遵守。
3. 使用 Foundry MCP 操作前，调用 Azure MCP 的 foundry 工具，检查可用 Foundry MCP 工具和相关参数，作为发现/帮助步骤。
4. 执行任何 azd 命令前，必须先读 foundry-agent/azd-guidance/azd-guidance.md，并严格遵循共享规则，尤其 AZURE_DEV_USER_AGENT 设置规则。
5. 匹配到 deploy 子技能时，读取 foundry-agent/deploy/deploy.md，按流程部署 hosted agents 到 Foundry、冒烟测试部署、创建/更新 prompt agents、管理 agent 版本和多环境部署。
6. 匹配到 cicd 子技能时，读取 foundry-agent/cicd/cicd.md，为 Foundry agent 设置 CI/CD 部署流水线。
7. 匹配到 invoke 子技能时，读取 foundry-agent/invoke/invoke.md，向 agent 发送消息，进行单轮或多轮对话。
8. 匹配到 routine 子技能时，读取 foundry-agent/routine/routine.md，用 routines 调度或事件触发 Foundry agents；用 azd 做 CRUD、启用/禁用、手动 dispatch、查看历史运行，或在 azure.yaml 中定义 routines。
9. 匹配到 invocations-ws 子技能时，读取 foundry-agent/invocations-ws/invocations-ws.md，构建、部署和连接使用 invocations_ws 双工 WebSocket 协议的 hosted agents，适用于语音 agent、实时流和带外媒体传输信令。
10. 匹配到 observe 子技能时，读取 foundry-agent/observe/observe.md，评估 agent 质量、运行 batch evals、分析失败、优化 prompts、改进 agent instructions、比较版本、设置 CI/CD 监控、启用生产持续评估。
11. 匹配到 insights 子技能时，读取 foundry-agent/insights/insights.md，从已有 monitor 拉取生成的 agent insights、证据和建议；只读检索，不发起新分析。
12. 匹配到 trace 子技能时，读取 foundry-agent/trace/trace.md，查询 traces、分析延迟/失败、通过 App Insights customEvents 将 eval 结果关联到具体响应。
13. 匹配到 troubleshoot 子技能时，读取 foundry-agent/troubleshoot/troubleshoot.md，查看 hosted agent 日志、查询遥测、诊断失败。
14. validate 子技能仅当用户明确要求使用该验证子技能，或明确要求按最佳实践验证 Microsoft Foundry hosted-agent 代码时才读取 foundry-agent/validate/validate.md；绝不主动调用或加入其他工作流。
15. 创建全新 hosted Foundry agent 端到端时，读取 foundry-agent/create/quick-start-hosted.md，执行脚手架、供应或使用现有 Foundry project、部署、冒烟测试；不要用于已有代码工作；quickstart 未覆盖的内容转用 create。
16. 当标准端到端 happy path（quick start）不适用时，读取 foundry-agent/create/create-hosted.md；用于创建新 Foundry agent、更新现有 agent 代码、继续开发现有 agent、在 scaffold 时连接连接、使用高级设置或 A2A（Agent2Agent），或从失败 quickstart 恢复。
17. 匹配到 agent-optimizer 时，读取 foundry-agent/agent-optimizer/agent-optimizer.md，让现有 Python hosted-agent 代码可优化、配置 eval.yaml、运行 Agent Optimizer 作业、本地应用候选，并在审查后通过 azd 部署。
18. 匹配到 eval-datasets 时，读取 foundry-agent/eval-datasets/eval-datasets.md，从生产 traces 收集评估数据集、管理数据集版本和拆分、跟踪评估指标随时间变化、检测回归、维护从 trace 到部署的完整 lineage。
19. 创建新 Microsoft Foundry project 以托管 agents 和 models 时，读取 project/create/create-foundry-project.md；用于 onboarding 到 Foundry 或搭建新基础设施。
20. 使用 Azure CLI 创建 Azure AI Services multi-service resource（Foundry resource）时，读取 resource/create/create-foundry-resource.md；用于手动供应并细粒度控制 AI Services 资源。
21. 回答 Foundry 网络隔离问题或部署 VNet 隔离 Foundry（BYO VNet、Managed VNet、hybrid）时，读取 resource/private-network/private-network.md；覆盖架构概念、模板选择、部署、部署后验证。
22. 进行统一模型部署并需要智能路由时，读取 models/deploy-model/SKILL.md；处理快速预设部署、完全自定义部署（version/SKU/capacity/RAI）、跨区域容量发现；按情况路由到 preset、customize、capacity 子技能。
23. 管理 Microsoft Foundry 资源配额和容量、检查配额用量、排查因配额不足导致的部署失败、请求配额增加或规划容量时，读取 quota/quota.md。
24. 管理 Microsoft Foundry 资源 RBAC 权限、角色分配、托管身份和服务主体；用于访问控制、审计权限和 CI/CD 设置时，读取 rbac/rbac.md。
25. 在 Microsoft Foundry 上微调模型（SFT distillation、DPO preference optimization、RFT with graders 和 tool calling）时，读取 finetuning/SKILL.md；执行数据集准备、grader 校准、训练、检查点选择、部署、评估。
26. 任何 azd 相关 Foundry agent 工作流先读取 foundry-agent/azd-guidance/azd-guidance.md，获取共享 azd 知识和指导。
27. 可选 onboarding 流程：project/create（public）或 private-network（VNet isolation）→ models/deploy-model → agent workflows（create → deploy → invoke）。
28. 对所有模型定制使用 finetuning：SFT distillation、DPO preference optimization、RFT with graders；包含 quickstart、grader calibration、training curve analysis。
29. 对所有模型部署场景使用 models/deploy-model，让它在快速 preset 部署、完全控制的自定义部署、跨区域容量发现间智能路由。
30. 对 optimize my prompt 或 improve my agent instructions 请求，加载 observe 并通过该 eval-driven 工作流使用 prompt_optimize MCP 工具。
31. 基础设施生命周期：当用户意图 Create Foundry 或 Set up Foundry 含糊时，用 AskUserQuestion 询问：(a) 仅 AI Services 资源，(b) 公共访问 project，(c) 网络隔离 project；路由 (a)→resource/create/create-foundry-resource.md，(b)→project/create/create-foundry-project.md，(c)→resource/private-network/private-network.md。
32. 设置 Foundry 并需要 VNet 隔离时，走 resource/private-network/private-network.md。
33. 创建 Foundry project（公共）时，走 project/create/create-foundry-project.md。
34. 创建裸 Foundry resource 时，走 resource/create/create-foundry-resource.md。
35. Agent 开发生命周期：创建新 hosted agent 端到端（scaffold + deploy + test）按顺序执行 dependency check and setup → azd-guidance → quick-start-hosted（自包含端到端）。
36. 超出标准 quickstart（现有代码、迁移、re-hosting、部署自定义、scaffold 时连接、A2A、恢复）按顺序执行 dependency check and setup → azd-guidance → create → deploy → invoke。
37. 优化现有 Python hosted agent 按顺序执行 dependency check and setup → azd-guidance → agent-optimizer → scaffold/review → eval.yaml → optimize → apply candidate → deploy → invoke。
38. 部署 agent（代码已存在）按顺序执行 dependency check and setup → azd-guidance → deploy（含 eval-suite 设置）→ invoke → observe（评估/优化）。
39. 代码变更后更新/重新部署 agent 按顺序执行 dependency check and setup → azd-guidance → deploy（含 eval-suite 设置）→ invoke → observe（评估/优化）。
40. 为 hosted agent 设置 CI/CD 部署流水线按顺序执行 dependency check and setup → azd-guidance → cicd。
41. 调用/测试/与 agent 聊天按顺序执行 dependency check and setup → azd-guidance → invoke。
42. 调度/事件触发 agent，或对 routine 做 CRUD/启用/禁用/dispatch 按顺序执行 dependency check and setup → azd-guidance → routine。
43. 优化/改进 agent prompt 或 instructions 时，走 observe 的 Step 4: Optimize。
44. 评估和优化 agent（完整循环）时，走 observe。
45. 启用持续评估监控时，走 observe 的 Step 6: CI/CD & Monitoring。
46. 拉取 agent insights 或列出生成的问题和建议时，执行 dependency check and setup → insights（所有页面含扩展证据；只读）。
47. 排查 agent 问题时，执行 dependency check and setup → azd-guidance → invoke → troubleshoot。
48. 修复损坏 agent（troubleshoot + redeploy）时，执行 dependency check and setup → azd-guidance → invoke → troubleshoot → 应用修复 → deploy → invoke。
49. .foundry workspace：每个 agent 源文件夹可在 .foundry/ 下保留 Foundry 特定缓存和 overlay 状态，结构包含 agent-metadata.yaml、agent-metadata.prod.yaml、suites/、datasets/、evaluators/、results/。
50. 在 azd 项目中，从 azure.yaml 加 azd env get-values 派生部署上下文（project endpoint、agent name/version、ACR、App Insights）；当 azd 已提供时不要在 metadata 中重复这些值。
51. agent-metadata.yaml 是本地/开发 overlay 首选，用于非 azd 值、远程 Foundry suite 引用、本地缓存路径、结果摘要和显式覆盖；可选 sidecar（如 agent-metadata.prod.yaml）可保存单个 prod 或 CI-targeted overlay，不要在一个文件中混合多环境。
52. suites/、datasets/、evaluators/ 是本地缓存文件夹；当前则复用，刷新或覆盖前先询问。
53. 参见 references/agent-metadata-contract.md 获取 canonical schema 和工作流规则。
54. 生产工作负载需要数据驻留控制（通过 Foundry capability host 自带 Cosmos DB / Storage / AI Search）时，使用 Standard Agent Setup（references/standard-agent-setup.md）；默认 azd ai agent 流程使用 Basic Agent Setup，且不 provision capabilityHosts/agents，不要将其缺失标记为 bug；默认 post-provision 状态见 foundry-agent/create/create-hosted.md 的 Expected env-var fingerprint。
55. 公共项目上下文解析只在需要且未知配置值时运行；若值（agent root、environment、project endpoint、agent name）已从用户消息或同会话先前技能得知，跳过该值解析。
56. Step 1 发现 agent roots 和 azd 上下文：检查 workspace 是否有 azure.yaml 且 services 使用 host: azure.ai.agent；一个 azd agent 服务则用其 project 文件夹作为 agent root；多个则要求用户选择目标服务/文件夹；没有 azd agent 服务则搜索 workspace 中 .foundry/ 文件夹含 agent-metadata.yaml 或 agent-metadata.<env>.yaml；一个匹配则用；多个要求用户选择；无匹配时，insights 只询问缺失远程输入而不初始化本地文件，create/deploy 在 setup 时新建 .foundry/ 文件夹，其他工作流停止并询问要初始化哪个 agent 源文件夹。
57. 选定 agent root 后，所有本地 .foundry 缓存检查、源代码检查、评估器建议、数据集建议、prompt 优化上下文都只在该文件夹内进行；除非用户显式切换 roots，不要扫描兄弟 agent 文件夹。
58. Step 2 解析环境和部署上下文：若 azure.yaml 存在，按顺序解析 azd 环境：用户明确命名的环境；azd env get-values 的 AZURE_ENV_NAME；.azure/config.json 中 azd 默认环境；会话中已选环境。若 project/deployment 值未知，对选中环境运行 azd env get-values。优先使用 azd 值：AZURE_AI_PROJECT_ENDPOINT 或 AZURE_AIPROJECT_ENDPOINT 解析 project endpoint；AGENT_<SERVICE>_NAME 解析 agent name；AGENT_<SERVICE>_VERSION 解析 agent version；AZURE_CONTAINER_REGISTRY_NAME 或 AZURE_CONTAINER_REGISTRY_ENDPOINT 解析 ACR registry name/image URL prefix；APPLICATIONINSIGHTS_CONNECTION_STRING 解析 App Insights connection string 用于 trace 工作流；AZURE_SUBSCRIPTION_ID、AZURE_RESOURCE_GROUP、AZURE_AI_ACCOUNT_NAME、AZURE_AI_PROJECT_NAME 用于 Azure 资源查找和 Playground 链接。azd 提供时作为真相来源，metadata 写入时不要复制这些值。
59. Step 3 选择 metadata overlay 并解析环境：在选定 agent root 内按顺序选 metadata 文件：用户或工作流明确提供的文件名/路径；若已知显式环境且 .foundry/agent-metadata.<env>.yaml 存在则用该文件；.foundry/agent-metadata.yaml；若仍多个且无规则选中则提示用户选择。读取后按顺序解析环境：用户明确命名；若选中 metadata 文件只定义一个环境则用；会话中已选；metadata 的 defaultEnvironment。若仍多环境且无规则选中则提示用户选择。每个工作流摘要中保持 agent root、metadata 文件、环境、上下文来自 azd 还是 metadata 可见。若环境有旧 testSuites[] 但无 evaluationSuites[]，以 testSuites[] 为本次来源，在内存规范化为 evaluationSuites[] 形状；若更旧只有 legacy testCases[]，同样规范化。保留 dataset 和 evaluator 字段，保留已有 tags，仅在 tags.tier 缺失时将 legacy priority 映射：P0→smoke、P1→regression、P2→coverage。
60. Step 4 解析 eval.yaml 本地评估意图：若选定 agent root 有 eval.yaml，在生成新 suites 前解析：agent.name 为目标 agent 候选，使用前验证匹配选定 azd/metadata agent；dataset.local_uri 为本地种子数据集候选，legacy dataset_file 可在内存规范化；dataset.name/dataset.version 为注册数据集候选；validation_dataset 为可选验证数据集候选；evaluators[] 为候选 Foundry evaluator 名称，用 evaluator_catalog_get 验证后再视为远程 evaluator；name 为本地 eval/suite 候选，远程验证后再持久化为 suiteName；options.eval_model、options.optimization_model、options.max_candidates、options.optimization_config.model_search_space、options.pass_threshold、max_samples、trace_days、generation_instruction 为设置默认值。将 eval.yaml 视为本地评估意图，不证明 Foundry suite 存在；只在远程查找或注册成功后把同步的 suite/dataset/evaluator 引用持久化到 .foundry。
61. Step 5 解析公共配置：按顺序分层来源：显式用户输入和会话中已选值；azd 环境值用于部署上下文；.foundry/agent-metadata*.yaml overlay 值和远程 suite/cache 引用；azure.yaml 和 eval.yaml 本地源配置；仍缺则询问用户。若 azd 和 metadata 提供同一值且不同，停止并问哪个来源权威；若相同，用 azd 值，未来 metadata 写入避免重写重复。有效值首选来源：project endpoint 用 azd env，供 deploy/invoke/observe/trace/troubleshoot；agent name/version 用 azd agent 变量然后 azure.yaml，供 invoke/observe/trace/troubleshoot；ACR 用 azd env，供 deploy；evaluation suites 和 cache paths 用 .foundry/agent-metadata*.yaml，供 observe/eval-datasets；本地种子 dataset/evaluator intent 用 eval.yaml，供 observe/eval-datasets。
62. Step 6 写 metadata overlay（仅 create/deploy/observe）：任何 metadata 写入（deploy、auto-setup、dataset refresh、trace-to-dataset update）只把不可派生 overlay/cache 状态持久化到选中 metadata 文件：azd 绑定（azd.environmentName、azd.service）在有用时；evaluationSuites[] 含远程 suite/dataset/evaluator 引用和本地缓存路径；lastEval、结果文件、比较摘要或显式非 azd 覆盖。azd 已提供部署值时，不要把 azd-owned 值复制到 metadata。若选中文件是首选单环境文件，只重写该环境块；若选中文件是 legacy 多环境文件，只重写选中环境块。永不自动复制或合并兄弟 metadata 文件中的环境。若选中环境仍用旧 testSuites[] 或 legacy testCases[]，重写为 evaluationSuites[]，并从重写条目中删除迁移的 priority 字段。
63. Step 7 收集缺失值：仅对未从用户消息、会话上下文、metadata 或 azd bootstrap 解析的值，使用 ask_user 或 askQuestions 工具。常见值：agent root（目标 azd 服务项目文件夹或含 .foundry/agent-metadata*.yaml 的文件夹）、metadata 文件（本地/开发用 agent-metadata.yaml，或显式 sidecar 如 agent-metadata.prod.yaml）、environment（azd 环境、dev、prod 或 metadata 中其他环境键）、project endpoint（Microsoft Foundry project endpoint URL）、agent name（目标 agent 名称）。若用户已提供 agent path、environment、project endpoint 或 agent name，直接提取，不要再次询问。
64. Agent 类型：Prompt 类型为 prompt，是由模型部署支撑的 LLM-based agents；Hosted 类型为 hosted，是运行自定义代码的容器化 agents。将 azure.yaml 服务含 host: azure.ai.agent 视为 Hosted。仅当无法从项目上下文解析类型时用 agent_get。
65. 工具使用约定：从用户收集信息时用 ask_user 或 askQuestions；将长时或独立子任务（如 env var 扫描、状态轮询、Dockerfile 生成）委托给 task 或 runSubagent；Hosted Agents 优先用 azd，Prompt Agents 优先用 Foundry MCP；引用官方 Microsoft 文档 URL，而不是嵌入 CLI 命令语法。
66. Azure 认证：阅读 references/auth-best-practices.md。
67. 额外资源：阅读 Foundry Hosted Agents 和 Foundry Agent Runtime Components 官方链接。
68. 网络隔离错误：适用于任何对 Foundry project 或其父 Foundry account 的调用（Foundry MCP tools、azd、az CLI、curl、REST 或 SDK）。若错误匹配 Public access is disabled / PublicNetworkAccessDisabled / 来自私有终结点的 403 Forbidden / 连接超时 / project endpoint FQDN 解析到公网 IP，通常表示父 Foundry account 的 publicNetworkAccess=Disabled 或 Enabled from selected IP addresses，且当前 shell 在 VNet 外。
69. 仅当错误模糊时，用管理平面调用确认 Foundry account：az cognitiveservices account show --name <account> --resource-group <rg> --query "properties.{publicNetworkAccess:publicNetworkAccess, networkAcls:networkAcls, privateEndpointConnections:privateEndpointConnections[].properties.privateLinkServiceConnectionState.status}"。publicNetworkAccess 为 Disabled，或 Enabled 且非空 networkAcls.ipRules/virtualNetworkRules，确认隔离。若 publicNetworkAccess 为 Enabled 且 networkAcls 为空，失败是调用方网络问题（如 Private DNS 从 VNet 内将 FQDN 解析到公网 IP），不是账户配置问题。
70. 若确实是网络隔离问题，支持的连接选项见官方 Choose a secure connection method to Foundry。注意 Foundry MCP 工具即使从 VNet 内也无法访问 VNet 隔离项目。

适用边界 · 注意事项

• 不适用于 Azure Functions 或 App Service。
• 不用于一般 Azure 部署或一般 Azure 准备工作；前者用 azure-deploy，后者用 azure-prepare。
• 不要主动使用 validate 子技能，除非用户明确要求验证 Microsoft Foundry hosted-agent 代码是否符合最佳实践。