name: microsoft-foundry
description: 部署、评估并端到端管理 Foundry 代理：Docker 构建、ACR 推送、托管/提示代理创建、容器启动、批量评估、持续评估、提示优化工作流、agent.yaml、基于追踪的数据集整理。用于：将代理部署到 Foundry、托管代理、创建代理、调用代理、评估代理、运行批量评估、持续评估、持续监控、持续评估状态、优化提示、改进提示、提示优化器、优化代理指令、改进代理指令、优化系统提示、部署模型、Foundry 项目、RBAC、角色分配、权限、配额、容量、区域、排查代理问题、部署失败、从追踪创建数据集、数据集版本控制、评估趋势、创建 AI 服务、认知服务、创建 Foundry 资源、配置资源、知识索引、代理监控、自定义部署、入门、可用性。请勿用于：Azure Functions、应用服务、常规 Azure 部署（请使用 azure-deploy）、常规 Azure 准备工作（请使用 azure-prepare）。
license: MIT
metadata:
    author: Microsoft
    version: "1.1.13"

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）。

💡 模型部署： 对于所有部署场景，使用 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
    datasets/
    evaluators/
    results/

• agent-metadata.yaml 是首选的本地/开发元数据文件。可选的 sidecar 文件如 agent-metadata.prod.yaml 可保存单个生产或 CI 目标环境，而无需在单个文件中混合多个环境。
• datasets/ 和 evaluators/ 是本地缓存文件夹。当它们是最新时重复使用，在刷新或覆盖之前询问。
• 有关规范架构和工作流规则，请参阅[代理元数据契约](references/agent-metadata-contract.md)。

代理：设置参考

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

代理：项目上下文解析

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

步骤 1：发现代理根

在工作区中搜索包含 agent-metadata.yaml 或 agent-metadata.<env>.yaml 的 .foundry/ 文件夹。

• 找到一个 → 使用该代理根。
• 找到多个 → 要求用户选择目标代理文件夹。
• 未找到 → 对于创建/部署工作流，在设置期间植入新的 .foundry/ 文件夹；对于所有其他工作流，停止并询问用户要初始化哪个代理源文件夹。

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

步骤 2：选择元数据文件并解析环境

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

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

读取选定的元数据文件并按以下顺序解析环境：

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

如果选定的元数据文件仍包含多个环境且以上规则均未选中，则提示用户选择。在每个工作流摘要中保持选定的代理根、元数据文件和环境可见。

如果选定环境公开旧的 testSuites[] 元数据但未公开 evaluationSuites[]，则将 testSuites[] 作为此会话的来源，并在继续之前将每个条目在内存中规范化为 evaluationSuites[] 形状。如果元数据更旧且仅公开旧的 testCases[]，则同样规范化该列表。保留数据集和评估器字段，保留任何现有的 tags，并且仅当 tags.tier 缺失时才将旧的 priority 映射到 tags.tier：P0 -> smoke，P1 -> regression，P2 -> coverage。

步骤 3：解析通用配置

使用选定元数据文件中的选定环境作为主要来源：

步骤 4：引导缺失元数据（仅创建/部署）

如果创建/部署正在初始化新的 .foundry 工作区且元数据字段仍缺失，请检查项目根目录中是否存在 azure.yaml。如果找到，则运行 azd env get-values 并将其用于默认情况下植入 agent-metadata.yaml，或者在工作流显式针对特定于环境的文件时植入 agent-metadata.<env>.yaml。

在任何元数据写入操作（部署、自动设置、数据集刷新或追踪到数据集更新）中，仅将 evaluationSuites[] 持久化到选定的元数据文件。如果选定的文件是首选单环境文件，则仅重写该环境块。如果选定的文件是旧的多环境文件，则仅重写选定的环境块。永远不要自动跨同级元数据文件复制或合并环境。如果选定的环境仍使用旧的 testSuites[] 或旧的 testCases[]，则将其重写为 evaluationSuites[] 并从重写的条目中删除已迁移的 priority 字段。

步骤 5：收集缺失值

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

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

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

代理：代理类型

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

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

工具使用约定

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

其他资源

• Foundry 托管代理
• Foundry 代理运行时组件

SDK 快速参考

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