microsoft-foundry

Microsoft Foundry 技能

此技能可帮助开发者使用 Microsoft Foundry 资源，涵盖模型发现与部署、AI Agent 的完整开发生命周期、评估工作流以及故障排除。

执行前要求

开始相应操作或工作流前，请先遵循下方适用的小节。

依赖项检查与设置

必须： 此技能加载后，第一步是在此技能的根目录中运行以下依赖项检查与设置脚本，并等待脚本完成后再继续。脚本会先进行检查，只安装缺失的依赖项；不会重新安装已有依赖项。

在阅读或进入任何子技能、工作流或工作流专属参考文档前，必须完成此检查。

./scripts/check-and-setup-dependencies.sh     # macOS / Linux
./scripts/check-and-setup-dependencies.ps1    # Windows (pwsh)

后续操作必须严格遵循脚本输出。

工作流指南

必须： 执行任何工作流专属步骤前，必须阅读相应的子技能文档。未阅读其技能文档前，不得调用工作流专属 MCP 工具。即使你已了解 MCP 工具的参数，也必须遵循此规则——技能文档包含必须遵循的工作流步骤、预检查和验证逻辑。每条触发不同工作流的新用户消息都适用此规则，即使技能已加载也不例外。

Foundry MCP

必须： 使用 Foundry MCP 操作前，先调用 Azure MCP foundry 工具，并检查可用的 Foundry MCP 工具及相关参数。将此步骤视为基于 MCP 的工作流中的发现／帮助步骤。

azd

必须： 执行任何 azd 命令前，必须阅读 azd-guidance，并严格遵循其中定义的通用规则，尤其是 AZURE_DEV_USER_AGENT 设置规则。

子技能

此技能包含针对特定工作流的专用子技能。当某项任务与某个子技能相匹配时，必须严格遵循其工作流：

子技能	适用场景	参考
deploy	将托管 Agent 部署到 Foundry，对部署进行冒烟测试，创建或更新提示词 Agent，并管理 Agent 版本和多环境部署。	deploy
cicd	为 Foundry Agent 设置 CI/CD 部署管道。	cicd
invoke	向 Agent 发送消息，进行单轮或多轮对话	invoke
routine	使用例行任务按计划或事件触发 Foundry Agent；使用 azd 执行 CRUD、启用/禁用、手动调度和查看过往运行记录，或在 azure.yaml 中定义例行任务。	routine
invocations-ws	构建、部署并连接使用 invocations_ws 双工 WebSocket 协议的托管 Agent——语音 Agent、实时流，以及带外媒体传输的信令。	invocations-ws
observe	评估 Agent 质量、运行批量评估、分析故障、优化提示词、改进 Agent 指令、比较版本、设置 CI/CD 监控，并启用持续生产评估	observe
insights	从现有监控器中获取生成的 Agent 洞察、证据和建议；仅检索数据，不会运行新的分析	insights
trace	查询跟踪记录、分析延迟/故障，并通过 App Insights customEvents 将评估结果与特定响应关联	trace
troubleshoot	查看托管 Agent 日志、查询遥测数据、诊断故障	troubleshoot
validate	仅当用户明确要求使用此验证子技能，或要求依据最佳实践验证 Microsoft Foundry 托管 Agent 代码时使用。切勿主动调用，或将其加入其他工作流。	validate
create (quick start)	从头到尾创建新的托管 Foundry Agent——搭建框架、预配或使用现有 Foundry 项目、部署并进行冒烟测试。不要用于对现有代码进行任何操作。对于快速入门未涵盖的内容，请使用 create。	create/quick-start-hosted.md
create	当标准的端到端顺利路径（快速入门）不适用时使用。创建新的 Foundry Agent、更新现有 Agent 的代码、继续开发现有 Agent、在搭建框架时配置连接、使用高级设置或 A2A (Agent2Agent)，或从失败的快速入门运行中恢复。	create
create managed harness	创建或继续开发明确使用 Foundry 托管 GitHub Copilot harness 的提示词 Agent。使用 azd 和 azure.yaml，而非普通的提示词 Agent MCP 工作流。	create-managed-harness
agent-optimizer	使现有 Python 托管 Agent 代码可进行优化，配置 eval.yaml，运行 Agent Optimizer 作业，在本地应用候选方案，并在审核后通过 azd 部署。	agent-optimizer
eval-datasets	将生产跟踪记录整理为评估数据集，管理数据集版本和拆分，跟踪评估指标随时间的变化，检测回归，并维护从跟踪记录到部署的完整沿袭。适用于：从跟踪记录创建数据集、数据集版本管理、评估趋势分析、回归检测、数据集比较、评估沿袭。	eval-datasets
project/create	创建用于托管 Agent 和模型的新 Microsoft Foundry 项目。适用于接入 Foundry 或设置新基础设施。	project/create/create-foundry-project.md
resource/create	使用 Azure CLI 创建 Azure AI Services 多服务资源（Foundry 资源）。适用于手动预配 AI Services 资源并进行精细控制。	resource/create/create-foundry-resource.md
private-network	解答有关 Foundry 网络隔离的问题，并在 VNet 隔离（自带 VNet、托管 VNet、混合模式）下部署 Foundry。涵盖架构概念、模板选择、部署和部署后验证。	resource/private-network/private-network.md
models/deploy-model	使用智能路由统一部署模型。支持快速预设部署、完全自定义部署（版本/SKU/容量/RAI），以及跨区域的容量发现。路由到子技能：preset（快速部署）、customize（完全控制）、capacity（查找可用性）。	models/deploy-model/SKILL.md
quota	管理 Microsoft Foundry 资源的配额和容量。适用于检查配额使用情况、排查因配额不足导致的部署失败、申请提高配额或规划容量。	quota/quota.md
rbac	管理 Microsoft Foundry 资源的 RBAC 权限、角色分配、托管标识和服务主体。适用于访问控制、权限审计和 CI/CD 设置。	rbac/rbac.md
finetuning	在 Microsoft Foundry 上微调模型——SFT 蒸馏、DPO 偏好优化、使用评分器和工具调用的 RFT。包括数据集准备、评分器校准、训练、检查点选择、部署和评估。适用于：微调、SFT、DPO、RFT、训练数据、评分器、蒸馏、微调模型、大文件上传。	finetuning/SKILL.md
azd-guidance	提供用于管理 Foundry Agent 的共享 azd 知识和指导。对于任何与 azd 相关的工作流，请先阅读此项。	azd-guidance

💡 提示： 完整的入门流程：project/create（公共访问）或 private-network（VNet 隔离）→ models/deploy-model → Agent 工作流（create → deploy → invoke）。

💡 微调： 使用 finetuning 进行所有模型定制，包括 SFT 蒸馏、DPO 偏好优化和使用评分器的 RFT。包含快速入门、评分器校准和训练曲线分析。

💡 模型部署： 使用 models/deploy-model 处理所有部署场景，它会智能地在快速预设部署、完全可控的自定义部署和跨区域容量发现之间进行路由。

💡 提示词优化： 对于“优化我的提示词”或“改进我的 Agent 指令”等请求，请加载 observe，并通过这个由评估驱动的工作流使用 prompt_optimize MCP 工具。

基础设施生命周期

根据用户意图选择正确的基础设施工作流。

用户意图	工作流
“创建 Foundry” / “设置 Foundry”（意图模糊）	使用 AskUserQuestion： (a) 仅创建一个 AI Services 资源，(b) 创建一个可公开访问的项目，还是 (c) 创建一个带网络隔离的项目？路由：(a) → resource/create，(b) → project/create，(c) → private-network
设置带 VNet 隔离的 Foundry	private-network
创建 Foundry 项目（公共访问）	project/create
创建一个基础 Foundry 资源	resource/create

Agent 开发生命周期

根据用户意图选择正确的 Agent 工作流。执行前请按顺序阅读各子技能。

用户意图	工作流（按顺序阅读）
创建或开发明确要求的 Managed Harness Agent / GitHub Copilot harness agent	依赖项检查和设置 → azd-guidance → create-managed-harness → deploy → invoke
从头到尾创建新的托管 Agent（搭建脚手架 + 部署 + 测试）	依赖项检查和设置 → azd-guidance → quick-start-hosted（端到端自包含）
超出标准快速入门的任何事项（现有代码、迁移、重新托管、自定义部署、脚手架阶段的连接、A2A (Agent2Agent)、恢复）	依赖项检查和设置 → azd-guidance → create → deploy → invoke
优化现有的 Python 托管 Agent	依赖项检查和设置 → azd-guidance → agent-optimizer → 搭建脚手架/审查 → eval.yaml → 优化 → 应用候选方案 → 部署 → 调用
部署 Agent（代码已存在）	依赖项检查和设置 → azd-guidance → 部署（包括 eval-suite 设置）→ 调用 → 观察（评估/优化）
代码更改后更新/重新部署 Agent	依赖项检查和设置 → azd-guidance → 部署（包括 eval-suite 设置）→ 调用 → 观察（评估/优化）
为托管 Agent 设置 CI/CD 部署管道	依赖项检查和设置 → azd-guidance → cicd
调用/测试/与 Agent 聊天	依赖项检查和设置 → azd-guidance → invoke
定时/事件触发 Agent，或对例程执行 CRUD/启用/禁用/调度	依赖项检查和设置 → azd-guidance → routine
优化/改进 Agent 提示词或指令	observe（步骤 4：优化）
评估并优化 Agent（完整循环）	observe
启用持续评估监控	observe（步骤 6：CI/CD 和监控）
获取 Agent 洞察/列出生成的问题和建议	依赖项检查和设置 → insights（所有页面均包含扩展证据；只读）
排查 Agent 问题	依赖项检查和设置 → azd-guidance → invoke → troubleshoot
修复故障 Agent（排查 + 重新部署）	依赖项检查和设置 → azd-guidance → invoke → troubleshoot → 应用修复 → deploy → invoke

Agent：.foundry 工作区标准

每个 Agent 源文件夹都可以在 .foundry/ 下保存 Foundry 专用缓存和覆盖状态：

<agent-root>/
  .foundry/
    agent-metadata.yaml
    agent-metadata.prod.yaml
    suites/
    datasets/
    evaluators/
    results/

• 对于 azd 项目，从 azure.yaml 和 azd env get-values 推导部署上下文（项目终结点、Agent 名称/版本、ACR、App Insights）；如果 azd 已提供这些值，请勿在元数据中重复记录。
• agent-metadata.yaml 是非 azd 值、远程 Foundry 套件引用、本地缓存路径、结果摘要和显式覆盖项的首选本地/开发覆盖文件。可选的旁文件（例如 agent-metadata.prod.yaml）可以保存单个面向生产或 CI 的覆盖项，避免在同一个文件中混合多个环境。
• suites/、datasets/ 和 evaluators/ 是本地缓存文件夹。内容仍为最新时请复用；刷新或覆盖前请先征求确认。
• 规范的架构和工作流规则请参阅 Agent 元数据契约。

Agent：设置参考

• 标准 Agent 设置 — 适用于需要控制数据驻留的生产工作负载的高级设置（通过 Foundry 功能主机使用自带的 Cosmos DB / Storage / AI Search）。默认的 azd ai agent 流程使用 基本 Agent 设置，且不会预配 capabilityHosts/agents——请勿将其缺失判定为缺陷。默认预配后的状态，请参阅 foundry-agent/create/create-hosted.md 中的“预期环境变量指纹”部分。

Agent：常见项目上下文解析

仅当 Agent 技能需要尚未获取的配置值时，才应执行此步骤。如果已从用户消息或同一会话中的先前技能获知某个值（例如 Agent 根目录、环境、项目终结点或 Agent 名称），则跳过该值的解析。

步骤 1：发现 Agent 根目录和 azd 上下文

首先检查工作区是否包含带有 host: azure.ai.agent 服务的 azure.yaml。

• 一个 azd Agent 服务 → 根据 kind 和 harness 对其分类，然后使用该服务的 project 文件夹或 azure.yaml 所在目录作为 Agent 根目录。
• 多个 azd Agent 服务 → 要求用户选择目标服务/文件夹。
• 没有 azd Agent 服务 → 在工作区中搜索包含 agent-metadata.yaml 或 agent-metadata.<env>.yaml 的 .foundry/ 文件夹。
  • 找到一个 → 使用该 Agent 根目录。
  • 找到多个 → 要求用户选择目标 Agent 文件夹。
  • 未找到 → 对于 insights，只询问缺少的远程输入，不初始化本地文件；对于创建/部署工作流，在设置期间创建新的 .foundry/ 文件夹；对于其他工作流，停止并询问用户要初始化哪个 Agent 源文件夹。

选择 Agent 根目录后，所有本地 .foundry 缓存检查、源文件检查、评估器建议、数据集建议和提示词优化上下文都必须限定在该文件夹内。除非用户明确切换根目录，否则不要扫描同级 Agent 文件夹。

步骤 2：解析环境和部署上下文

如果存在 azure.yaml，请先解析 azd 环境：

1. 用户明确指定的环境
2. azd env get-values 中的 AZURE_ENV_NAME
3. .azure/config.json 中的 azd 默认环境
4. 会话中此前已选择的环境

如果项目或部署值尚未确定，请针对所选环境运行 azd env get-values。部署上下文优先使用 azd 值：

azd 变量	解析为
AZURE_AI_PROJECT_ENDPOINT 或 AZURE_AIPROJECT_ENDPOINT	项目终结点
AGENT_<SERVICE>_NAME	所选 azd 服务的 Agent 名称
AGENT_<SERVICE>_VERSION	所选 azd 服务的 Agent 版本
AZURE_CONTAINER_REGISTRY_NAME 或 AZURE_CONTAINER_REGISTRY_ENDPOINT	ACR 注册表名称／镜像 URL 前缀
APPLICATIONINSIGHTS_CONNECTION_STRING	用于跟踪工作流的 App Insights 连接字符串
AZURE_SUBSCRIPTION_ID、AZURE_RESOURCE_GROUP、AZURE_AI_ACCOUNT_NAME、AZURE_AI_PROJECT_NAME	Azure 资源查询和 Playground 链接

如果 azd 提供了这些值，请以其为准，并且在写入元数据时不要将它们复制到 .foundry/agent-metadata*.yaml 中。

步骤 3：选择元数据叠加文件并解析环境

在所选 Agent 根目录中，按以下顺序选择元数据文件：

1. 用户或工作流明确提供的元数据文件名或路径
2. 如果已知明确的环境，且 .foundry/agent-metadata.<env>.yaml 存在，则使用该文件
3. .foundry/agent-metadata.yaml
4. 如果仍有多个元数据文件，且上述规则均无法选出一个，则提示用户选择

读取所选元数据文件，并按以下顺序解析任何尚未确定的环境选择：

1. 用户明确指定的环境
2. 如果所选元数据文件只定义了一个环境，则使用该环境
3. 会话中此前已选择的环境
4. 元数据中的 defaultEnvironment

如果所选元数据文件仍包含多个环境，且上述规则均未能选出一个，则提示用户选择。在每个工作流摘要中，都要清楚显示所选的 Agent 根目录、元数据文件、环境，以及上下文来自 azd 还是元数据。

如果所选环境公开了较旧的 testSuites[] 元数据，但没有 evaluationSuites[]，则在本次会话中将 testSuites[] 作为数据源，并在继续之前将每个条目规范化为 evaluationSuites[] 的结构。如果元数据版本更旧，且只公开了旧版 testCases[]，则以相同方式规范化该列表。保留数据集和评估器字段，保留已有的 tags，并且仅在缺少 tags.tier 时将旧版 priority 映射到 tags.tier：P0 -> smoke、P1 -> regression、P2 -> coverage。

步骤 4：解析 eval.yaml 中的本地评估意图

如果所选 Agent 根目录中存在 eval.yaml，请在生成新套件之前解析它：

• agent.name -> 目标 Agent 候选项；使用前请确认它与所选的 azd／元数据 Agent 相匹配。
• dataset.local_uri -> 本地种子数据集候选项；旧版 dataset_file 可在内存中规范化。
• dataset.name / dataset.version -> 已注册的数据集候选项。
• validation_dataset -> 可选的验证数据集候选项。
• evaluators[] -> Foundry 评估器名称候选项；将其视为远程评估器前，请通过 evaluator_catalog_get 确认。
• name -> 本地评估／套件候选项；将其保存为 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 套件存在的证明。只有在远程查询或注册成功后，才将同步的套件／数据集／评估器引用保存到 .foundry。

第 5 步：解析常见配置

按以下顺序叠加配置来源：

1. 明确的用户输入和会话中已选定的值
2. 用于部署上下文的 azd 环境值
3. .foundry/agent-metadata*.yaml 覆盖值和远程套件／缓存引用
4. azure.yaml 和 eval.yaml 本地源配置
5. 对仍缺失的内容向用户提问

如果 azd 和元数据提供了相同的值但内容不同，请暂停并询问哪个来源权威。如果二者一致，则使用 azd 的值，并在之后写入元数据时避免重复写入。

生效值	首选来源	使用场景
项目终结点	azd env	deploy、invoke、observe、trace、troubleshoot
Agent 名称／版本	azd Agent 变量，其次是 azure.yaml	invoke、observe、trace、troubleshoot
ACR	azd env	deploy
评估套件和缓存路径	.foundry/agent-metadata*.yaml	observe、eval-datasets
本地种子数据集／评估器意图	eval.yaml	observe、eval-datasets

第 6 步：写入元数据覆盖项（仅限 Create／Deploy／Observe）

进行任何元数据写入（deploy、自动设置、数据集刷新或 trace 转数据集更新）时，仅将无法推导的覆盖项／缓存状态持久化到所选元数据文件中：

• azd 绑定（azd.environmentName、azd.service），便于后续解析时使用
• evaluationSuites[]，包含远程套件／数据集／评估器引用和本地缓存路径
• lastEval、结果文件、比较摘要或明确的非 azd 覆盖项

如果 azd 已提供其负责的部署值，请勿将这些值复制到元数据中。如果所选文件是首选的单环境文件，则仅重写该文件中的环境区块。如果所选文件是旧版多环境文件，则仅重写所选环境区块。切勿自动跨同级元数据文件复制或合并环境。如果所选环境仍使用较旧的 testSuites[] 或旧版 testCases[]，请将其改写为 evaluationSuites[]，并从重写后的条目中移除已迁移的 priority 字段。

第 7 步：收集缺失值

仅当用户消息、会话上下文、元数据或 azd 引导配置中无法解析所需值时，才使用 ask_user 或 askQuestions 工具。技能可能需要的常见值：

• Agent 根目录 — 目标 azd 服务项目文件夹，或包含 .foundry/agent-metadata*.yaml 的文件夹
• 元数据文件 — 本地／开发环境使用 agent-metadata.yaml，或使用明确指定的旁路文件，例如 agent-metadata.prod.yaml
• 环境 — azd 环境、dev、prod 或元数据中的其他环境键
• 项目终结点 — Microsoft Foundry 项目终结点 URL
• Agent 名称 — 目标 Agent 的名称

💡 **提示：**如果用户已提供 Agent 路径、环境、项目终结点或 Agent 名称，请直接提取，不要再次询问。

Agent：Agent 类型

Agent 工作流分为三种开发路径：

类型	种类	说明
提示词	"prompt"	由模型部署提供支持的基于大模型的 Agent
托管型	"hosted"	运行自定义代码的容器型 Agent
托管式 Harness Agent	"prompt"，且 harness.type: "github_copilot_preview"	在 Foundry 管理的 GitHub Copilot harness 上运行的提示词 Agent；此技能使用 azd 进行开发和部署

根据定义而非仅根据 host 对 azure.yaml 服务进行分类：

• kind: hosted -> 托管型。
• kind: prompt 且 harness.type: github_copilot_preview -> 托管式 Harness Agent。
• kind: prompt 且不含该 harness -> 普通提示词 Agent。

仅当无法从项目上下文确定类型时，才使用 agent_get。不要将现有 Agent 转换为提示词、托管型或托管式 Harness Agent；请改为创建新的 Agent。

工具使用约定

• 从用户处收集信息时，使用 ask_user 或 askQuestions 工具
• 委派耗时较长或相互独立的子任务（例如扫描环境变量、轮询状态、生成 Dockerfile）时，使用 task 或 runSubagent 工具
• 对于 Hosted Agents 和 Managed Harness Agents，优先使用 azd；对于普通的 Prompt Agents，优先使用 Foundry MCP。
• 请引用 Microsoft 官方文档 URL，而不是嵌入 CLI 命令语法

Azure 身份验证

• Azure 身份验证最佳实践

其他资源

• Foundry 托管 Agent
• Foundry Agent 运行时组件

网络隔离错误

适用于针对 Foundry 项目或其父级 Foundry 帐户发起的任何调用 — Foundry MCP 工具、azd、az CLI、curl、REST 或 SDK。

如果错误与 Public access is disabled / PublicNetworkAccessDisabled / 来自专用终结点的 403 Forbidden / 连接超时 / 项目终结点 FQDN 解析为公共 IP 相符，通常意味着父级 Foundry 帐户的 publicNetworkAccess=Disabled 或 Enabled from selected IP addresses，且当前 shell 位于其 VNet 之外。

仅当错误含义不明确时，才通过管理平面调用向 Foundry 帐户确认（任何具有读取者访问权限的位置均可调用）：

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 为空，则故障是调用方侧的网络问题（例如，在具有专用终结点的 VNet 内，Private DNS 将 FQDN 解析为公共 IP），而非帐户配置问题。

如果确实是网络隔离问题，选择连接到 Foundry 的安全方法中介绍了受支持的连接选项。

ℹ️ Foundry MCP 工具无法访问 VNet 隔离的项目，即使位于 VNet 内也不行。