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

• Azure Developer CLI バージョン 1.23.0 以降
• Docker Desktop がインストールされ、実行されている

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

手順 1: サンプル projectを設定する

Foundry スターター テンプレートを使用して新しいprojectを初期化し、agent-with-foundry-tools サンプルを使用して構成します。

1. 空のディレクトリでスターター テンプレートを初期化します。

   azd init -t https://github.com/Azure-Samples/azd-ai-starter-basic
   

   この対話型コマンドは、環境名 (たとえば、 my-hosted-agent) を入力するように求められます。 環境名によって、リソース グループ名 (rg-my-hosted-agent) が決まります。

   注

   同じ名前のリソース グループが既に存在する場合、 azd provision は既存のグループを使用します。 競合を回避するには、一意の環境名を選択するか、既存のリソース グループを最初に削除します。

2. エージェントサンプルを初期化します。

   azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/agent-framework/agent-with-foundry-tools/agent.yaml
   

   この対話型コマンドでは、次の構成値の入力を求められます。

   • Azure サブスクリプション - Foundry リソースを作成するAzure サブスクリプションを選択します。
   • 場所 - リソースのリージョンを選択する
   • モデル SKU - リージョンとサブスクリプションで使用可能な SKU を選択する
   • デプロイ名 - モデル デプロイの名前を入力します
   • コンテナー メモリ - コンテナー のメモリ割り当ての値を入力するか、既定値をそのまま使用します
   • コンテナー CPU - コンテナー の CPU 割り当ての値を入力するか、既定値をそのまま使用します
   • 最小レプリカ - コンテナーの最小レプリカの値を入力します
   • 最大レプリカ - コンテナーの最大レプリカの値を入力します

   Important

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

   - name: AZURE_AI_PROJECT_TOOL_CONNECTION_ID
     value: <CONNECTION_ID_PLACEHOLDER>
   

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

   注

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

   azd provision
   

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

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

   ヒント

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

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

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

1. Python 仮想環境を作成してアクティブ化します。

   Bash：

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

   PowerShell:

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

2. 依存関係をインストールします。

   pip install -r ./src/af-agent-with-foundry-tools/requirements.txt
   

3. エージェント コードで使用される必要な環境変数をローカルの .env ファイルにコピーします。

   Bash：

   azd env get-values > .env
   

   PowerShell:

   azd env get-values > .env
   

4. モデル デプロイの名前を使用して、 AZURE_OPENAI_CHAT_DEPLOYMENT_NAME 変数を .env ファイルに追加します。

   AZURE_OPENAI_CHAT_DEPLOYMENT_NAME="gpt-4.1"

5. エージェントをローカルで実行します。

   python ./src/af-agent-with-foundry-tools/main.py
   

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

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

6. REST クライアントを使用してテストします。 エージェントは localhost:8088で実行されます。

   Bash：

   curl -X POST http://localhost:8088/responses \
       -H "Content-Type: application/json" \
       -d '{"input": "What is Microsoft Foundry?"}'
   

   PowerShell:

   Invoke-RestMethod -Method Post `
       -Uri "http://localhost:8088/responses" `
       -ContentType "application/json" `
       -Body '{"input":"What is Microsoft Foundry?"}'
   

   Microsoft Foundry に関する Web 検索結果を含む応答が表示されます。

7. Ctrl + C キーを押してローカル サーバーを停止します。

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

azd up コマンドは、インフラストラクチャのプロビジョニング、アプリケーションのパッケージ化、Azureへのデプロイという 3 つの手順を組み合わせています。 これは、 azd provision、 azd package、および azd deploy を個別に実行することと同じです。

開始する前に、Docker Desktop が実行されていることを確認します。

docker info

このコマンドが失敗した場合は、Docker Desktop を起動し、初期化されるまで待ってから続行します。

エージェントをデプロイします。

azd up

Docker でイメージをビルドする必要があるため、最初のデプロイには時間がかかります。

完了すると、エージェントプレイグラウンドとエージェントのエンドポイントへのリンクが表示され、これを使用してエージェントをプログラムで呼び出すことができます。

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 拡張機能を使用して、新しい Microsoft Foundry プロジェクト リソースを作成します。

1. コマンド パレット (Ctrl + Shift + P) を開き、[ Microsoft Foundry: プロジェクトの作成] を選択します。

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

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

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

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

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

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

1. コマンド パレット (Ctrl + Shift + P) を開き、[ Microsoft Foundry: Open Model Catalog]\(Microsoft Foundry: モデル カタログを開く\) を選択します。

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

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

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

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

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

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

2. 単一エージェントまたはマルチエージェント ワークフロー テンプレートを選択する

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

4. 前の手順でデプロイした既存の gpt-4.1 モデルを選択します。

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

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

新しい 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

必要なパッケージは次のとおりです。

• azure-ai-agentserver-agentframework - Agent Framework と AgentServer SDK

手順 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. 対話型テスト用に AI 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. ホストされるエージェント コンテナーの CPU とメモリの構成を選択します。

3. 表示されたダイアログで、[確認と展開] ボタンを選択します。

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

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

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

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

2. バージョン (v1) を選択して詳細ページを開きます。

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

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

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

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

2. バージョン (v1) を選択して詳細ページを開きます。

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

確認する前に削除される内容をプレビューするには:

azd down --preview

削除する準備ができたら、次のコマンドを実行します。

azd down

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

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

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

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

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

2. バージョン (v1) を選択して詳細ページを開きます。

3. 右側の [ログ] ボタンを選択して、ログ ビューアーを開きます。