microsoft-foundry

概觀

什麼是 microsoft-foundry 技能？

microsoft-foundry 技能是一組精選的工作流程與參考文件，用來引導你完成 Azure AI Foundry 代理的完整生命週期。重點在於實務上的部署與營運操作：

• 建立 prompt 與 hosted 代理
• 建置 Docker 映像並推送到 Azure Container Registry (ACR)
• 將代理部署到 Azure AI Foundry
• 設定 projects、RBAC、配額與 connections
• 執行 evaluation datasets 並管理 agent-metadata.yaml
• 設定 standard 與 private-network 代理架構
• 啟用 observability、tracing 與疑難排解

所有內容都來自 microsoft/azure-skills 儲存庫，並以結構化方式整理，讓你不必反向拆解 repo 結構，就能在 Azure AI Foundry 上順利營運代理。

適合哪些人使用？

如果你符合以下情境，建議使用 microsoft-foundry：

• 後端或平台工程師，負責部署與營運 Azure AI Foundry 代理
• AI/ML 工程師，要把原型搬進正式的 Foundry 專案
• 開發人員，要將 Foundry 代理與既有服務、SDK 或 MCP 工具整合
• 技術負責人，需要規劃 RBAC、配額、私人網路與環境設定

如果你只需要基本的 Azure 基礎架構部署（App Service、Functions、一般 Web 應用），這個技能不是最佳選擇——應改用更通用的 Azure 部署技能。

microsoft-foundry 解決哪些問題？

這個技能是為了解決常見、反覆出現的問題而設計：

• 「我要怎麼為 Foundry 規劃代理的 repo 結構？」
  參考 references/agent-metadata-contract.md，了解 .foundry/ 的布局和 agent-metadata.yaml 欄位設計。

• 「我要怎麼一致化建立與部署代理？」
  使用 foundry-agent/create 和 foundry-agent/deploy 工作流程來建立 prompt/hosted 代理、建置容器、推送到 ACR 並啟動代理容器。

• 「我要怎麼設定 projects、connections、RBAC 和配額？」
  依照 project/create、rbac/rbac.md 與 quota/quota.md 的指引建立專案、指派角色並規劃容量。

• 「我要怎麼評估與觀察我的代理？」
  使用 foundry-agent/eval-datasets、foundry-agent/observe 與 foundry-agent/trace 來執行批次評估、管理 datasets 與 evaluators，並串接到 observability 資源。

• 「標準環境與私人網路架構要怎麼選與怎麼設？」
  參考 references/standard-agent-setup.md 和 references/private-network-standard-agent-setup.md 來選擇並設定正確的網路模型。

什麼情況下 microsoft-foundry 很適合？

在以下需求時建議使用本技能：

• 將 prompt 或 hosted 代理部署到 Azure AI Foundry
• 以 .foundry/agent-metadata.yaml 標準化 代理專案結構
• 將 MCP tools 與 Azure SDK 納入可重複使用的工作流程
• 管理代理工作負載的 RBAC、配額與容量規劃
• 執行 evaluation datasets 並跨環境追蹤結果
• 使用 Application Insights 與 trace 建立 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 的工作流程與參考內容就會在你的代理或工具環境中可用。安裝後的主要入口檔為 skills/microsoft-foundry 資料夾中的 SKILL.md。

儲存庫結構與主要資料夾

安裝技能或在 repo 中開啟後，你會看到類似的結構：

• SKILL.md – 技能總覽與子技能列表
• foundry-agent/ – 個別代理的端對端工作流程
  • create/ – 建立 prompt 或 hosted 代理
  • deploy/ – 建置與部署代理，包括容器與 ACR
  • eval-datasets/ – 管理評估 datasets 與評估執行
  • invoke/ – 呼叫既有代理
  • observe/ – observability 設定與監控工作流程
  • trace/ – 收集 trace 並從 trace 建立 datasets
  • troubleshoot/ – 執行失敗時的疑難排解指引
• project/
  • create/ – 建立與設定 Azure AI Foundry projects
  • connections.md – project 層級 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 – 標準（非隔離）代理設定
  • private-network-standard-agent-setup.md – VNet/private-link 設定
  • sdk/ – MCP tools 不可用時的 SDK 操作參考

建議先從 SKILL.md 了解各子技能，再進入對應情境的資料夾。

快速開始工作流程：從專案到已部署的代理

本節提供一條實務路徑，示範如何使用 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>）
   • 依標準架構需求連結必要的 connections（Cosmos DB、Storage、Azure AI Search 等）
3. 檢視 project/connections.md，確認 thread storage、file storage 與 vector store 的 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 與開發環境選擇合適的憑證類型

這能確保部署與代理操作在沒有硬編碼密碼的情況下，仍可穩定完成驗證。

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 subnet 與 private endpoint subnet）
   • Foundry 資源與 VNet 之間的區域（region）對齊
   • 如何使用官方 Bicep template 來設定 private-network standard agent 架構

先依你的法遵與網路需求選定架構，再進入代理建立步驟。

4. 標準化代理專案結構

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 的工作流程都假設它存在且內容正確。

5. 建立 prompt 或 hosted 代理

1. 對於 prompt agents，開啟 foundry-agent/create/create-prompt.md：

   • 了解 prompt agents 與 workflows 的差別
   • 依步驟取得專案脈絡（endpoint、credentials）
   • 優先使用 MCP tools，如無法使用則依文件改用 azure-ai-projects SDK
   • 提供代理名稱、model deployment、instructions 以及選用工具（file search、code interpreter 等）

2. 對於 hosted agents，開啟 foundry-agent/create/create.md：

   • 選擇是建立新代理（greenfield）還是將既有專案轉換（brownfield）
   • 依範例路徑選擇框架與語言（如 Python 或 C# 的 Microsoft Agent Framework 或 LangGraph）
   • 依指引在需要時整合 foundry-samples 儲存庫

完成此步驟後，你應該會有一個符合 Foundry 的代理專案，準備進行部署。

6. 建置並部署代理

1. 開啟 foundry-agent/deploy/deploy.md。
2. 依工作流程操作，內容涵蓋：
   • 專案掃描與環境變數收集
   • 為 hosted agents 產生 Dockerfile 並使用 docker / az acr
   • 使用 agent_update、agent_container_control、agent_container_status_get 等 MCP tools
   • 建立或更新部署，並啟動/停止代理容器
3. 在不先閱讀此指引前，請勿單獨執行 azd up、azd deploy、az acr build 或 docker build——本技能會將這些指令整合為一條完整的部署管線。

完成後，你的代理應該已部署，並可透過 Azure AI Foundry 進行存取。

7. 呼叫並測試代理

1. 開啟 foundry-agent/invoke/invoke.md。
2. 依內容說明進行：
   • 透過 agent-metadata.yaml 解析正確的環境與 endpoint
   • 以範例或自訂 payload 呼叫代理
   • 確認回應、工具與狀態的行為符合預期

此階段很適合進行 smoke test，再進入完整評估流程。

8. 進行評估與迭代

1. 開啟 foundry-agent/eval-datasets/eval-datasets.md。
2. 依指引操作：
   • 在 .foundry/datasets 與 .foundry/evaluators 下管理 datasets 與 evaluators
   • 使用 agent-metadata.yaml 中的 testCases 定義執行評估工作流程
   • 將輸出存放在 .foundry/results，並依環境或代理版本比較結果
3. 持續調整 prompts 或 instructions 並重複評估，以長期追蹤品質改善。

Observability、Tracing 與疑難排解

Observability 與監控

1. 開啟 foundry-agent/observe/observe.md。
2. 依指引設定 observability：
   • 依 agent-metadata-contract.md 中說明的 resource ID 與 connection string 欄位設定 Application Insights
   • 使用建議的 dashboard 或查詢來監控延遲、錯誤與吞吐量

這有助於你觀察正式環境的行為，並與部署變更進行關聯分析。

Tracing 與從 traces 建立 datasets

1. 開啟 foundry-agent/trace/trace.md。
2. 依工作流程操作：
   • 收集代理的 traces
   • 從 traces 挑選並整理 datasets，存放於 .foundry/datasets
   • 將這些 datasets 輸入評估工作流程，進行更貼近真實流量的測試

當你想將實際使用者流量轉成評估情境時，這會特別有幫助。

部署與執行階段的疑難排解

1. 開啟 foundry-agent/troubleshoot/troubleshoot.md。
2. 依疑難排解指南處理下列常見問題：
   • 部署失敗與容器啟動錯誤
   • endpoint、credentials 或 connections 設定錯誤
   • 配額或容量錯誤（並交叉參考 quota/quota.md 與 quota/references/*.md）

請搭配記錄檔與 Application Insights telemetry，一起診斷並排除問題。

配額、容量與最佳化

1. 開啟 quota/quota.md 了解以下主題：
   • Azure AI Foundry 如何將配額套用到模型與部署
   • 如何在多個環境與區域之間規劃容量
2. 檢視 quota/references/ 中的檔案：
   • capacity-planning.md – 協助你依使用量預估代理所需容量
   • error-resolution.md – 對應常見配額相關錯誤與建議解法
   • optimization.md – 提供如何微調工作負載以符合配額限制的建議

透過這些內容，你可以在放大規模時避免意外狀況，並維持代理的回應效率。

常見問題（FAQ）

使用 Azure AI Foundry 一定要安裝 microsoft-foundry 嗎？

不需要。你可以直接透過 Azure 入口網站、CLI 或 SDK 使用 Azure AI Foundry。microsoft-foundry 技能的價值在於將最佳實務、工作流程與參考文件整理在同一處，幫助你更一致地設定專案、代理與環境。

可以用 microsoft-foundry 來操作非 Foundry 的 Azure 服務嗎？

本技能主要適用於 部署與營運 Azure AI Foundry 代理與專案。若你要的是一般 Web apps、API 或其他 PaaS 服務（App Service、Functions、一般容器）的部署，建議改用專門的 Azure 部署技能或官方指引。

microsoft-foundry 是否同時支援 prompt 與 hosted 代理？

是的。本技能針對兩種代理都提供專門內容：

• 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 tools 前先閱讀這些文件，避免導入不安全或脆弱的設定。

一定要用 MCP tools 嗎？可以只用 SDK 嗎？

內容撰寫時假設 在有 MCP tools 時優先使用，但也在 references/sdk 資料夾中提供了 純 SDK 的替代方案。例如，create-prompt.md 就說明了在 MCP tools 不存在時，如何改用 azure-ai-projects SDK。

要怎麼確認我的代理專案結構是否正確？

請將專案與 references/agent-metadata-contract.md 進行比對，並確認：

• 在代理根目錄有 .foundry/ 資料夾
• 具備有效的 agent-metadata.yaml，包含環境與測試案例
• 如文件所述，設有 datasets/、evaluators/ 與 results/ 資料夾

只要遵循這份合約，其餘 microsoft-foundry 的工作流程就能與你的專案結構正確對應。

microsoft-foundry 能搭配私人網路（VNet）架構使用嗎？

可以。references/private-network-standard-agent-setup.md 提供詳細說明：

• 必要的 VNet 與子網路設定
• Foundry 資源與 VNet 之間的區域限制
• 如何使用官方的 private-network standard agent setup Bicep template

若你必須將流量限制在私人網路中，請搭配 references/standard-agent-setup.md 一起參考。

安裝後在儲存庫裡應該從哪裡開始看？

安裝技能後，建議依序從下列檔案開始：

1. SKILL.md – 了解所有子技能的高階總覽
2. project/create/create-foundry-project.md – 建立並設定你的 Foundry 專案
3. references/agent-metadata-contract.md – 統一代理專案的結構
4. foundry-agent/create/ 與 foundry-agent/deploy/ – 建置並部署你的第一個代理

之後可依情境需要，進一步使用 eval-datasets、observe、trace、rbac 與 quota 等內容。