Aggiungere un adattatore di protocollo all'agente ospitato

Importante

Gli elementi contrassegnati (anteprima) in questo articolo sono attualmente in anteprima pubblica. Questa anteprima viene fornita senza un contratto di servizio e non è consigliabile per i carichi di lavoro di produzione. Alcune funzionalità potrebbero non essere supportate o potrebbero avere funzionalità limitate. Per ulteriori informazioni, vedere Condizioni supplementari per l'uso delle versioni di anteprima di Microsoft Azure.

Un adattatore di protocollo è un wrapper leggero dell'SDK che consente al codice del tuo agente di comunicare tramite uno dei protocolli per agenti ospitati di Microsoft Foundry. In questo articolo si installa il pacchetto dell'adattatore SDK, si collega un gestore, si dichiara il protocollo in azure.yamle si ridistribuisce. Aggiungere un adattatore quando si usa codice personalizzato che non implementa già il contratto di runtime dell'agente ospitato.

Prerequisiti

Scegliere un protocollo

Protocol Quando utilizzare
responses Agenti di conversazione. Ottieni la cronologia automatica delle conversazioni, lo streaming e la compatibilità con l'API Responses di OpenAI.
invocations Carichi di lavoro non conversazionali o con payload personalizzato. Definire la forma della richiesta e della risposta.

Per dettagli completi sul contratto, vedere Contratto di runtime dell'agente ospitato.

Installare il pacchetto SDK

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

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

Implementa un gestore

I criteri seguenti sono una versione abbreviata dei propri esempi nel repository foundry-samples. Usarli come punto di partenza e copiare l'esempio completo per il codice di produzione.

Protocollo di risposte

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

Protocollo di Invocazioni

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

Dichiarare il protocollo in azure.yaml

Aggiungi o aggiorna il campo protocols nel servizio azure.ai.agent nel tuo azure.yaml:

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

Per le chiamate, usare il protocollo seguente:

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

Aggiornare il comando di avvio

Assicurarsi che startupCommand nel servizio azure.ai.agent punti al punto di accesso che avvia il server:

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

Testare localmente e ridistribuire

# Test locally
azd ai agent run

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

# Deploy
azd deploy

Per il invocations protocollo, usare --input-file per inviare il payload personalizzato:

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

Aggiungere un secondo protocollo

Un agente può supportare più protocolli. Per aggiungere un secondo, installare il pacchetto SDK aggiuntivo, registrare entrambi i gestori nel punto di ingresso e aggiungere entrambi i protocolli al azure.ai.agent servizio in azure.yaml:

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

Annotazioni

Quando un agente supporta più protocolli, azd ai agent invoke usa il responses protocollo per impostazione predefinita. Passare -p/--protocol per selezionare responses o invocations in modo esplicito.