ホストされているエージェントにプロトコル アダプターを追加する

Important

この記事で "(プレビュー)" と付記されている項目は、現在、パブリック プレビュー段階です。 このプレビューはサービス レベル アグリーメントなしで提供されており、運用環境ではお勧めしません。 特定の機能がサポートされていないか、機能が制限されている可能性があります。 詳細については、「 Microsoft Azure プレビューの追加使用条件」を参照してください。

プロトコル アダプターは、エージェント コードが Microsoft Foundry でホストされるエージェント プロトコルのいずれか 1 つに対応できるようにする軽量な SDK ラッパーです。 この記事では、SDK アダプター パッケージをインストールし、ハンドラーを接続し、 azure.yamlでプロトコルを宣言して、再デプロイします。 ホストされるエージェント ランタイム コントラクトをまだ実装していない独自のコードを持ち込む場合は、アダプターを追加します。

前提条件

プロトコルを選択する

プロトコル いつ使用するか
responses 会話エージェント。 会話履歴、ストリーミング、OpenAI 応答 API の互換性が自動的に取得されます。
invocations 非会話型ワークロードまたはカスタム ペイロード ワークロード。 要求と応答の図形を定義します。

コントラクトの詳細については、 ホストされるエージェント ランタイム コントラクトに関するページを参照してください。

SDK パッケージをインストールする

# For the Responses protocol
pip install azure-ai-agentserver-responses

# For the Invocations protocol
pip install azure-ai-agentserver-invocations

ハンドラーを実装する

以下のパターンは、 foundry-samples リポジトリの Bring Your Own サンプルから抜粋したものです。 これらを開始点として使用し、実稼働コードの完全なサンプルをコピーします。

応答プロトコル

import asyncio
import os

from azure.ai.agentserver.responses import (
    CreateResponse,
    ResponseContext,
    ResponsesAgentServerHost,
    ResponsesServerOptions,
    TextResponse,
)
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential

_endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
_model = os.environ["FOUNDRY_MODEL_NAME"]

_project_client = AIProjectClient(
    endpoint=_endpoint, credential=DefaultAzureCredential()
)
_responses_client = _project_client.get_openai_client().responses

app = ResponsesAgentServerHost(
    options=ResponsesServerOptions(default_fetch_history_count=20),
)


@app.response_handler
async def handler(
    request: CreateResponse,
    context: ResponseContext,
    _cancellation_signal: asyncio.Event,
):
    user_input = await context.get_input_text() or "Hello!"

    # --- Your agent logic goes here ---
    response = await asyncio.get_running_loop().run_in_executor(
        None,
        lambda: _responses_client.create(
            model=_model,
            instructions="You are a helpful AI assistant.",
            input=[{"role": "user", "content": user_input}],
            store=False,
        ),
    )
    # -----------------------------------

    return TextResponse(context, request, text=response.output_text)


app.run()

呼び出しプロトコル

from starlette.requests import Request
from starlette.responses import Response, JSONResponse
from azure.ai.agentserver.invocations import InvocationAgentServerHost

app = InvocationAgentServerHost()


@app.invoke_handler
async def handle_invoke(request: Request) -> Response:
    data = await request.json()
    # --- Your agent logic goes here ---
    # The payload shape is entirely up to you
    message = data.get("message", "Hello!")
    return JSONResponse({"reply": message})


if __name__ == "__main__":
    app.run()

azure.yaml でプロトコルを宣言する

protocolsazure.ai.agent サービス内の azure.yaml フィールドを追加または更新します。

services:
  my-agent:
    host: azure.ai.agent
    project: src/my-agent
    kind: hosted
    protocols:
      - protocol: responses
        version: 2.0.0

呼び出しの場合は、次のプロトコルを使用します。

services:
  my-agent:
    host: azure.ai.agent
    project: src/my-agent
    kind: hosted
    protocols:
      - protocol: invocations
        version: 1.0.0

スタートアップ コマンドを更新する

startupCommand サービスのazure.ai.agentが、サーバーを起動するエントリ ポイントを指していることを確認します。

services:
  my-agent:
    host: azure.ai.agent
    startupCommand: python main.py

ローカルでテストして再デプロイする

# Test locally
azd ai agent run

# In another terminal
azd ai agent invoke --local "Hello!"

# Deploy
azd deploy

invocations プロトコルの場合は、--input-fileを使用してカスタム ペイロードを送信します。

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

2 つ目のプロトコルを追加する

エージェントは複数のプロトコルをサポートできます。 2 つ目を追加するには、追加の SDK パッケージをインストールし、エントリ ポイントに両方のハンドラーを登録し、azure.ai.agentazure.yaml サービスに両方のプロトコルを追加します。

services:
  my-agent:
    host: azure.ai.agent
    protocols:
      - protocol: responses
        version: 2.0.0
      - protocol: invocations
        version: 1.0.0

Note

エージェントが複数のプロトコルをサポートしている場合、 azd ai agent invoke は既定で responses プロトコルを使用します。 -p / --protocolを渡して、responsesまたはinvocationsを明示的に選択します。