Adicionar um adaptador de protocolo ao agente hospedado

Importante

Os itens marcados (versão prévia) neste artigo estão atualmente em versão prévia pública. Essa versão prévia é fornecida sem um contrato de nível de serviço e não recomendamos isso para cargas de trabalho de produção. Alguns recursos podem não ter suporte ou podem ter restrição de recursos. Para obter mais informações, consulte Termos de Uso Complementares para Versões Prévias do Microsoft Azure.

Um adaptador de protocolo é um wrapper leve de SDK que permite que o código do seu agente se comunique usando um dos protocolos de agente hospedados do Microsoft Foundry. Neste artigo, você instala o pacote do adaptador do SDK, conecta um manipulador, declara o protocolo azure.yamle reimplanta. Adicione um adaptador ao usar código próprio que não implemente o contrato de tempo de execução do agente hospedado.

Pré-requisitos

Escolher um protocolo

Protocol Quando usar
responses Agentes conversacionais. Você obtém compatibilidade automática de histórico de conversas, streaming e API de Respostas OpenAI.
invocations Cargas de trabalho não conversacionais ou de carga útil personalizada. Você define a forma de solicitação e resposta.

Para obter os detalhes completos do contrato, consulte o contrato de runtime do agente hospedado.

Instalar o pacote do SDK

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

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

Implemente um manipulador

Os padrões abaixo são adaptados dos exemplos do tipo “traga o seu próprio” no repositório foundry-samples. Use-os como ponto de partida e copie o exemplo completo para o código de produção.

Protocolo de respostas

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 invocações

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

Declarar o protocolo em azure.yaml

Adicione ou atualize o campo protocols no serviço azure.ai.agent no seu azure.yaml:

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

Para invocações, use o seguinte protocolo:

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

Atualizar o comando de inicialização

Verifique se o startupCommand no serviço azure.ai.agent aponta para o ponto de entrada que inicia o servidor:

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

Testar localmente e reimplantar

# Test locally
azd ai agent run

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

# Deploy
azd deploy

Para o protocolo invocations, use --input-file para enviar seu payload personalizado:

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

Adicionar um segundo protocolo

Um agente pode dar suporte a vários protocolos. Para adicionar um segundo, instale o pacote SDK adicional, registre ambos os manipuladores no seu ponto de entrada e adicione ambos os protocolos ao serviço azure.ai.agent em azure.yaml:

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

Note

Quando um agente dá suporte a vários protocolos, azd ai agent invoke usa o responses protocolo por padrão. Passe -p/--protocol para selecionar responses ou invocations explicitamente.