クイック スタート: 最初のホステッド エージェントをデプロイする

• Azure Developer CLI バージョン 1.24.0 以降

• Visual Studio Code
• Microsoft Foundry Toolkit for Visual Studio Code 拡張機能

必要なアクセス許可

ホストされたエージェントを作成してデプロイするには、プロジェクトの範囲でAzureのAIプロジェクトマネージャーが必要です。 このロールには、エージェントを作成するためのデータ プレーンのアクセス許可と、プラットフォームで作成されたエージェント ID に Azure AI ユーザー ロールを割り当てる機能の両方が含まれます。 実行時にモデルやアーティファクトにアクセスするには、プロジェクト内の AzureのAIユーザーとしてのエージェントの識別情報が必要です。

azd または VS Code 拡張機能を使用する場合、ツールは次のようなほとんどの RBAC 割り当てを自動的に処理します。

Foundry Project のマネージド ID に、使用するAzure Container Registryに対する ACR プル ロールがあることを確認します。 所有者または "ユーザー アクセス管理者" アクセス権を持っている場合は、ツール azd/vscode でもこの割り当てを行うことができます。 プラットフォームで作成されたエージェント ID の Azure AI ユーザー(ランタイムモデルとツールアクセスのため)

手順 1: サンプル プロジェクトを設定する

Azure Developer CLI エージェント拡張機能をインストールし、新しいホステッド エージェント プロジェクトを初期化します。

1. Azure Developer CLI の ai agent 拡張機能をインストールします。

   azd ext install azure.ai.agents
   

   拡張機能がインストールされていることを確認するには、次を実行します。

   azd ext list
   

2. 空のディレクトリで新しいホステッド エージェント プロジェクトを初期化します。

   azd ai agent init
   

   対話型フローでは、次の構成について説明します。

   • Language — サンプル コードを使用するプログラミング言語 (C# または Python) を選択します。
   • エージェント テンプレート - 開始するサンプルを選択します。
   • Model Configuration - Foundry に新しいモデルをデプロイする場合、または既存の Foundry Projectの既存のモデルを使用する場合に選択します。
   • Azure サブスクリプション - Foundry リソースを作成するサブスクリプションを選択します。
   • 場所 - リソースのリージョンを選択します。
   • モデル SKU — リージョンとサブスクリプションで使用可能な SKU を選択します。
   • デプロイ名 - モデル デプロイの名前を入力します。
   • コンテナー サイズ — CPU とメモリの割り当てを選択するか、既定値をそのまま使用します。

   重要

   ツールでサンプルを選択し、MCP サーバーを使用していない場合は、 agent.yaml ファイル内の次の行をコメント アウトまたは削除します。

   - name: AZURE_AI_PROJECT_TOOL_CONNECTION_ID
     value: <CONNECTION_ID_PLACEHOLDER>
   

   ヒント

   CI/CD パイプラインや SSH セッションなどの非対話型環境で実行している場合は、--no-promptと共に azd ai agent init フラグを使用します。 また、対話型プロンプトに応答するのではなく、必要なすべての値をコマンド ライン フラグとして指定する必要があります。

3. 必要なAzure リソースをプロビジョニングします。

   メモ

   リソース のプロビジョニングには、Azure サブスクリプションContributor アクセス権が必要です。

   azd provision
   

   このコマンドには数分かかり、次のリソースが作成されます。

   リソース	目的	コスト
   リソース グループ	関連するすべてのリソースを同じ領域に整理します	コストなし
   モデルの展開	エージェントによって使用されるモデル	Foundry の価格を参照してください
   Foundry プロジェクト	エージェントをホストし、AI 機能を提供する	使用量に基づく; Foundry pricingを参照してください
   Azure Container Registry	エージェント コンテナー イメージを格納します	Basic レベル。ACR の価格を参照してください
   Log Analytics ワークスペース	すべてのログ データを 1 か所で管理する	直接コストはかからなくなります。 Log Analytics コスト を参照してください。
   Application Insights	エージェントのパフォーマンスとログを監視する	従量制であり、Azure Monitor の価格を参照してください
   マネージド ID	Azure サービスに対してエージェントを認証します	コストなし

   ヒント

   このクイック スタートが完了したら、 azd down を実行してリソースを削除し、料金の発生を停止します。

手順 2: エージェントをローカルでテストする

デプロイする前に、エージェントがローカルで動作することを確認します。

1. エージェントをローカルで起動します。

   azd ai agent run
   

   このコマンドは、環境を自動的に設定し、依存関係をインストールして、エージェントを起動します。 startupCommandで定義されているazure.yamlを使用してエージェントを起動します。

   メモ

   プレビュー パッケージは、セットアップ中に pip 依存関係のバージョン競合の警告を生成できます。 これらの警告は非ブロッキングです。エージェントは起動し、それらの警告に対して正しく応答します。

   エージェントの起動に失敗した場合は、次の一般的な問題を確認してください。

   エラー	ソリューション
   AuthenticationError または DefaultAzureCredential エラー	azd auth logoutを実行し、azd auth loginしてセッションを更新します。
   ResourceNotFound	エンドポイント URL が Foundry ポータルの値と一致するかどうかを確認します。
   DeploymentNotFound	Build>Deployments でデプロイ名を確認します。
   Connection refused	他のプロセスでポート 8088 が使用されていないことを確認します。

2. 別のターミナルで、ローカル エージェントにテスト メッセージを送信します。

   Responses API を使用するエージェントの場合は、ペイロードとして文字列を送信できます。

   azd ai agent invoke --local "What is Microsoft Foundry?"
   

   Invocations API を使用するエージェントの場合は、予想されるペイロードの README.md を確認します。 サンプルには通常、JSON ペイロードが必要ですが、そのサンプルの README.md の内容を特定の例で確認します。

   エージェントからの応答が表示されます。

手順 3: Foundry エージェント サービスにデプロイする

手順 1 でインフラストラクチャを既にプロビジョニングしているため、エージェント コードをAzureにデプロイします。

azd deploy

エージェント コンテナーはリモートでビルドされるため、Docker Desktop はコンピューター上で必要ありません。

完了すると、出力には、エージェントプレイグラウンドへのリンクと、プログラムによってエージェントを呼び出すためのエンドポイントが表示されます。

Deploying services (azd deploy)

  (✓) Done: Deploying service af-agent-with-foundry-tools
  - Agent playground (portal): https://ai.azure.com/nextgen/.../build/agents/af-agent-with-foundry-tools/build?version=1 
  - Agent endpoint: https://ai-account-<name>.services.ai.azure.com/api/projects/<project>/agents/af-agent-with-foundry-tools/versions/1

手順 1: Foundry プロジェクトを作成する

VS Code の Microsoft Foundry Toolkit 拡張機能を使用して、新しい Microsoft Foundry Project リソースを作成します。

1. コマンド パレット (Ctrl + Shift + P) を開き、Microsoft Foundry: Create Project を選択します。

2. Azure サブスクリプションを選択します。

3. 新しいリソース グループを作成するか、既存のリソース グループを選択します。

4. Foundry Project リソースの名前を入力します。

プロジェクトの作成が完了したら、次の手順に進み、モデルをデプロイします。

手順 2: モデルをデプロイする

VS Code の Microsoft Foundry Toolkit 拡張機能を使用して、Foundry にモデルをデプロイします。

1. コマンド パレット (Ctrl + Shift + P) を開き、Microsoft Foundry: Open Model Catalog を選択します。

2. モデル カタログを参照するか、gpt-4.1 を検索し、[ デプロイ ] ボタンを選択します。

3. モデルのデプロイ ページで、Microsoft Foundry にデプロイ ボタンを選択します。

モデルが正常にデプロイされたら、次の手順に進み、Hosted Agent プロジェクトを作成します

手順 3: ホステッド エージェント プロジェクトを作成する

VS Code の Microsoft Foundry Toolkit 拡張機能を使用して、新しいホステッド エージェント プロジェクトをスキャフォールディングします。

1. コマンド パレット (Ctrl + Shift + P) を開き、Microsoft Foundry: Create new Hosted Agent を選択します。

2. 使用するフレームワークを選択します。

3. プログラミング言語 、Python、または C# を選択します。

4. [応答 API] または [API の呼び出し] を選択します。

5. 使用するサンプル コードを選択します。

6. プロジェクト ファイルを保存するフォルダーを選択します。

7. ホストされるエージェントの名前を入力します。

新しい VS Code ウィンドウが起動し、新しいエージェント プロジェクト フォルダーがアクティブなワークスペースとして表示されます。

手順 4: 依存関係をインストールする

仮想環境を使用してプロジェクトの依存関係を分離することをお勧めします。

macOS/Linux:

python -m venv .venv
source .venv/bin/activate

Windows (PowerShell):

python -m venv .venv
.\.venv\Scripts\Activate.ps1

依存関係のインストール

pip を使用して必要なPythonの依存関係をインストールします。

pip install -r requirements.txt

必要なパッケージの一覧については、requirement.txt を参照してください。

手順 5: エージェントをローカルでテストする

デプロイする前に、エージェントを実行してテストします。

オプション 1: F5 キーを押す (推奨)

VS Code で F5 キーを押してデバッグを開始します。 または、VS Code デバッグ メニューを使用することもできます。

1. [実行とデバッグ] ビューを開きます (Ctrl + Shift + D / Cmd + Shift + D)
2. ドロップダウンから [Debug Local Workflow HTTP Server]\(ローカル ワークフロー HTTP サーバーのデバッグ\) を選択します
3. 緑色の [デバッグの開始 ] ボタンをクリックします (または F5 キーを押します)

これにより、次の操作が行われます。

1. デバッグを有効にして HTTP サーバーを起動する
2. Foundry Toolkit Agent Inspector を開いて対話型テストを行う
3. ブレークポイントを設定し、ワークフローを検査できるようにします

オプション 2: ターミナルで実行する

HTTP サーバーとして実行する (既定):

python main.py

これにより、 http://localhost:8088/でホストされるエージェントがローカルで開始されます。

PowerShell (Windows):

$body = @{
   input = "I need a hotel in Seattle from 2025-03-15 to 2025-03-18, budget under `$200 per night"
    stream = $false
} | ConvertTo-Json

Invoke-RestMethod -Uri http://localhost:8088/responses -Method Post -Body $body -ContentType "application/json"

Bash/curl (Linux/macOS):

curl -sS -H "Content-Type: application/json" -X POST http://localhost:8088/responses \
   -d '{"input": "Find me hotels in Seattle for March 20-23, 2025 under $200 per night","stream":false}'

エージェントは、 get_available_hotels ツールを使用して、条件に一致する利用可能なホテルを検索します。

手順 6: Foundry Agent Service にデプロイする

VS Code から直接エージェントをデプロイします。

1. コマンド パレット (Ctrl + Shift + P) を開き、Microsoft Foundry: Deploy Hosted Agent を選択します。

2. [既定の ACR] を選択する

3. ホストされるエージェント コンテナーの CPU とメモリの構成を選択します。

左側のアイコンを選択して、Microsoft Foundry Toolkit エクスプローラーに切り替えます。 デプロイが完了すると、エージェント が [Hosted Agents (Preview)] ツリー ビュー サイドバーに表示されます。

エージェントの状態を確認する

エージェントの状態を確認して、実行中であることを確認します。

1. ホストされたエージェント (プレビュー) ツリー ビューから、ホストされているエージェントを選択します。

2. デプロイしたばかりのエージェントを選択する

詳細ページには、[コンテナーの詳細] セクションの下に [状態] が表示されます。

VS Code を使用してプレイグラウンドでテストする

Microsoft Foundry Toolkit for VS Code には、エージェントとチャットして対話するための統合されたプレイグラウンドが含まれています。

1. ホストされたエージェント (プレビュー) ツリー ビューから、ホストされているエージェントを選択します。

2. Playground オプションを選択し、メッセージを入力して送信してエージェントをテストします。

エージェントの状態を確認する

デプロイされたエージェントの状態を確認します。

azd ai agent show

出力をテーブル形式で表示するには:

azd ai agent show --output table

プロジェクトに複数のエージェント サービスがある場合は、位置引数としてエージェント名を指定します。

azd ai agent show <agent-name>

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

前に使用したのと同じ invoke コマンドを使用して、 --local フラグを指定せずに、デプロイされたエージェントにテスト メッセージを送信します。

Responses API を使用するエージェントの場合は、ペイロードとして文字列を送信できます。

azd ai agent invoke <payload>

数秒後にエージェントからの応答が表示されます。

エージェント ログの表示

エージェントのライブ ログを監視します。

# Fetch recent container console logs
azd ai agent monitor

# Fetch the last N lines of console logs
azd ai agent monitor --tail 20

# Fetch system event logs (container start and stop events)
azd ai agent monitor --type system

# Stream session logs in real time
azd ai agent monitor --session <session-id> --follow

プロジェクトに複数のエージェント サービスがある場合は、位置引数としてエージェント名を指定します。

azd ai agent monitor <agent-name> --follow

削除される内容をプレビューするには、 down コマンドを実行します。

azd down

完了すると、 azd 削除されるすべてのリソースが表示され、確認を求められます。 続行するには yes を選択するか、キャンセルする no を選択します。

クリーンアップ プロセスには約 2 ~ 5 分かかります。

リソースを削除するには、Azure ポータルを開き、リソース グループに移動して、含まれているすべてのリソースと共に削除します。

エージェントのコンテナー ログを表示する

問題のトラブルシューティングを行うには、コンテナーのコンソールとシステム ログを確認できます。

1. ホストされたエージェント (プレビュー) ツリー ビューから、ホストされているエージェントを選択します。

2. ホストされているエージェントの [プレイグラウンド] タブを選択します

3. セッションの詳細で [ログ] セクションを選択します。

エージェントのセッション ファイルを表示する

ADC ベースのエージェントのホーム ディレクトリに格納されているすべてのファイルを表示できます

1. ホストされたエージェント (プレビュー) ツリー ビューから、ホストされているエージェントを選択します。

2. ホストされているエージェントの [プレイグラウンド] タブを選択します

3. セッションの詳細で [ファイル] セクションを選択します。

現在のフォルダー内のフォルダーをダウンロード、アップロード、作成できます。フォルダーをクリックするとフォルダーにステップ インし、上部のナビゲーション バーをクリックすると、そのフォルダーに戻ります。