Important
この記事で "(プレビュー)" と付記されている項目は、現在、パブリック プレビュー段階です。 このプレビューはサービス レベル アグリーメントなしで提供されており、運用環境ではお勧めしません。 特定の機能がサポートされていないか、機能が制限されている可能性があります。 詳細については、「 Microsoft Azure プレビューの追加使用条件」を参照してください。
プロトコル アダプターは、エージェント コードが Microsoft Foundry でホストされるエージェント プロトコルのいずれか 1 つに対応できるようにする軽量な SDK ラッパーです。 この記事では、SDK アダプター パッケージをインストールし、ハンドラーを接続し、 azure.yamlでプロトコルを宣言して、再デプロイします。
ホストされるエージェント ランタイム コントラクトをまだ実装していない独自のコードを持ち込む場合は、アダプターを追加します。
前提条件
- ホスト型エージェント プロジェクト。 作成するには、「Azure Developer CLI を使用してホストされるエージェント プロジェクトを初期化する」を参照してください。
- Python 3.10 以降、または 8 以降.NET。
- 関数内のエージェント ロジックは、ハンドラーから呼び出すことができます。
プロトコルを選択する
| プロトコル | いつ使用するか |
|---|---|
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 でプロトコルを宣言する
protocols の azure.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.agentの azure.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を明示的に選択します。