Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
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
- Un proyecto de agente alojado. Para crear uno, consulte Inicialización de un proyecto de agente hospedado con la CLI para desarrolladores de Azure.
- Python 3.10 o posterior, o .NET 8 o posterior.
- Tu lógica de agente en una función que puedes llamar desde un controlador.
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.