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/versions/3 \
   "Summarize today's release notes."

    --agent-endpoint は azd 環境と azure.yaml 解決をオーバーライドするため、azd プロジェクト ディレクトリ内で使用する必要はありません。

ローカルで呼び出す

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

    azd ai agent invoke --local "Hello!"

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

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

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

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

プロトコルを選択する

呼び出しに使用されるプロトコルは、protocolsのazure.ai.agent サービスのazure.yaml フィールドによって決まります。

  • responses -- {"input": "your message"}を使用して標準の OpenAI 応答 API 要求を送信します。 会話履歴は自動的に管理されます。
  • invocations -- エージェントコードが想定する任意のペイロードを送信します。 ハンドラーが定義するスキーマに一致する JSON ファイルで --input-file (-f) を使用します。

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

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

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

セッションを管理する

セッションはエージェントごとに永続化されます。 エージェントを呼び出すと、 azd はセッション ID をローカルに保存するため、次の invoke は自動的に同じセッションを続行し、呼び出し間で会話履歴を保持します。

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

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

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

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

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

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

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

構造化されたペイロードまたは大きなペイロード (特に 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 を使用します。

分離キーを渡す

Foundry ヘッダーベースの分離を使用して構成されたエージェントでは、すべての要求に対してユーザーごとまたはチャットごとのキーが必要です。 --user-isolation-keyと--chat-isolation-keyで渡します。

  • 要求で分離キーを渡します。

    azd ai agent invoke \
   --user-isolation-key "$USER_KEY" \
   --chat-isolation-key "$CHAT_KEY" \
   "Hello!"

セッション、ファイル、およびモニター コマンドで同じフラグを使用する方法など、完全なパターンについては、「 分離キーをホストされたエージェントに渡す」を参照してください。

生の HTTP 応答を検査する

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

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

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

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

関連するコンテンツ

  • Last updated on