Hinzufügen eines Protokolladapters zu Ihrem gehosteten Agent

Important

Die in diesem Artikel markierten Elemente (Vorschau) sind aktuell als öffentliche Vorschau verfügbar. Diese Vorschauversion wird ohne Vereinbarung zum Servicelevel bereitgestellt und sollte nicht für Produktionsworkloads verwendet werden. Manche Features werden möglicherweise nicht unterstützt oder sind nur eingeschränkt verwendbar. Weitere Informationen finden Sie unter Supplementale Nutzungsbedingungen für Microsoft Azure Previews.

Ein Protokolladapter ist ein einfacher SDK-Wrapper, mit dem Ihr Agentcode eines der Microsoft Foundry gehosteten Agent-Protokolle sprechen kann. In diesem Artikel installieren Sie das SDK-Adapterpaket, binden einen Handler ein, deklarieren das Protokoll in azure.yaml und stellen es erneut bereit. Fügen Sie einen Adapter hinzu, wenn Sie Ihren eigenen Code mitbringen, der den Laufzeitvertrag des gehosteten Agents noch nicht implementiert.

Voraussetzungen

Auswählen eines Protokolls

Protocol Wann verwenden?
responses Dialogagenten. Sie erhalten automatischen Gesprächsverlauf, Streaming und Kompatibilität mit der OpenAI Responses API.
invocations Nicht konversationsbezogene oder benutzerdefinierte Payload-Workloads. Sie definieren die Struktur der Anfrage und der Antwort.

Ausführliche Vertragsdetails finden Sie unter Laufzeitvertrag für gehosteten Agent.

Installieren des SDK-Pakets

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

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

Einen Handler implementieren

Die folgenden Muster sind gekürzte Fassungen von den „Bring-your-own“-Beispielen im Repository foundry-samples. Verwenden Sie sie als Ausgangspunkt, und kopieren Sie das vollständige Beispiel für Produktionscode.

Antwortprotokoll

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()

Aufrufeprotokoll

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()

Deklarieren des Protokolls in azure.yaml

Fügen Sie das Feld protocols im Dienst azure.ai.agent in Ihrem azure.yaml hinzu oder aktualisieren Sie es:

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

Verwenden Sie für Aufrufe das folgende Protokoll:

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

Aktualisieren des Startbefehls

Stellen Sie sicher, dass der startupCommand im azure.ai.agent-Dienst auf den Einstiegspunkt verweist, der den Server startet:

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

Lokal testen und erneut bereitstellen

# Test locally
azd ai agent run

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

# Deploy
azd deploy

Für das invocations-Protokoll verwenden Sie --input-file, um Ihre benutzerdefinierten Nutzdaten zu senden:

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

Hinzufügen eines zweiten Protokolls

Ein Agent kann mehrere Protokolle unterstützen. Um ein zweites hinzuzufügen, installieren Sie das zusätzliche SDK-Paket, registrieren Sie beide Handler in Ihrem Einstiegspunkt und fügen Sie beide Protokolle zum azure.ai.agent-Dienst in azure.yaml hinzu:

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

Note

Wenn ein Agent mehrere Protokolle unterstützt, verwendet azd ai agent invoke standardmäßig das responses-Protokoll. Übergeben Sie -p/--protocol, um responses oder invocations explizit auszuwählen.