Adición de un adaptador de protocolo al agente hospedado

Importante

Los elementos marcados (versión preliminar) de este artículo se encuentran actualmente en versión preliminar pública. Esta versión preliminar se ofrece sin acuerdo de nivel de servicio y no se recomienda para las cargas de trabajo de producción. Es posible que algunas características no se admitan o que tengan funcionalidades restringidas. Para más información, consulte Términos de uso complementarios para las versiones preliminares de Microsoft Azure.

Un adaptador de protocolo es un encapsulador ligero del SDK que permite al código del agente comunicarse con uno de los protocolos de agente alojados en Microsoft Foundry. En este artículo, instalará el paquete del adaptador del SDK, conectará un controlador, declarará el protocolo en azure.yamly volverá a implementarlo. Añade un adaptador cuando utilices tu propio código que aún no implemente el contrato de tiempo de ejecución del agente hospedado.

Prerequisites

Elección de un protocolo

Protocol Cuándo se deben usar
responses Agentes conversacionales. Obtienes historial de conversaciones automático, transmisión en tiempo real y compatibilidad con la API Responses de OpenAI.
invocations Cargas de trabajo no conversacionales o de carga útil personalizada. Defina la forma de solicitud y respuesta.

Para obtener los detalles completos del contrato, consulte Contrato de tiempo de ejecución del agente hospedado.

Instalación del paquete del SDK

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

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

Implementación de un controlador

Los siguientes patrones son versiones abreviadas de los ejemplos de tipo «bring-your-own» del repositorio foundry-samples. Úselos como punto de partida y copie el ejemplo completo para el código de producción.

Protocolo de respuestas

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

Protocolo de invocaciones

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

Declare el protocolo en azure.yaml

Agregue o actualice el campo protocols en el servicio azure.ai.agent de su azure.yaml:

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

Para las invocaciones, use el siguiente protocolo:

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

Actualización del comando de inicio

Asegúrese de que el startupCommand del servicio azure.ai.agent apunte al punto de entrada que inicia el servidor:

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

Prueba local y reimplementación

# Test locally
azd ai agent run

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

# Deploy
azd deploy

Para el invocations protocolo, use --input-file para enviar la carga personalizada:

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

Adición de un segundo protocolo

Un agente puede admitir varios protocolos. Para agregar un segundo, instale el paquete de SDK adicional, registre ambos controladores en el punto de entrada y agregue ambos protocolos al azure.ai.agent servicio en azure.yaml:

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

Nota:

Cuando un agente admite varios protocolos, azd ai agent invoke usa el responses protocolo de forma predeterminada. Pase -p/--protocol para seleccionar responses o invocations explícitamente.