Microsoft Foundry Toolkit for Visual Studio Code を使用してホストされるエージェントを作成する

Microsoft Foundry Toolkit for Visual Studio Codeを使用して、Microsoft Agent Framework サンプルからコードベースのワークフローを作成します。 Agent Inspector を使用してローカルで実行し、そのソースコードをホストされたエージェントとして Foundry Agent Service にデプロイします。コードとその依存関係を維持します。 Foundry は、ホスティングインフラストラクチャとスケーリングを管理します。

ホストされたワークフローは、コード内のエージェントを調整します。これらは、廃止される Foundry 宣言型ワークフローサービスとは異なります。その他の作成ルートについては、「エージェントの作成」を参照してください。

前提条件

Visual Studio Code 用 Microsoft Foundry Toolkit をインストールします。
デプロイされたモデルを含む Foundry プロジェクトを選択します。サポートされているホステッドエージェントリージョンを使用します。
モデルを使用し、ホストされているエージェントをデプロイするためのアクセス許可。ソースコードのデプロイの場合、project スコープの Foundry Project Manager ロールには、エージェント操作とロールの割り当てアクセス許可が含まれます。「ホステッドエージェントのアクセス許可」を参照してください。

Important

Foundry RBAC ロールの名前が最近変更されました。 Foundry User, Foundry Owner, Foundry Account Owner、および Foundry Project Manager は、以前は、AZURE AI ユーザー、Azure AI 所有者、Azure AI アカウント所有者、および AZURE AI Project Manager という名前でした。名前の変更がロールアウトされている間、以前の名前が表示される場合があります。ロール ID とコアアクセス許可は、名前の変更によって変更されません。
この記事のローカル認証の手順には、Azure CLI を使用します。
コンテナーのデプロイの場合、Azure Container Registryセットアップで必要なレジストリとイメージのアクセス。これらのレジストリ要件は、ソースコードのデプロイには適用されません。

サンプルに構成されているホストランタイム用の Python 3.13
Visual Studio CodeのPython拡張機能。

.NET 10 SDK。
Visual Studio Code 用の C# 開発キット

メインデプロイパスでは、リモート パッケージモードの Code が使用され、ローカル Docker ビルドは必要ありません。ローカル実行は引き続き Foundry にモデル要求を送信し、料金が発生する可能性があります。使用する機能については、サービスの制限と可用性とツールキットのリリースノートを確認してください。

ホストされるエージェントワークフローを作成する

応答プロトコルを使用する Agent Framework サンプルを選択します。最初に別のプロンプトエージェントを作成する必要はありません。サンプル、エージェントビルダー、およびCopilot支援コーディングを比較するには、「作成ルートの選択」を参照してください。

ライター、校閲者、フォーマッタをチェーンする マルチエージェントワークフロー (エージェントフレームワーク) を使用します。最終的な応答はフォーマッタから取得されます。完全な実装とそのモデルガイダンスについては、Python ワークフローサンプルを確認してください。

翻訳ワークフローを使用します。これは、英語からフランス語、フランス語からスペイン語、スペイン語から英語の 3 つの翻訳エージェントを連結します。完全な実装については、 C# ワークフローサンプルを確認してください。

Foundry Toolkit ビューで、開発者ツール>ビルド>エージェントの作成を選択します。
[ サンプルからエージェントをコーディングする] で、[ すべてのサンプルを参照] を選択します。
サンプルからのホスト型エージェントの作成で、言語、フレームワーク、エージェントフレームワーク = プロトコルの種類 = Responses でフィルター処理します。 workflow を検索します。

次のスクリーンショットは、 Basic Hosted Agent が例として選択されているギャラリーを示しています。このガイドでは、代わりに言語のワークフローサンプルを選択します。
言語のワークフローサンプルを選択します。
次へを選択します。
[ 作成] で、 ワークスペースフォルダーを選択します。フォルダーに既にファイルが含まれている場合は、新しい子フォルダーの フォルダー名 を入力します。
[Environment Setup]$環境セットアップ$ が表示されたら、Microsoft Foundry で [Setup]$セットアップ$ を選択し、サブスクリプションとプロジェクトを選択します。既定のプロジェクトが既に選択されている場合、フォームはそのプロジェクトを使用します。
既存の互換性のある モデルデプロイを選択します。

次のスクリーンショットは、ローカルパスが非表示になっているプロジェクト設定の例を示しています。独自の宛先と、サンプルに必要なモデルデプロイを使用します。
保存先を確認し、作成を選択します。
Visual Studio Codeで生成されたプロジェクトを開き、そのREADME.mdを読み取る。

[Create Agent] の Agent Framework、Copilot SDK、および LangGraph の各タイルをクリックすると、hello-world スターターが選択された状態で [作成] タブが開きます。 [ すべてのサンプルを参照] を使用して、これらのスターターの 1 つではなくワークフローを選択します。マイ リソース>Agents>Hosted Agent>Add Hosted Agent からギャラリーを開くこともできます。

サンプルの名前と内容は、カタログで変更できます。一部のバージョンでは、これらのサンプルワークフローにラベルが付 けられます。サンプルの GitHub リンクを使用して、目的のワークフローを選択したことを確認します。

ここでスキップすると 、モデルの設定を完了せずにコードが生成されます。選択した場合は、サンプルを実行する前に、必要なプロジェクトとモデルの値を構成します。 新しいモデルをデプロイして使用する (提供されている場合) は、ホストされるエージェントではなく、モデルのデプロイをプロビジョニングします。ローカルプロジェクトファイルを作成しても、エージェントはデプロイされません。

ローカルプロジェクトを構成する

azure.yamlを含むフォルダーは、ワークスペースルートとして開いたままにしておきます。そのファイル内の hosted-agent サービスの project パスを調べて、そのソースディレクトリを見つけます。

アーティファクト	Purpose
`azure.yaml`	ホステッドエージェントサービス、ソースディレクトリ、ランタイム、プロトコル、およびデプロイ設定を宣言します。
`main.py`またはソースディレクトリ内の`Program.cs`	ワークフローを実装し、Responses サーバーを起動します。
`requirements.txt` または `.csproj` ファイル	選択した言語の依存関係を宣言します。
`.env` ソースディレクトリ内	ローカルプロジェクトとモデルの値を保持します。ツールキットは、サンプルがそのファイルを提供するときに `.env.example` から作成します。
`.vscode/launch.json` と `.vscode/tasks.json`	ローカルサーバー、デバッガーの添付ファイル、およびエージェントインスペクターを構成します。

サンプルレイアウトは変更される可能性があります。コードと環境ファイルがワークスペースのルートにあると想定するのではなく、生成された README.md と azure.yaml を使用します。

依存関係のインストール

生成されたサンプルの依存関係ファイルを使用します。選択したインタープリターまたは SDK とそのランタイム構成との整合性を保ちます。

コマンドパレットから Python: 環境の作成... を実行して仮想環境を作成するか、Python: インタープリターを選択して既存の Python 3.13 環境を選択します。環境のセットアップと選択については、Visual Studio CodeのPython環境を参照してください。
その環境を有効化した状態でターミナルを開いてください。 main.pyとrequirements.txtを含むソースディレクトリに移動します。
サンプルのパッケージをインストールします。
```
python -m pip install -r requirements.txt
```
要件には、生成された F5 構成で使用される debugpyが含まれます。リファレンス: Python ワークフローの依存関係。

C# を実行する: コマンドパレットからワークスペースの要件を確認します。
ターミナルで、 .csproj ファイルを含むソースディレクトリに変更し、そのパッケージを復元します。
```
dotnet restore
```
リファレンス: dotnet restore。

デバッガーの制御と構成については、Visual Studio Codeでの C# デバッグに関するページを参照してください。

プロジェクトとモデルを設定する

ソースディレクトリの .env ファイルを確認します。存在しない場合は、サンプルに必要な値を使用して作成します。

Variable	価値
`FOUNDRY_PROJECT_ENDPOINT`	プロジェクトエンドポイント ( `https://<resource-name>.services.ai.azure.com/api/projects/<project-name>`形式)。
`AZURE_AI_MODEL_DEPLOYMENT_NAME`	モデルのカタログ名だけでなく、そのプロジェクト内のモデル配置の名前。

どちらのワークフローサンプルも、起動時に .env 読み込まれます。プロジェクトエンドポイントは、Azure OpenAI アカウントエンドポイントではありません。ファイルをソース管理から除外し、アプリケーションコードに資格情報を配置しないでください。

ローカルで認証する

サンプルでは、 DefaultAzureCredentialを使用します。 Azure CLI資格情報パスの場合は、プロジェクトのモデルにアクセスできるアカウントでサインインします。

az login

リファレンス: Azure CLIを使用してサインインします。

ツールキットのサインインでは、拡張機能の操作用にプロジェクトが選択されます。ローカルエージェントプロセスには、サポートされている資格情報も必要です。その他のオプションについては、Pythonの DefaultAzureCredential または.NETの資格情報チェーンに関するページを参照してください。

ホストされているワークフローをローカルで実行する

生成されたデバッグ構成を使用して HTTP サーバーを起動し、 Agent Inspector を開きます。エージェントインスペクターを開くだけでは、サーバーは起動しません。

次のテスト要求を使用します。 Create a slogan for a new electric SUV that is affordable and fun to drive. ワークフローは、ライター、校閲者、フォーマッタの完了後に書式設定されたスローガンを返します。

次のテスト要求を使用します。 The quick brown fox jumps over the lazy dog. ワークフローは翻訳チェーンを実行し、応答を返します。

生成されたプロジェクトワークスペースに戻ります。
実行を検査する場合は、ワークフローコードにブレークポイントを設定します。
F5 キーを押します。メッセージが表示されたら、[ ローカルエージェント HTTP サーバーのデバッグ] を選択します。
サーバーが起動し、 エージェントインスペクター が開くのを待ちます。
サンプルのテスト要求を送信します。
応答を検査し、別の要求で繰り返します。ブレークポイントを設定した場合は、値を調べて実行を続行します。

サンプルが動作したら、ワークフローを変更し、ローカルテストを繰り返します。ツールを追加する場合は、実際のツールの結果を必要とする要求を送信し、呼び出しを検査します。モデルのみの回答またはモック応答では、ライブツールが動作することを証明しません。

このスクリーンショットには、ツールが有効なローカルエージェントが示されています。どちらのワークフローサンプルも示されていません。 Agent Inspector では、応答とツール呼び出しが待機時間のウォーターフォールと実行タイムラインと共に表示されます。使用可能な検査の詳細は、実行中のエージェントとそのインストルメンテーションによって異なります。

GitHub Copilotを使用する場合は、Copilot Chatで/validate-microsoft-foundry-hosted-agentを実行して、Foundry のベストプラクティスに照らしてプロジェクトを確認できます。このチャットコマンドはレポートを開きます。これはターミナルコマンドでも、ワークフローの実行に代わるものでもない。

生成されたタスクは、エージェントサーバーのポート 8088 を使用します。 Pythonデバッグでは、ポート 5679も使用されます。スタートアップでポートの競合が報告された場合は、所有している競合するプロセスを停止するか、生成されたタスク構成を一貫して調整します。

デバッガーなしで実行する

手動で実行するには、依存関係、環境値、および使用可能な資格情報を使用して、サンプルのソースディレクトリAzureターミナルを開きます。

python main.py

リファレンス: Python ワークフローエントリポイント。

ローカルサーバーの HTTP アドレスを設定し、実行します。

$env:ASPNETCORE_URLS = "http://localhost:8088"
dotnet run

set ASPNETCORE_URLS=http://localhost:8088
dotnet run

export ASPNETCORE_URLS="http://localhost:8088"
dotnet run

リファレンス: ASP.NET Core サーバー URL と dotnet run。

次に、コマンドパレットから Foundry Toolkit: Open Agent Inspector を実行し、ポート 8088でローカルサーバーに接続します。 pythonまたはdotnet runを使用してサンプルを実行すると、コンテナーではなくローカルプロセスが開始されます。

ホストされたエージェントワークフローの実行を視覚化する

Agent Inspector を使用して、実行中のエージェントが出力するイベント、応答、およびツール呼び出しを検査します。ランタイムがワークフローイベントを出力する場合は、ワークフローの視覚化を使用して一連の手順を調べます。

使用可能な詳細は、サンプルのインストルメンテーションによって異なります。ランタイム固有の要件については、サンプルのテレメトリのセットアップ手順に従ってください。

これらの手順では、応答プロトコルを使用します。その他のサンプルには、プロトコルに一致するクライアントが必要です。HTTP 呼び出しビューは WebSocket クライアントではなく、Python アクティビティサンプルでは Microsoft 365 Agents Playground を使用します。選択したサンプルのローカルテスト手順に従います。構成でプロトコル名を変更しても、そのプロトコルはサーバーに追加されません。「ホストされるエージェントプロトコルの選択」を参照してください。

ホストされるエージェントをデプロイする

ローカルワークフローが想定どおりに動作したら、プロジェクトワークスペースからデプロイします。 Pythonと C# では、デプロイ手順を共有します。 コードとリモート パッケージモードから開始してソースをアップロードし、Foundry が依存関係を復元できるようにします。

デプロイ構成を準備する

hosted-agent サービスを確認して azure.yamlに保存します。サンプルのプロトコル構成を保持し、そこでモデルのデプロイとその他の必要なランタイム設定を宣言します。

デプロイは、ソースディレクトリの .env またはプロセス環境から宣言された環境の値を解決します。すべてのローカル .env エントリが転送されるわけではありません。プラットフォームは、 FOUNDRY_PROJECT_ENDPOINTなどの予約済みランタイム値を提供します。デプロイ設定として再宣言しないでください。プラットフォームによって挿入される環境変数を参照してください。

パッケージ化する前に、ソースディレクトリの無視ルールを確認します。 .env、資格情報、仮想環境、キャッシュはパッケージから除外します。 ZIP デプロイの場合、ソースルート .agentignore は .gitignore と .dockerignoreのルールを置き換えるので、そのファイルを追加する場合は、必要な除外を保持します。

Important

シークレットをコミットしたりパッケージ化したりしないでください。ローカルサインインでは、デプロイされたエージェントにユーザーのアクセス許可は転送されません。エージェントのランタイム ID とサポートされている接続のアクセスを構成します。「ホステッドエージェントのアクセス許可」を参照してください。

リモートパッケージモードでソースをデプロイする

ツールキットがサービス構成を読み取り、そのソースディレクトリを見つけられるように、生成されたワークスペースルートを使用します。

ローカルデバッグセッションを停止します。
[Developer Tools>Build>Deploy to Microsoft Foundry を選択します。コマンドパレットから Foundry Toolkit: Deploy Hosted Agent を実行することもできます。

$[Foundry Toolkit Developer Tools] セクションの [Build]$ビルド$ の [Deploy to Microsoft Foundry]$Foundry へのデプロイ$ のスクリーンショット。$
Foundry Project セットアップが表示されたら、サブスクリプションとprojectを選択し、[次へ] を選択します。それ以外の場合は、既定のプロジェクトが目的の宛先であることを確認します。
[基本] で、[配置方法としてコード] を選択し、[パッケージモードとしてリモート] を選択します。
[ 新しいエージェント ] を選択し、[ Hosted Agent Name]$ホストされたエージェント名$ を入力します。デプロイされたエージェントを更新するには、[ 既存のエージェント ] を選択し、代わりにそのエージェントを選択します。
次へを選択します。
[確認とデプロイ] で、サンプルに対して言語、ランタイムバージョン、エントリポイント、CPU とメモリを確認します。ソースディレクトリがサービスの project パスと一致することを確認します。

次のスクリーンショットは、これらのワークフローサンプルの設定ではなく、Python 3.14 とそのエントリポイントが非表示になっている例を示しています。 Pythonの場合は、python3 main.pyで Python 3.13 を使用します。 C# の場合は、.NET 10 と、生成されたプロジェクトに対して検出されたエントリポイントを使用します。
展開を選択します。通知と出力の進行状況に従います。
デプロイされたワークフローのテストに進みます。

サンプル構成とローカル環境にランタイムを一致させます。ウィザードの既定値であるため、別のランタイムを受け入れないでください。

ツールキットは、フォームを送信するときにデプロイの選択肢を保存します。これらのローカル設定では、クラウドデプロイが成功したことを証明するわけではありません。既存のエージェントを更新すると、以前のバージョンを変更するのではなく、新しいバージョンが作成されます。

別の ZIP パッケージモードを選択する

ツールキットには、次のソースコードパッケージオプションが用意されています。

パッケージモード	何が起きるか	準備する内容
リモート	ツールキットパッケージソース。 Foundry は、プロビジョニング中Python要件または.NET プロジェクトを復元します。	ソース、依存関係宣言、および互換性のあるエントリポイント。
バンドル	ツールキットはソースをステージングし、ZIP を作成する前にパッケージコマンドをローカルで実行します。 Foundry は準備されたパッケージを実行します。	互換性のある Linux の依存関係と、コマンドに必要なローカルツール。既定の Python コマンドは、互換性のある依存関係を`packages/`にインストールします。.NET コマンドは発行出力を作成します。

選択可能な ZIP ランタイムは、Python 3.13、Python 3.14、.NET 10 です。ランタイムをコードと依存関係と一致させます。レイアウト、制限、およびサービスの要件については、「ソースコードからのデプロイ」を参照してください。ランタイムサポートポリシーについては、サポートされている hosted-agent ランタイムに関するページを参照してください。

コンテナーイメージをデプロイする

カスタムランタイムイメージが必要な場合、または互換性のあるイメージが既にある場合は、[基本] の [コンテナー] を選択します。

レジストリの選択	ツールキットの動作
既定の ACR	選択したプロジェクトのレジストリを作成または再利用し、Azure Container Registry (ACR) を介してイメージをビルドしてプッシュします。
カスタム ACR	選択した既存のレジストリを使用し、ACR を介してイメージをビルドしてプッシュします。
カスタム ACR イメージ	ソースをビルドまたはプッシュせずに、事前構築済みの ACR イメージ参照を使用します。

ビルドオプションについては、デプロイする前に Dockerfile とビルドコンテキストを確認してください。ウィザードで Dockerfile を生成する場合は、ファイルを確認し、[ 続行してデプロイ] を選択します。これらのオプションでは、ローカル Docker ビルドではなく、リモート ACR ビルドが使用されます。

カスタムレジストリオプションでは、選択したサブスクリプションのレジストリが使用されます。カスタムレジストリのビルドパスにはパブリックネットワークアクセスが必要です。事前構築済みイメージパスには、個別のプライベートネットワーク要件があります。イメージを選択しても、ネットワーク接続は構成されません。

カスタムレジストリを使用する前に、コンテナーの要件とプライベートネットワークのガイダンスを確認します。これらのデプロイは、廃止されたAzure Container Appsホステッドエージェントパスではなく、Foundry Agent Service を対象とします。古いエージェントを移動するには、 hosted-agent プレビューから Migrate に従います。

デプロイされたワークフローをテストする

作成リクエストが成功しても、ランタイムの準備が整っていることや、そのモデルやツールにアクセスできることは証明されません。デプロイされた正確なバージョンをテストします。

[ My Resources>Agents>Hosted Agent] で、エージェント名を選択します。
デプロイした番号付きバージョンを選択します。
[詳細] で、エージェントが実行されていることを示すデプロイの状態を待ちます。失敗した場合は、再試行する前にデプロイの出力を調べます。
Playground を開き、ローカルでテストしたのと同じ要求を送信します。
応答を確認します。ツールを追加した場合は、それらのツールを必要とする要求を送信し、呼び出しを検査します。

ローカル実行とクラウド実行では、さまざまな資格情報、依存関係環境、およびネットワークパスが使用されます。ローカル応答が成功しても、リモート応答の成功は保証されません。

デプロイされたエージェントを検査して更新する

リモートプレイグラウンドを使用して、デプロイされたエージェントをテストおよび検査します。 Agent Inspector を使用したローカルテストとは異なり、このプレイグラウンドの要求は Foundry でホストされているエージェントに対して実行されます。

Foundry Toolkit で、Developer Tools>Build>Hosted Agent Playground を選択します。
[ Hosted Agent]$ホストされたエージェント $ ドロップダウンで、デプロイされたエージェントと検査するバージョンを選択します。 Playground を開いて要求を送信し、応答とセッションの詳細を表示します。

次のスクリーンショットは、デプロイされたエージェントの応答を示しています。どちらのワークフローサンプルの出力も想定されていません。エージェントとセッションの識別子は非表示になります。

これらのコントロールを使用して、エージェントを検査および更新します。使用可能なタブは、プロトコルと接続されたサービスによって異なります。

タスク	アクション
デプロイの詳細を確認	状態、構成、およびコピー可能なエンドポイントの詳細を開きます。
バージョンをテストする	プレイグラウンドリクエストの番号付きバージョンを選択します。自動は、サービスエンドポイントのバージョンの選択に従います。これは必ずしも最新バージョンではありません。ピッカーは、他のクライアントのルーティングを変更しません。
ランタイムログを確認する	セッションを開き、セッションを選択し、そのログを表示します。ランタイムログにはセッションが必要です。ビルド出力は別です。ログストリームを停止したり、要求を取り消したりしても、ホストされているエージェントは停止されません。
デプロイされたコードを取得する	ZIP 展開には、コード資産のダウンロードを使用します。イメージ配置では、ダウンロード可能なソースプロジェクトではなく、イメージ参照が公開されます。
動作を更新する	ローカルコードを編集してテストし、既存のエージェントでデプロイ手順を繰り返して新しいバージョンを作成します。

使用可能な場合は 、トレース と評価を使用して、1 つの成功した応答を超えた調査と品質の測定を行います。 hosted-agent tracing および hosted-agent evaluation の前提条件に従ってください。

デプロイにより、エージェントはプログラムで使用するためのエンドポイントが提供されます。 API アクセスには、別の発行手順は必要ありません。 Teams またはMicrosoft 365への発行は別のタスクです。現在のエージェントエンドポイントと発行モデルを参照してください。

Troubleshooting

報告されたエラーとサンプル構成を使用して、失敗した手順を特定します。

症状:	アクション
パッケージが見つからないため、ローカルスタートアップが失敗します。	選択したインタープリターまたは SDK を確認し、サンプルのソースディレクトリから依存関係をインストールします。
プロジェクトのエンドポイントまたはモデルが見つかりません。	`FOUNDRY_PROJECT_ENDPOINT` および `AZURE_AI_MODEL_DEPLOYMENT_NAME` を確認します。アカウントエンドポイントまたはモデルカタログ名に置き換えないでください。
認証または承認が失敗します。	ローカル資格情報とプロジェクトアクセスを確認します。デプロイとランタイム ID の要件について、ホストされているエージェントのアクセス許可を確認します。
エージェントインスペクターは接続できません。	サーバーが起動し、ポート `8088` が使用可能であることを確認します。インスペクターを開くだけでは、サーバーは起動しません。
デプロイが失敗します。	デプロイエラーを確認し、出力をビルドします。コードについては、ランタイム、エントリポイント、パッケージモード、および無視ルールを確認します。コンテナーの場合は、イメージとレジストリのアクセス許可を確認します。
ローカル応答は機能しますが、デプロイされたバージョンは失敗します。	デプロイされた環境と ID のアクセス許可をローカル構成と比較します。デプロイされた正確なバージョンを再テストします。

リソースをクリーンアップする

完了したら、ローカルデバッグセッションを停止します。デプロイされたテストエージェントが不要になった場合は、「ホストされたエージェントの管理」に従って削除します。

エージェントを削除すると、そのバージョンが削除され、アクティブなセッションが終了します。関連付けられているすべてのAzure リソースが削除されるわけではありません。

この演習用に作成された、他のアプリケーションで使用されていないクラウドリソースのみを削除します。共有 Foundry プロジェクト、モデルデプロイ、またはコンテナーレジストリは削除しないでください。

ワークフローを拡張するには、次のガイドを使用します。

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-09-17