microsoft-foundry

概要

microsoft-foundry スキルとは？

microsoft-foundry スキルは、Azure AI Foundry エージェントのエンドツーエンドのライフサイクルを通して案内する、ワークフローとリファレンスドキュメントのセットです。実運用で役立つデプロイと運用を重視しています。

• prompt エージェントとhosted エージェントの作成
• Docker イメージのビルドと Azure Container Registry (ACR) への push
• Azure AI Foundry へのエージェントのデプロイ
• projects, RBAC, quota, connections のセットアップ
• evaluation datasets の実行と agent-metadata.yaml の管理
• standard および private-network 構成のエージェントセットアップ
• observability, tracing, troubleshooting の有効化

コンテンツはすべて microsoft/azure-skills リポジトリ由来で、リポジトリ構造を解析しなくても Azure AI Foundry 上でエージェントを運用できるよう整理されています。

このスキルの対象者

microsoft-foundry は次のような方に向いています。

• Azure AI Foundry エージェントのデプロイと運用を担当する バックエンド/プラットフォームエンジニア
• プロトタイプを本番の Foundry プロジェクトに移行する AI/ML エンジニア
• 既存サービスや SDK、MCP ツールと Foundry エージェントを統合する 開発者
• RBAC、クォータ、プライベートネットワーク構成、環境セットアップまで責任を持つ 技術オーナー

App Service や Functions、一般的な Web アプリなどの、ベーシックな Azure インフラのデプロイだけが必要な場合は、このスキルは適していません。その場合は、より汎用的な Azure デプロイスキルを利用してください。

microsoft-foundry はどのような課題を解決する？

このスキルは、よくある次のような課題に対応するために設計されています。

• 「Foundry 用にエージェントのリポジトリ構造をどう設計すればいい？」
  .foundry/ の構成や agent-metadata.yaml のフィールドについては、references/agent-metadata-contract.md のガイダンスを参照してください。

• 「エージェントを毎回同じ手順で作成・デプロイするには？」
  foundry-agent/create と foundry-agent/deploy ワークフローを使うことで、prompt/hosted エージェントの作成、コンテナビルド、ACR への push、エージェントコンテナの起動までを一貫して実行できます。

• 「projects, connections, RBAC, quota はどう構成する？」
  project/create、rbac/rbac.md、quota/quota.md に従って、プロジェクトの作成、ロールの割り当て、キャパシティ計画を行ってください。

• 「エージェントの評価と観測はどう行う？」
  foundry-agent/eval-datasets、foundry-agent/observe、foundry-agent/trace を利用して、バッチ評価の実行、データセットと evaluator の管理、観測基盤との接続を行えます。

• 「standard と private-network 構成はどう切り分ければいい？」
  references/standard-agent-setup.md と references/private-network-standard-agent-setup.md を参照して、要件に合ったネットワークモデルを選定・構成してください。

microsoft-foundry がフィットするケース

このスキルを使うべきなのは、次のような場合です。

• Azure AI Foundry に prompt または hosted エージェントをデプロイしたい
• .foundry/agent-metadata.yaml を用いて エージェントプロジェクト構造を標準化したい
• MCP tools や Azure SDK を繰り返し使えるワークフローに組み込みたい
• エージェントワークロードの RBAC, quota, キャパシティ計画 を管理したい
• evaluation datasets を実行し、環境をまたいで結果を追跡したい
• Application Insights とトレースを利用した 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 です。

リポジトリ構成と主要フォルダー

スキルをインストールするか、リポジトリを開くと次のような構成が確認できます。

• SKILL.md – スキル全体のインデックスとサブスキル一覧
• foundry-agent/ – 個々のエージェント向けエンドツーエンドワークフロー
  • create/ – prompt エージェントまたは hosted エージェントの作成
  • deploy/ – コンテナや ACR を含むエージェントのビルドとデプロイ
  • eval-datasets/ – 評価データセットと評価実行の管理
  • invoke/ – 既存エージェントの呼び出し
  • observe/ – observability 設定とモニタリングワークフロー
  • trace/ – トレース収集とトレースからのデータセット生成
  • troubleshoot/ – 実行失敗時のトラブルシューティングガイド
• project/
  • create/ – Azure AI Foundry プロジェクトの作成と構成
  • 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（非分離）エージェントセットアップ
  • 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>）
   • standard 構成に必要な connections（Cosmos DB, Storage, Azure AI Search など）をリンク
3. project/connections.md を確認し、とくに standard agent setup を利用する場合は、thread storage、file storage、vector store の connections が正しく構成されているかチェックします。

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 とサブネットの要件（エージェント用サブネットと private endpoint 用サブネット）
   • Foundry リソースと VNet 間のリージョン整合性
   • private-network standard agent setup 向け公式 Bicep template の利用

コンプライアンスやネットワーク要件に合った構成を選定してから、エージェントの作成に進んでください。

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 エージェント向け）
   • environments.<name>.observability.*（Application Insights 用）
   • 評価バンドル用の environments.<name>.testCases[]

このファイルが環境ごとの設定の 単一の信頼できる情報源 となり、その存在と内容を前提として、microsoft-foundry の他のワークフローが動作します。

5. prompt エージェントまたは hosted エージェントを作成する

1. prompt エージェントの場合は、foundry-agent/create/create-prompt.md を開きます。

   • prompt エージェントと workflow の違いを理解
   • プロジェクトコンテキスト（endpoint、credentials）の解決手順に従う
   • MCP tools が利用できる場合はそれを使い、利用できない場合はドキュメント通りに azure-ai-projects SDK にフォールバック
   • エージェント名、model deployment、instructions に加え、必要に応じて tools（file search, code interpreter など）を指定

2. hosted エージェントの場合は、foundry-agent/create/create.md を開きます。

   • 新規エージェントを作るのか（greenfield）、既存プロジェクトを変換するのか（brownfield）を選択
   • サンプルパスに基づいてフレームワークと言語を選択（Python や C# の Microsoft Agent Framework、LangGraph など）
   • 必要に応じて foundry-samples リポジトリとの統合ガイドに従う

このステップが完了すると、Foundry 互換のエージェントプロジェクトがデプロイ可能な状態になります。

6. エージェントをビルドしてデプロイする

1. foundry-agent/deploy/deploy.md を開きます。
2. 次をカバーするワークフローに従います。
   • プロジェクトスキャンと環境変数の収集
   • Dockerfile の生成および hosted エージェント向けの 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 を解決
   • サンプルまたはカスタムのペイロードでエージェントを呼び出し
   • レスポンス、tools、state が期待どおりに動作しているか検証

この段階は、本格的な評価スイートを走らせる前のスモークテストに最適です。

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, トレース, トラブルシューティング

Observability とモニタリング

1. foundry-agent/observe/observe.md を開きます。
2. ガイドに従って observability を構成します。
   • agent-metadata-contract.md に記載されている resource ID や connection string フィールドを使って Application Insights を接続
   • 推奨のダッシュボードやクエリでレイテンシ、エラー、スループットを監視

これにより、本番環境での挙動をデプロイ変更と紐づけて追跡できるようになります。

トレースとトレースからのデータセット生成

1. foundry-agent/trace/trace.md を開きます。
2. ドキュメントのワークフローに従って次を実施します。
   • エージェントからトレースを収集
   • トレースを整理してデータセット化し、.foundry/datasets に保存
   • これらのデータセットを評価ワークフローに投入し、より実運用に近いテストを実施

実ユーザートラフィックを評価シナリオに変換したい場合に特に有効です。

デプロイやランタイムの問題をトラブルシュートする

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 – 想定利用状況に基づいてエージェントのキャパシティを見積もる際に役立つガイド
   • error-resolution.md – よくあるクォータ関連エラーと推奨される対処方法のマッピング
   • optimization.md – クォータの範囲内に収まるようワークロードをチューニングするための提案

これらのコンテンツによって、大規模運用時の想定外の制限を避け、エージェントの応答性を維持しやすくなります。

FAQ

Azure AI Foundry を使うのに microsoft-foundry は必須ですか？

いいえ、必須ではありません。Azure portal、CLI、SDK から直接 Azure AI Foundry を利用できます。microsoft-foundry スキルは、ベストプラクティス・ワークフロー・リファレンスを 1 つにまとめた構造化ガイドであり、プロジェクト・エージェント・環境をより一貫したやり方でセットアップできるようにするためのものです。

microsoft-foundry を Foundry 以外の Azure サービスに使えますか？

このスキルは、主に Azure AI Foundry のエージェントとプロジェクトをデプロイ・運用する ことを目的としています。Web apps, APIs その他の PaaS（App Service, Functions, 汎用コンテナなど）のデプロイが主用途であれば、専用の Azure デプロイスキルやガイドを利用してください。

microsoft-foundry は prompt エージェントと hosted エージェントの両方をサポートしていますか？

はい、両方に対応したコンテンツがあります。

• foundry-agent/create/create-prompt.md が prompt エージェント を扱います。
• foundry-agent/create/create.md と foundry-agent/deploy/deploy.md が hosted エージェント を扱い、コンテナ化、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 が利用可能な場合はそれを活用しつつ、利用できない場合には SDK ベースのフォールバックができる ように書かれています。references/sdk フォルダーに SDK ベースの手順をまとめています。たとえば create-prompt.md では、MCP tools がない場合に azure-ai-projects SDK にフォールバックする方法を説明しています。

自分のエージェントプロジェクト構造が正しいかどうかはどう確認できますか？

references/agent-metadata-contract.md に照らし合わせてチェックしてください。次の点を確認します。

• エージェントのルートに .foundry/ ディレクトリが存在する
• 環境と test cases を含む有効な agent-metadata.yaml がある
• ドキュメントどおりに datasets/, evaluators/, results/ フォルダーが用意されている

この契約に従っていれば、microsoft-foundry の他のワークフローはプロジェクトレイアウトと整合するよう設計されています。

private network (VNet) 構成でも microsoft-foundry は使えますか？

はい、利用できます。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 などに進んでください。