Azure Developer CLI を使用してホステッド エージェントを呼び出す

azd ai agent invokeを使用して、Microsoft Foundry にデプロイされたバージョンまたはローカルで実行されているインスタンスのいずれかで、エージェントにメッセージを送信します。 エージェントの選択、直接エンドポイントの使用、セッションの管理、ファイルの送信、バージョンのピン留め、生の応答の検査を行う方法について説明します。

前提条件

デプロイされたエージェントを呼び出す

  • 展開されたエージェントにプロンプトを送信します。

    azd ai agent invoke "What is Microsoft Foundry?"
    

特定のエージェントを呼び出す

  • プロジェクトに複数のエージェントが含まれている場合は、呼び出すエージェントを指定します。

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

デプロイされた特定のエンドポイントを呼び出す

アクティブな azd 環境や azure.yamlに依存せずに特定のデプロイ済みエージェントを呼び出す場合は、 --agent-endpoint を使用してデプロイされたエージェントの URL を直接ポイントします。 このパターンは、プロジェクト外のスクリプト、コーディング エージェント、または特定のエージェント バージョンをテストする場合に役立ちます。

  • デプロイされたエージェント エンドポイントを渡します。

    azd ai agent invoke \
       --agent-endpoint "https://my-project.services.ai.azure.com/api/projects/my-project/agents/release-summarizer/endpoint/protocols/openai/responses?api-version=v1" \
       "Summarize today's release notes."
    

    azd ai agent showまたはazd ai agent endpoint showから呼び出し可能プロトコルのエンドポイントをコピーします。 /versions/3で終わるバージョン管理 URL は、呼び出しエンドポイントではありません。 --agent-endpoint は azd 環境と azure.yaml の解決をバイパスします。

ローカルで呼び出す

  • ローカル エージェントを呼び出します。

    azd ai agent invoke --local "Hello!"
    

    エージェントは、別のターミナルで azd ai agent run で既に実行されている必要があります。

カスタム ローカル ポートで呼び出す

  • エージェントが既定以外のポートで実行されている場合は、 --port渡します。

    azd ai agent invoke --local --port 9090 "Hello!"
    

プロトコルを選択する

--protocolを省略すると、CLI は利用可能な場合は完全なデプロイ済みエンドポイント データを使用し、そうでない場合はエージェント定義を使用します。 呼び出し可能なプロトコルを 1 つだけ正確に特定できない場合は、--protocol を明示的に渡します。 再デプロイして、以前の拡張機能によって保存されたエンドポイント データを更新します。

  • responses -- {"input": "your message"}を使用して標準の OpenAI 応答 API 要求を送信します。 会話履歴は自動的に管理されます。
  • invocations -- エージェントコードが想定する任意のペイロードを送信します。 ハンドラーが定義するスキーマに一致する JSON ファイルで --input-file (-f) を使用します。
  • a2a -- デプロイされたエージェント間エンドポイントを呼び出します。 メッセージを渡すか、完全な JSON-RPC 要求で --input-file を使用します。 このプロトコルは、 --localをサポートしていません。

invocations エージェントの場合は、サンプルの README を確認するか、ハンドラーのエントリ ポイントを調べて、予想されるペイロードを理解します。

  • エージェントが複数のプロトコルを実装している場合は、 --protocol (-p) を渡して選択します。

    azd ai agent invoke --protocol invocations -f request.json
    

音声エージェントの制限事項

azd ai agent invoke は音声会話に対応していません。 選択したサービスazure.yamlvoiceまたはprompt-voiceとして識別されると、コマンドはvoice agents cannot be invoked with this commandを返し、Foundry ポータルに誘導します。

この制限は、 conversationEngine を使用してホステッド ターゲットを参照する音声ラッパーにも適用されます。 --protocol responsesを選択しても、音声サービスのチェックはバイパスされません。

音声エージェントのクイック スタートで説明されているように、プレイグラウンドを使用して 音声エージェントをテストします。

セッションを管理する

CLI は、セッションと会話の選択をエージェントごとにローカルに保存します。 セッションでは、アップロードされたファイルなどのサンドボックスの状態が保持されます。 応答プロトコルの場合、会話はメッセージ履歴を保持します。 セッションのみを再利用しても、Invocations プロトコルの会話履歴は提供されません。

新しいセッションを開始する

  • 保存されたセッションを破棄し、新たに開始します。

    azd ai agent invoke --new-session "Start fresh"
    

特定のセッション ID を使用する

  • 既存のセッション ID を渡します。

    azd ai agent invoke --session-id my-session-123 "Continue conversation"
    

会話履歴を個別に選択する

応答プロトコルでは、--new-conversation と新しい会話を開始するか、--conversation-id との既存の会話を継続してください:

azd ai agent invoke --new-conversation "Start a new topic"
azd ai agent invoke --conversation-id <conversation-id> "Continue this topic"

--new-session 保存された会話もリセットします。 会話履歴とサンドボックスの状態の違いについては、「ホステッド エージェント セッションの管理」を参照してください。

ファイルを入力として送信する

構造化されたペイロードまたは大きなペイロード (特に invocations プロトコルの場合) には、JSON ファイルを渡します。

  1. ファイルを送信する:

    azd ai agent invoke -f request.json
    
  2. または、特定のエージェントにファイルを送信します。

    azd ai agent invoke my-agent -f request.json
    

デプロイされたバージョンを呼び出す

エージェントに複数のデプロイ済みバージョンがある場合は、特定のバージョンを --versionにピン留めします。 azd は、そのバージョンによってサポートされるセッションを作成または再利用するため、各バージョンは独自の会話状態を維持します。

  • バージョンを固定する:

    azd ai agent invoke --version 3 "Use the v3 prompt"
    

    --version セッションは作成時にバージョンにバインドされるため、 --local または --session-id と組み合わせることはできません。

カスタム タイムアウトを設定する

  • タイムアウトを秒単位で渡します。

    azd ai agent invoke --timeout 300 "Process this large dataset"
    

    既定のタイムアウトは 1800 秒 (30 分) です。 タイムアウトがない場合は、 --timeout 0 を使用します。

エンドユーザーの ID を渡す

--user-identity を渡して、エンドユーザーに代わってリクエストを送信します。 リモート要求の場合、azd は x-ms-user-identity ヘッダーで値を送信します。 フラグは、応答、呼び出し、および A2A プロトコルで動作します。

要求は引き続き呼び出し元のMicrosoft Entra資格情報で認証されます。 ヘッダーは、代理対象のユーザーを識別します。認証を置き換えたり、前提条件に記載されている委任アクセス許可を付与したりすることはありません。

  • デプロイされたエージェントにエンドユーザー ID を送信します。

    azd ai agent invoke my-agent \
       --user-identity "user-123" \
       "Hello!"
    

    user-123を、認証されたエンド ユーザーの安定した識別子に置き換えます。 すべての呼び出しに --user-identity を含めます。フラグの既定値は空です。 これを使用しない場合、Foundry は呼び出し元自身の ID を使用します。

azd は、 --user-identity 値ではなく、エージェントごとにセッション ID と会話 ID を保存します。 ID を変更しても、別の保存状態は選択されません。 Responses プロトコルを使用してユーザーを切り替える場合は、新しいセッションと会話を開始します。

azd ai agent invoke my-agent --protocol responses \
  --user-identity "user-456" \
  --new-session --new-conversation \
  "Start a conversation for this user"

ユーザーの既存の Responses 状態を再開するには、同じ --user-identity を使用して、そのユーザーの --session-id と --conversation-id を渡します。 別のユーザーの会話 ID を再利用しないでください。

x-ms-user-identity には、--client-header ではなく、--user-identity を使用します。 --client-header フラグは、x-client-* の名前のみを受け入れ、ID ヘッダーを拒否します。

識別子の要件と分離の動作については、「ユーザーごとにホストされるエージェント セッションを分離する」を参照してください。 エージェント拡張機能の現在のバージョンでは、以前の --user-isolation-key、--chat-isolation-key、または --isolation-key フラグは受け入れられません。

ローカル エージェントに ID を渡す

--local を使用して、azd は、x-ms-user-identity ではなく、x-agent-user-id としての同じフラグ値を送信します。

azd ai agent invoke my-agent --local \
  --user-identity "user-123" \
  "Hello!"

このヘッダーを使用して、ローカルエージェントがユーザーコンテキストをどのように処理するかをテストします。 ローカル実行では、Foundry の分離権限または委任権限は強制されません。

アプリケーション固有のヘッダーを送信する

相関 ID やテナント ラベルなど、要求メタデータに反復可能な --client-header "Name: Value" フラグを使用します。

azd ai agent invoke \
  --client-header "x-client-request-id: request-123" \
  --client-header "x-client-tenant: contoso" \
  "Hello!"

x-client-*ヘッダー名のみが受け入れられます。 応答と呼び出しエンドポイントは、これらのヘッダーをエージェントに転送します。 A2A プロトコルでは、このフラグはサポートされていません。 委任された ID には、--user-identityではなく--client-headerを使用します。

クライアントの切断後に作業を実行する

応答プロトコルの場合、 --long-running はサービス側のバックグラウンド作業を開始します。 --no-waitも渡す場合を除き、コマンドは完了するまでアタッチされたままです。

azd ai agent invoke --long-running --no-wait "Run the long task"

このコマンドは、サービス割り当て応答 ID を受け取った後に戻ります。 その作業を確認、追跡、またはキャンセルを要求します:

azd ai agent invocations show --protocol responses
azd ai agent invocations follow --protocol responses
azd ai agent invocations cancel --protocol responses

これらのコマンドでは、選択したエージェントとプロトコルの最新の保存済み ID が既定で使用されます。 その選択を変更せずに別の応答を指定するには、--id <response-id> を渡します。 --agent-nameまたは--agent-endpointを使用してターゲットを選択し、委任された要求に対して--user-identityを繰り返します。 ダイレクト エンドポイントはプロトコルを識別します。 --protocol や --agent-nameと組み合わせないでください。

応答 は show、follow、cancel に対応しています。 呼び出しでは show と cancelがサポートされますが、 followはサポートされません。 A2A では、これらのライフサイクル コマンドはサポートされていません。 サービスは、個々のエージェントが実装していない操作を拒否できます。

バックグラウンド実行では、クラッシュ復旧や自動再接続は有効になりません。 エージェントの回復動作を個別に構成します。クラッシュ後に長時間実行される作業を回復するを参照してください。

プラットフォームのレイテンシを確認する

リモート ホステッド エージェントの応答と呼び出し要求は、既定でプラットフォーム レイテンシの診断を収集します。 サービスがタイミング ヘッダーを返すと、CLI に概要が表示されます。 --debug-latency=false を使用して、収集と要約を無効にします。

ローカル呼び出し、プロンプト エージェント呼び出し、A2A 呼び出しでは、プラットフォームの待機時間は収集されません。 これらのルートでは、明示的な --debug-latency=true は拒否されます。 この設定は、グローバル --debug フラグとは無関係です。

生の HTTP 応答を検査する

エージェントのバージョン、状態行、変更されていない本文などの応答ヘッダーなど、サーバーから返された内容を正確に確認する必要がある場合は、 --output raw (-o raw) を渡します。

  • 生の出力を要求します。

    azd ai agent invoke --output raw "Hello!"
    

    未加工モードでは、 Session: や Invocation: などのわかりやすい要約行が抑制され、HTTP 応答が逐語的にダンプされます。 このモードは、サーバーの動作をデバッグし、呼び出しを処理したエージェントのバージョンを確認する場合に役立ちます。