microsoft-foundry

概览

microsoft-foundry 技能是什么？

microsoft-foundry 技能是一套精心整理的 workflow 和参考文档，用于引导你完成 Azure AI Foundry agents 的端到端全生命周期。内容重点在于落地部署与运维实践：

• 创建 prompt agents 和 hosted agents
• 构建 Docker 镜像并推送到 Azure Container Registry (ACR)
• 将 agents 部署到 Azure AI Foundry
• 配置 projects、RBAC、配额（quota）和 connections
• 运行 evaluation datasets 并管理 agent-metadata.yaml
• 配置 standard 和 private-network 两类 agent 部署形态
• 启用 observability、tracing 和故障排查

所有内容均来自 microsoft/azure-skills 仓库，并经过结构化整理，帮助你在 Azure AI Foundry 上直接运营 agents，而无需自己去“反向工程”仓库结构。

适合哪些人使用？

在以下场景中你可以使用 microsoft-foundry：

• 你是负责部署和运维 Azure AI Foundry agents 的 后端或平台工程师
• 你是将原型迁移到生产 Foundry 项目的 AI/ML 工程师
• 你是需要将 Foundry agents 集成到现有服务、SDK 或 MCP 工具中的 开发者
• 你是需要考虑 RBAC、配额、私有网络以及环境搭建的 技术负责人

如果你只需要基础的 Azure 基础设施部署（App Service、Functions、通用 Web 应用等），那这个技能并不适合——请改用更通用的 Azure 部署技能。

microsoft-foundry 解决哪些问题？

该技能专门针对以下常见难点：

• “我的 agent 仓库在 Foundry 下应该怎么布局？”
  使用 references/agent-metadata-contract.md 中的指南，了解 .foundry/ 目录结构和 agent-metadata.yaml 字段说明。

• “如何以一致的方式创建和部署 agents？”
  使用 foundry-agent/create 和 foundry-agent/deploy workflow 来创建 prompt/hosted agents，构建容器、推送到 ACR，并启动 agent 容器。

• “如何配置 projects、connections、RBAC 和配额？”
  参考 project/create、rbac/rbac.md 和 quota/quota.md，完成项目创建、角色分配和容量规划。

• “如何评估和观测我的 agents？”
  使用 foundry-agent/eval-datasets、foundry-agent/observe 和 foundry-agent/trace 来跑批量评估、管理数据集与 evaluator，并接入 observability 资源。

• “standard 和 private-network 两种部署形态该怎么选和配置？”
  使用 references/standard-agent-setup.md 和 references/private-network-standard-agent-setup.md 选择并配置适合的网络模型。

在哪些情况下 microsoft-foundry 是合适的？

在以下需求下使用此技能：

• 需要将 prompt 或 hosted agents 部署到 Azure AI Foundry
• 需要使用 .foundry/agent-metadata.yaml 统一 agent 项目结构
• 需要将 MCP 工具 和 Azure SDK 集成进可复用的 workflow
• 需要为 agent 工作负载管理 RBAC、配额和容量规划
• 需要运行 evaluation datasets 并在不同环境间追踪评估结果
• 需要使用 Application Insights 和 traces 搭建 observability
• 需要部署到 standard 或 private-network (VNet) 配置中

在以下情况时不建议只用这个技能：

• 仅需通用 Azure 应用部署（Web apps、Functions、App Service）
• 只是做 Azure 帐号或订阅的高层级准备工作

这类场景下，请将本技能与更通用的 Azure 部署/准备技能配合使用，或直接使用 azure-deploy / azure-prepare 等专用技能。

使用方法

安装

要从 microsoft/azure-skills 仓库添加 microsoft-foundry，请执行：

npx skills add https://github.com/microsoft/azure-skills --skill microsoft-foundry

执行后，microsoft-foundry 中的 workflow 和参考内容将可用于你的 agent 或工具环境。安装完成后，主要入口文件为 skills/microsoft-foundry 目录下的 SKILL.md。

仓库结构与关键目录

安装技能或在仓库中打开后，你会看到如下结构：

• SKILL.md – 顶层技能索引和子技能列表
• foundry-agent/ – 面向单个 agent 的端到端 workflow
  • create/ – 创建 prompt 或 hosted agents
  • deploy/ – 构建并部署 agents（包括容器与 ACR）
  • eval-datasets/ – 管理评估数据集与评估运行
  • invoke/ – 调用已有 agents
  • observe/ – observability 配置与监控 workflow
  • trace/ – trace 采集以及基于 trace 的数据集创建
  • troubleshoot/ – 失败运行的排障指南
• project/
  • create/ – 创建与配置 Azure AI Foundry projects
  • connections.md – 项目级 connections 配置指导
• rbac/
  • rbac.md – RBAC 角色、权限和常用模式
• quota/
  • quota.md – 配额与容量规划指南
  • references/ – 容量规划、错误排查、优化说明
• references/
  • agent-metadata-contract.md – .foundry/ 布局与 agent-metadata.yaml
  • auth-best-practices.md – Azure 身份验证模式与 RBAC 最佳实践
  • standard-agent-setup.md – standard（非隔离）agent 部署配置
  • private-network-standard-agent-setup.md – VNet/private-link 部署配置
  • sdk/ – 在没有 MCP 工具时的 SDK 操作参考

从 SKILL.md 开始了解子技能，再深入到与你场景对应的具体目录。

快速入门流程：从项目到已部署的 agent

本节给出一个基于 microsoft-foundry 内容的实战路径。

1. 创建或准备 Foundry 项目

1. 打开 project/create/create-foundry-project.md。
2. 按步骤执行：
   • 创建一个 Azure AI Foundry project
   • 确认 project endpoint（例如：https://<resource>.services.ai.azure.com/api/projects/<project>）
   • 按 standard 部署需求，关联必要的 connections（Cosmos DB、Storage、Azure AI Search 等）
3. 查阅 project/connections.md，确保你的线程存储、文件存储和向量存储 connections 配置正确，尤其是在计划使用 standard agent setup 时。

2. 配置 RBAC 与身份验证

1. 阅读 rbac/rbac.md，确认：
   • 在资源组和 Foundry 资源上需要哪些角色（Owner、Contributor、User Access Administrator 等）
   • 如何按照 Azure RBAC 最佳实践分配角色
2. 打开 references/auth-best-practices.md 并应用其中建议：
   • 在生产环境使用 managed identities 与 Azure RBAC
   • 将 DefaultAzureCredential 限定在本地开发使用
   • 为生产、CI/CD 和开发环境选择合适的凭据类型

这样可以在不硬编码密钥的前提下，保证部署和 agent 运行的可靠身份验证。

3. 决定使用 basic、standard 还是 private-network 部署

1. 打开 references/standard-agent-setup.md，了解：
   • Basic 与 Standard 两种部署模式的区别
   • standard 部署需要的 connections：Cosmos DB、Azure Storage、Azure AI Search，以及可选的 Azure AI Services
   • 前置条件，例如在资源组上的 RBAC 角色要求
2. 如需 完全网络隔离，阅读 references/private-network-standard-agent-setup.md：
   • VNet 与子网要求（agent 子网和 private endpoint 子网）
   • Foundry 资源与 VNet 的区域对齐要求
   • 如何使用官方 Bicep 模板 完成 private-network standard agent 部署

在继续创建 agent 之前，先选择满足合规与网络要求的部署形态。

4. 统一 agent 项目布局

1. 打开 references/agent-metadata-contract.md，将你的项目对齐到约定的布局：

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

2. 确认 agent-metadata.yaml 中包含环境定义以及如下字段：

   • defaultEnvironment
   • environments.<name>.projectEndpoint
   • environments.<name>.agentName
   • environments.<name>.azureContainerRegistry（用于 hosted agents）
   • environments.<name>.observability.*（用于 Application Insights）
   • environments.<name>.testCases[]（用于评估用例集合）

该文件将作为环境配置的单一事实来源，其他 microsoft-foundry workflow 默认它存在且配置正确。

5. 创建 prompt 或 hosted agent

1. 对于 prompt agents，打开 foundry-agent/create/create-prompt.md：

   • 理解 prompt agents 与 workflows 的区别
   • 按步骤解析项目上下文（endpoint、credentials）
   • 在可用时优先使用 MCP 工具，在不可用时按文档回退到 azure-ai-projects SDK
   • 提供 agent 名称、模型部署、指令说明以及可选工具（file search、code interpreter 等）

2. 对于 hosted agents，打开 foundry-agent/create/create.md：

   • 选择是创建新 agent（greenfield），还是将已有项目转换为 hosted agent（brownfield）
   • 根据示例路径选择框架和语言（Python 或 C#，如 Microsoft Agent Framework 或 LangGraph）
   • 按指导在需要时与 foundry-samples 仓库集成

完成此步骤后，你应当拥有一个符合 Foundry 要求、可用于部署的 agent 项目。

6. 构建并部署 agent

1. 打开 foundry-agent/deploy/deploy.md。
2. 按 workflow 执行：
   • 项目扫描与环境变量收集
   • 为 hosted agents 生成 Dockerfile，并使用 docker / az acr 构建与推送
   • 使用 MCP 工具（如 agent_update、agent_container_control 和 agent_container_status_get）
   • 创建或更新部署，并启动/停止 agent 容器
3. 不要在未阅读该指南的情况下单独执行 azd up、azd deploy、az acr build 或 docker build——该技能会将这些命令作为整体部署流水线的一部分进行编排。

完成此步骤后，你的 agent 应已成功部署，并可通过 Azure AI Foundry 访问。

7. 调用并测试 agent

1. 打开 foundry-agent/invoke/invoke.md。
2. 按文档中的模式：
   • 从 agent-metadata.yaml 中解析正确的环境与 endpoint
   • 使用示例或自定义 payload 调用 agent
   • 验证返回结果、工具调用及状态行为是否符合预期

这是在跑完整评估套件前做 smoke test 的理想阶段。

8. 评估与迭代

1. 打开 foundry-agent/eval-datasets/eval-datasets.md。
2. 按指南执行：
   • 在 .foundry/datasets 和 .foundry/evaluators 下管理数据集与 evaluator
   • 使用 agent-metadata.yaml 中的 testCases 定义来运行评估 workflow
   • 将输出存储在 .foundry/results 中，并按环境或 agent 版本比较结果
3. 持续迭代 prompt 或指令配置，并重复评估以观察效果提升。

Observability、tracing 与故障排查

Observability 与监控

1. 打开 foundry-agent/observe/observe.md。
2. 按指南配置 observability：
   • 根据 agent-metadata-contract.md 中说明的 resource ID 和 connection string 字段接入 Application Insights
   • 使用推荐的 dashboard 或查询监控延迟、错误和吞吐

这样你就可以监控生产行为，并将其与部署变更进行关联分析。

Tracing 与基于 trace 的数据集创建

1. 打开 foundry-agent/trace/trace.md。
2. 按 workflow 执行：
   • 从 agents 收集 traces
   • 从 traces 中筛选并构建数据集，将其保存到 .foundry/datasets
   • 将这些数据集输入评估 workflow，进行更贴近真实流量的测试

当你希望将真实用户流量转化为评估场景时，这尤其有用。

部署与运行期问题排查

1. 打开 foundry-agent/troubleshoot/troubleshoot.md。
2. 按排障指南定位如下问题：
   • 部署失败和容器启动错误
   • endpoint、credentials 或 connections 配置错误
   • 配额或容量相关错误（结合 quota/quota.md 和 quota/references/*.md）

将这些指南与日志和 Application Insights 遥测结合使用，可帮助你快速诊断并解决问题。

配额、容量与优化

1. 打开 quota/quota.md 概览：
   • 配额在 Azure AI Foundry 中如何应用到模型和部署
   • 如何在不同环境和区域间规划容量
2. 查看 quota/references/ 目录中的说明：
   • capacity-planning.md – 帮助你根据使用情况为 agents 做容量预估
   • error-resolution.md – 将常见配额相关错误映射到推荐解决方案
   • optimization.md – 提供在配额限制下优化 workload 的建议

这些内容有助于你在规模化时避免配额“踩坑”，并保持 agents 的响应能力。

常见问题（FAQ）

使用 Azure AI Foundry 是否必须安装 microsoft-foundry？

不是。你可以直接通过 Azure portal、CLI 或 SDK 使用 Azure AI Foundry。microsoft-foundry 技能只是将最佳实践、workflow 和参考文档打包在一起，帮助你更一致地搭建项目、agents 和环境。

可以使用 microsoft-foundry 管理非 Foundry 的 Azure 服务吗？

当你的主要目标是 部署和运维 Azure AI Foundry agents 与项目 时，请使用此技能。针对通用 Web 应用、API 或其他 PaaS（如 App Service、Functions、通用容器）部署，请改用专门的 Azure 部署技能或官方部署指南。

microsoft-foundry 是否同时支持 prompt agents 和 hosted agents？

是的。该技能为两者都提供了专门内容：

• foundry-agent/create/create-prompt.md 覆盖 prompt agents。
• foundry-agent/create/create.md 和 foundry-agent/deploy/deploy.md 覆盖 hosted agents，包括容器化、ACR 以及容器生命周期管理。

microsoft-foundry 如何处理身份验证与安全？

安全与身份验证在 references/auth-best-practices.md 和 rbac/rbac.md 中有详细说明：

• 在生产环境使用 managed identities 和 Azure RBAC
• 将 DefaultAzureCredential 保留给本地开发
• 为 CI/CD 和本地数据中心环境选择合适的凭据类型

在接入 SDK 或 MCP 工具前，请先按这些文档做配置，以避免不安全或脆弱的实现方式。

一定要用 MCP 工具吗？能否只用 SDK？

文档在设计上 优先兼容 MCP 工具，同时在 references/sdk 目录中提供了 基于 SDK 的 fallback 方案。例如，create-prompt.md 说明了在无法使用 MCP 工具时，如何回退到 azure-ai-projects SDK。

如何判断我的 agent 项目结构是否正确？

请将项目与 references/agent-metadata-contract.md 做对照。确保：

• 在 agent 根目录下有 .foundry/ 目录
• 存在合法的 agent-metadata.yaml，包含环境和测试用例定义
• datasets/、evaluators/ 和 results/ 目录按说明存在

只要你遵守这份“契约”，其他 microsoft-foundry workflow 就能与你的项目结构保持一致。

microsoft-foundry 是否支持私有网络（VNet）部署？

支持。references/private-network-standard-agent-setup.md 中有详细说明：

• 所需的 VNet 和子网配置
• Foundry 资源与 VNet 之间的区域限制
• 如何使用官方 private-network standard agent setup 的 Bicep 模板

在必须保持流量走私有网络时，请将该文档与 references/standard-agent-setup.md 一起使用。

安装完成后，我在仓库中应该从哪里开始？

安装技能后，建议按以下顺序开始：

1. SKILL.md – 获取所有子技能的高层概览
2. project/create/create-foundry-project.md – 完成 Foundry 项目创建和配置
3. references/agent-metadata-contract.md – 标准化 agent 项目布局
4. foundry-agent/create/ 和 foundry-agent/deploy/ – 构建并部署你的第一个 agent

之后，可按需继续探索 eval-datasets、observe、trace、rbac 和 quota 等子目录内容。