name: microsoft-foundry
description: 部署、评估、微调并端到端管理 Foundry 代理：Docker 构建、ACR 推送、托管/提示代理创建、容器启动、批量评估、持续评估、提示优化器、Agent Optimizer 脚手架、agent.yaml、从追踪数据中整理数据集、模型微调（SFT/DPO/RFT）。用途：部署代理、托管代理、创建代理、为代理添加工具、调用代理、评估代理、持续评估、持续监控、优化提示词、改进提示词、优化代理指令、部署模型、Foundry 项目、RBAC、角色分配、权限、配额、容量、区域、排查代理问题、部署失败、AI 服务、创建 Foundry 资源、预配、知识索引、代理监控、自定义部署、入职、可用性、微调、SFT、DPO、RFT、训练数据、评分器、蒸馏、微调模型、大文件上传。不适用于：Azure Functions、App Service、一般 Azure 部署（使用 azure-deploy）、一般 Azure 准备（使用 azure-prepare）。
license: MIT
metadata:
    author: Microsoft
    version: "1.1.23"

Microsoft Foundry 技能

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

执行前要求

必须：在执行任何工作流之前，必须先调用 Azure MCP foundry 工具，并检查可用的 Foundry MCP 工具及相关参数。 将此初始的 foundry 调用视为发现/帮助步骤。对于此技能，Azure MCP foundry 是 Foundry 相关 MCP 操作的必需入口点。

子技能

必须：在执行任何工作流特定步骤之前，必须阅读相应的子技能文档。 在没有阅读其技能文档的情况下，不要为某个工作流调用工作流特定的 MCP 工具。即使你已经知道 MCP 工具参数，此规则仍然适用——技能文档包含必须遵循的工作流步骤、前置检查和验证逻辑。此规则适用于每条触发不同工作流的新用户消息，即使该技能已加载。

此技能包含针对特定工作流的专门子技能。当这些子技能与你的任务匹配时，请使用它们代替主技能：

💡 提示： 完整的上手流程：project/create（公共）或 private-network（VNet 隔离）→ models/deploy-model → 代理工作流（create → deploy → invoke）。

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

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

💡 提示优化： 对于“优化我的提示”或“改进我的代理指令”等请求，加载 [observe](foundry-agent/observe/observe.md) 并通过该评估驱动的工作流使用 prompt_optimize MCP 工具。

基础设施生命周期

将用户意图与正确的基础设施工作流匹配。

代理开发生命周期

将用户意图与正确的代理工作流匹配。在执行前按顺序阅读每个子技能。

代理：.foundry 工作区标准

每个代理源文件夹可以在 .foundry/ 下保留 Foundry 特定的缓存和覆盖状态：

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

• 在 azd 项目中，从 azure.yaml 加上 azd env get-values 推导部署上下文（项目端点、代理名称/版本、ACR、App Insights）；当 azd 已提供这些值时，不要在元数据中重复这些值。
• agent-metadata.yaml 是首选的本地/开发覆盖文件，用于非 azd 值、远程 Foundry 套件引用、本地缓存路径、结果摘要和显式覆盖。可选的 sidecar 文件（如 agent-metadata.prod.yaml）可以保存单个生产或 CI 目标的覆盖，无需在一个文件中混合多个环境。
• suites/、datasets/ 和 evaluators/ 是本地缓存文件夹。当它们最新时重用它们，在刷新或覆盖之前询问。
• 参见 [Agent Metadata Contract](references/agent-metadata-contract.md) 了解规范模式和工作流规则。

代理：设置参考

• [Standard Agent Setup](references/standard-agent-setup.md) - 使用客户管理的数据、搜索和 AI Services 资源的标准能力主机设置。

代理：通用项目上下文解析

代理技能应仅在需要它们尚未拥有的配置值时运行此步骤。如果值（例如，代理根目录、环境、项目端点或代理名称）已从用户消息或同一会话中的先前技能获知，则跳过对该值的解析。

第 1 步：发现代理根目录和 azd 上下文

首先检查工作区是否存在包含使用 host: azure.ai.agent 的服务的 azure.yaml。

• 一个 azd 代理服务 -> 使用该服务的 project 文件夹作为代理根目录。
• 多个 azd 代理服务 -> 要求用户选择目标服务/文件夹。
• 没有 azd 代理服务 -> 在工作区中搜索包含 agent-metadata.yaml 或 agent-metadata.<env>.yaml 的 .foundry/ 文件夹。
• 一个匹配 -> 使用该代理根目录。
• 多个匹配 -> 要求用户选择目标代理文件夹。
• 无匹配 -> 对于创建/部署工作流，在设置期间播种一个新的 .foundry/ 文件夹；对于所有其他工作流，停止并询问用户要初始化哪个代理源文件夹。

选择代理根目录后，将所有本地 .foundry 缓存检查、源检查、评估器建议、数据集建议和提示优化上下文保留在该文件夹内。除非用户显式切换根目录，否则不要扫描同级代理文件夹。

第 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 提供这些值时，将它们用作事实来源，并且在元数据写入时不要将它们复制到 .foundry/agent-metadata*.yaml 中。

第 3 步：选择元数据覆盖并解析环境

在选定的代理根目录内，按以下顺序选择元数据文件：

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

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

1. 用户显式命名的环境
2. 如果所选元数据文件正好定义一个环境，则使用它
3. 会话中先前已选择的环境
4. 来自元数据的 defaultEnvironment

如果所选元数据文件仍包含多个环境，且上述规则均未选择一个，则提示用户选择。在每个工作流摘要中保持可见所选代理根目录、元数据文件、环境以及上下文来自 azd 还是元数据。

如果所选环境公开旧的 testSuites[] 元数据而非 evaluationSuites[]，则将 testSuites[] 视为本次会话的来源，并将每个条目在内存中规范化为 evaluationSuites[] 形状后再继续。如果元数据更旧，仅公开旧的 testCases[]，则以相同方式规范化该列表。保留数据集和评估器字段，保留任何现有的 tags，并且仅在 tags.tier 缺失时，将旧的 priority 映射到 tags.tier：P0 -> smoke，P1 -> regression，P2 -> coverage。

第 4 步：解析 eval.yaml 本地评估意图

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

• agent.name -> 目标代理候选；验证它是否与所选 azd/元数据代理匹配后再使用。
• dataset_file -> 本地种子数据集候选。
• evaluators[] -> 候选 Foundry 评估器名称；使用 evaluator_catalog_get 验证后再将其视为远程评估器。
• name -> 本地评估/套件候选；远程验证后再作为 suiteName 持久化。
• options.eval_model、options.pass_threshold、max_samples、trace_days 和 generation_instruction -> 设置默认值。

将 eval.yaml 视为本地评估意图，而不是 Foundry 套件存在的证明。仅当远程查找或注册成功后，才将同步的套件/数据集/评估器引用持久化到 .foundry。

第 5 步：解析通用配置

按此顺序分层来源：

1. 显式用户输入和会话中已选择的值
2. azd 环境值用于部署上下文
3. .foundry/agent-metadata*.yaml 覆盖值和远程套件/缓存引用
4. agent.yaml 和 eval.yaml 本地源代码配置
5. 对于仍缺失的任何内容的用户提示

如果 azd 和元数据都提供相同的值但不同，则停止并询问哪个来源是权威的。如果它们匹配，则使用 azd 值，并避免在将来的元数据写入时重写重复项。

第 6 步：写入元数据覆盖（仅限创建/部署/观察）

在任何元数据写入（部署、自动设置、数据集刷新或跟踪到数据集更新）时，仅在所选元数据文件中持久化不可推导的覆盖/缓存状态：

• azd 绑定（azd.environmentName、azd.service）当对未来解析有用时
• evaluationSuites[] 包含远程套件/数据集/评估器引用和本地缓存路径
• lastEval、结果文件、比较摘要或显式非 azd 覆盖

当 azd 已提供时，不要将 azd 拥有的部署值复制到元数据中。如果所选文件是首选单环境文件，仅重写该一个环境块。如果所选文件是旧的多环境文件，仅重写所选环境块。切勿自动将环境跨同级元数据文件复制或合并。如果所选环境仍使用旧的 testSuites[] 或旧的 testCases[]，将其重写为 evaluationSuites[] 并从重写的条目中移除已迁移的 priority 字段。

第 7 步：收集缺失值

仅对从用户消息、会话上下文、元数据或 azd 引导中未解析的值使用 ask_user 或 askQuestions 工具。技能可能需要的常见值：

• 代理根目录 — 目标 azd 服务项目文件夹或包含 .foundry/agent-metadata*.yaml 的文件夹
• 元数据文件 — 用于本地/开发的 agent-metadata.yaml，或显式的 sidecar 如 agent-metadata.prod.yaml
• 环境 — azd 环境、dev、prod 或来自元数据的其他环境键
• 项目端点 — AI Foundry 项目端点 URL
• 代理名称 — 目标代理的名称

💡 提示： 如果用户已提供代理路径、环境、项目端点或代理名称，直接提取——不要再次询问。

代理：代理类型

所有代理技能支持两种代理类型：

必要时使用 agent_get MCP 工具确定代理的类型。

工具使用约定

• 在需要从用户收集信息时使用 ask_user 或 askQuestions 工具
• 使用 task 或 runSubagent 工具委托长时间运行或独立的子任务（例如，环境变量扫描、状态轮询、Dockerfile 生成）
• 当可用时，优先使用 Azure MCP 工具而非直接 CLI 命令
• 引用官方 Microsoft 文档 URL 而不是嵌入 CLI 命令语法

其他资源

• Foundry Hosted Agents
• Foundry Agent Runtime Components

SDK 快速参考

• [Python](references/sdk/foundry-sdk-py.md)