Implementación de un agente hospedado

En este artículo se muestra cómo implementar un agente contenedorizado en el servicio de agente foundry mediante el SDK de Python o la API REST. Use estos enfoques cuando desee administrar implementaciones de agente directamente desde sus propias aplicaciones o servicios.

Si va a implementar por primera vez o quiere la ruta de acceso más rápida, use el inicio rápido: Creación e implementación de un agente hospedado en su lugar. El quickstart utiliza el Azure Developer CLI (azd) o la extensión de Visual Studio Code, que maneja automáticamente la creación, inserción, control de versiones y configuración de RBAC.

Ciclo de vida de la implementación

Cada implementación del agente hospedado sigue esta secuencia:

1. Compilación e inserción : empaquete el código del agente en una imagen de contenedor e insértelo en Azure Container Registry.
2. Crear una versión del agente: registre la imagen con Foundry Agent Service. La plataforma aprovisiona la infraestructura y crea una identidad de agente Entra dedicada.
3. Sondeo del estado: espere a que el estado de la versión sea active.
4. Invoke: envíe solicitudes al punto de conexión dedicado del agente.

Prerrequisitos

• Un proyecto de Microsoft Foundry.
• Código de agente utilizando un marco compatible.
• Docker Desktop instalado para el desarrollo de contenedores locales.
• Cli de Azure versión 2.80 o posterior.

Permisos necesarios

Necesita Azure AI Project Manager en el nivel del proyecto para crear e implementar agentes hospedados. Este rol incluye los permisos del plano de datos para crear agentes y la capacidad de asignar el rol de usuario de Azure AI a la identidad del agente creada por la plataforma. La identidad del agente necesita el usuario de Azure AI en el proyecto para acceder a los modelos y artefactos en tiempo de ejecución.

Si usa azd o la extensión de VS Code, las herramientas controlan la mayoría de las asignaciones de RBAC automáticamente, entre las que se incluyen:

• Lector del repositorio de Container Registry para la identidad administrada del proyecto (extracción de imágenes)
• Usuario de Azure AI para la identidad del agente creado por la plataforma (modelo en tiempo de ejecución y acceso a herramientas)

Para obtener más información, consulte Autenticación y autorización.

Requisitos de contenedor

Su imagen de contenedor debe cumplir los siguientes requisitos para poder ejecutarse en la plataforma de agente hospedado.

Bibliotecas de protocolos

Los agentes hospedados se comunican con la puerta de enlace de Foundry a través de bibliotecas de protocolos. Elija el protocolo que coincida con el patrón de interacción del agente:

Un único contenedor puede exponer ambos protocolos simultáneamente declarando ambos al crear el agente ( en el agent.yaml archivo, la llamada del SDK o la solicitud de API REST) e importando ambas bibliotecas. Use las bibliotecas de protocolos en el marco existente, ya sea microsoft Agent Framework, LangChain o código personalizado.

Biblioteca de protocolos de respuestas

Las bibliotecas de Python y .NET para el protocolo De respuestas implementan la API de respuestas de IA de Azure. Importe el paquete e implemente la IResponseHandler interfaz. La biblioteca controla el enrutamiento, el streaming con eventos enviados por el servidor (SSE), la ejecución en segundo plano, la cancelación, el almacenamiento en caché y la administración del ciclo de vida de respuesta.

IResponseHandler

IResponseHandler es la abstracción principal que implementa. La biblioteca llama a CreateAsync para cada solicitud entrante y entrega el devuelto IAsyncEnumerable<ResponseStreamEvent> a los clientes a través de SSE.

public class EchoHandler : ResponseHandler
{
    public override IAsyncEnumerable<ResponseStreamEvent> CreateAsync(
        CreateResponse request,
        ResponseContext context,
        CancellationToken cancellationToken)
    {
        return new TextResponse(context, request,
            createText: async ct =>
            {
                var input = await context.GetInputTextAsync(cancellationToken: ct);
                return $"Echo: {input}";
            });
    }
}

ResponseEventStream

ResponseEventStream administra automáticamente sequenceNumber, outputIndex, contentIndex, itemId y el ciclo de vida completo de Response. Cada yield return se asigna directamente a un evento SSE, por lo que no es necesario realizar un seguimiento de este estado por sí mismo.

Modos de streaming y de fondo

• Modo de streaming (valor predeterminado): los eventos SSE se entregan en tiempo real al cliente conectado.
• Modo en segundo plano: el controlador se ejecuta hasta la finalización sin un cliente SSE conectado. Los eventos se almacenan en búfer y están disponibles para la reproducción a través de GET /responses/{id}.

Ciclo de vida de la respuesta

La biblioteca organiza el ciclo de vida de respuesta completo: created → → in_progresscompleted (o failedcancelled). La biblioteca también administra automáticamente las garantías de cancelación, control de errores y eventos terminales.

Seguridad de hilos

Todas las instancias de servicio registradas a través de AddResponsesServer() son seguras para subprocesos. Las instancias del controlador tienen ámbito por solicitud.

Para obtener instrucciones detalladas sobre la implementación del controlador, consulte la guía de implementación de handler. Para obtener ejemplos ejecutables, consulte los ejemplos del protocolo Responses.

Puntos de evaluación de salud

Las bibliotecas de protocolo exponen automáticamente un /readiness punto de conexión para las comprobaciones de estado de la plataforma. No es necesario implementar esto usted mismo.

Puerto

Los contenedores atienden el tráfico en el puerto 8088 localmente. En producción, la pasarela de Foundry controla el enrutamiento, por lo que el contenedor no necesita exponer un puerto público.

Variables de entorno insertadas en la plataforma

La plataforma del agente hospedado inserta automáticamente variables de entorno en el contenedor en tiempo de ejecución. El código puede leerlos sin declararlos en agent.yaml o environment_variables. El FOUNDRY_* prefijo está reservado para uso de plataforma.

No vuelva a declarar las variables inyectadas por la plataforma en agent.yaml, ya que se establecen automáticamente.

Las variables que usted mismo declara, como MODEL_DEPLOYMENT_NAME o los puntos de conexión MCP del cuadro de herramientas, van en la sección environment_variables de agent.yaml o en la llamada del SDK create_version.

Empaquetado y prueba del agente localmente

Antes de realizar la implementación en Foundry, valide que el agente funciona localmente mediante la biblioteca de protocolos. El contenedor ofrece los mismos puntos de conexión localmente que en producción.

Probar el protocolo de respuestas

POST http://localhost:8088/responses
Content-Type: application/json

{
    "input": "Where is Seattle?",
    "stream": false
}

Probar el protocolo Invocations

POST http://localhost:8088/invocations
Content-Type: application/json

{
    "message": "Hello!"
}

Implementación mediante la CLI para desarrolladores de Azure o VS Code

La CLI para desarrolladores de Azure (azd) y la extensión de VS Code automatizan el ciclo de vida completo de la implementación. Para ver un tutorial paso a paso, consulte inicio rápido: Creación e implementación de un agente hospedado.

Implementación mediante el SDK de Python

Use el SDK cuando quiera administrar las implementaciones de agente directamente desde el código de Python.

Requisitos previos adicionales

• Python 3.10 o posterior

• Imagen de contenedor en Azure Container Registry

• Escritor de repositorios del Registro de Contenedores o rol AcrPush en el registro de contenedores (para cargar imágenes)

• SDK de proyectos de Azure AI versión 2.1.0 o posterior

  pip install "azure-ai-projects>=2.1.0"
  

Compilación e inserción de la imagen de contenedor

1. Compile la imagen de Docker:

   docker build --platform linux/amd64 -t myagent:v1 .
   

   Consulte dockerfiles de ejemplo para Python y C#.

2. Inserción en Azure Container Registry:

   az acr login --name myregistry
   docker tag myagent:v1 myregistry.azurecr.io/myagent:v1
   docker push myregistry.azurecr.io/myagent:v1
   

Configuración de permisos de registro de contenedor

Conceda acceso a la identidad administrada del proyecto para extraer imágenes:

1. En el portal Azure, vaya al recurso del proyecto Foundry.

2. Seleccione Identidad y copie el ID del objeto (principal) en el Sistema asignado.

3. Asigne el rol Lector del repositorio de Container Registry a esta identidad en el registro de contenedor. Consulte roles y permisos de Azure Container Registry.

Creación de una versión del agente hospedado

La creación de una versión desencadena la plataforma para aprovisionar el agente automáticamente. No hay ningún paso de inicio independiente: la plataforma compila una instantánea de contenedor y hace que el agente esté listo para atender solicitudes.

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import HostedAgentDefinition, ProtocolVersionRecord, AgentProtocol
from azure.identity import DefaultAzureCredential

# Format: "https://resource_name.services.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"

# Create project client
credential = DefaultAzureCredential()
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=credential,
    allow_preview=True,
)

# Create a hosted agent version
agent = project.agents.create_version(
    agent_name="my-agent",
    definition=HostedAgentDefinition(
        container_protocol_versions=[
            ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="1.0.0")
        ],
        cpu="1",
        memory="2Gi",
        image="your-registry.azurecr.io/your-image:tag",
        environment_variables={
            "MODEL_DEPLOYMENT_NAME": "gpt-5-mini"
        }
    )
)

print(f"Agent created: {agent.name}, version: {agent.version}")

Para exponer ambos protocolos, pase ambos en container_protocol_versions:

container_protocol_versions=[
    ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="1.0.0"),
    ProtocolVersionRecord(protocol=AgentProtocol.INVOCATIONS, version="1.0.0")
],

Parámetros clave:

Consultar el estado de la versión

Después de crear una versión, sondee hasta que el estado sea active antes de invocar al agente. El aprovisionamiento suele tardar menos de un minuto en función del tamaño de la imagen.

import time

# Poll until the agent version is active
while True:
    version_info = project.agents.get_version(
        agent_name="my-agent",
        agent_version=agent.version
    )
    status = version_info["status"]
    print(f"Status: {status}")

    if status == "active":
        print("Agent is ready!")
        break
    elif status == "failed":
        print(f"Provisioning failed: {version_info['error']}")
        break

    time.sleep(5)

Valores de estado de versión:

Invocar al agente

Una vez que la versión alcance el estado active, use get_openai_client para crear un cliente de OpenAI enlazado al punto de conexión del agente.

Para el protocolo respuestas:

# Create an OpenAI client bound to the agent endpoint
openai_client = project.get_openai_client(agent_name="my-agent")

response = openai_client.responses.create(
    input="Hello! What can you do?",
)

print(response.output_text)

En el caso del protocolo Invocaciones, llame directamente al punto de conexión de invocaciones:

import requests

token = credential.get_token("https://ai.azure.com/.default").token
url = f"{PROJECT_ENDPOINT}/agents/my-agent/endpoint/protocols/invocations"

response = requests.post(url, headers={
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json",
    "Foundry-Features": "HostedAgents=V1Preview"
}, params={"api-version": "v1"}, json={
    "message": "Process this task"
})

print(response.json())

Para obtener ejemplos más completos, consulte ejemplos del agente hospedado.

Implementación mediante la API REST

Use la API REST para implementaciones directas basadas en HTTP o cuando se integre con herramientas personalizadas.

Antes de empezar, compile e inserte la imagen de contenedor y configure los permisos del registro de contenedor.

Configurar las variables

BASE_URL="https://{account}.services.ai.azure.com/api/projects/{project}"
API_VERSION="v1"
TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)

Crear un agente

curl -X POST "$BASE_URL/agents?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-agent",
    "definition": {
      "kind": "hosted",
      "image": "myacr.azurecr.io/my-agent:v1",
      "cpu": "1",
      "memory": "2Gi",
      "container_protocol_versions": [
        {"protocol": "responses", "version": "1.0.0"}
      ],
      "environment_variables": {
        "MODEL_DEPLOYMENT_NAME": "gpt-5-mini"
      }
    }
  }'

La creación de un agente también crea la versión 1 y desencadena el provisionamiento.

Consultar el estado de la versión

Sondee el punto de conexión de la versión hasta que status sea active.

while true; do
  STATUS=$(curl -s -X GET "$BASE_URL/agents/my-agent/versions/1?api-version=$API_VERSION" \
    -H "Authorization: Bearer $TOKEN" | jq -r '.status')
  echo "Status: $STATUS"
  [ "$STATUS" = "active" ] && echo "Ready!" && break
  [ "$STATUS" = "failed" ] && echo "Provisioning failed." && exit 1
  sleep 5
done

Invocar al agente

Use el punto de conexión dedicado del agente para enviar solicitudes. Configure "stream": true para recibir eventos enviados por el servidor.

Protocolo de respuestas:

curl -X POST "$BASE_URL/agents/my-agent/endpoint/protocols/openai/responses?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Hello! What can you do?",
    "store": true
  }'

Protocolo de invocaciones:

curl -X POST "$BASE_URL/agents/my-agent/endpoint/protocols/invocations?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Foundry-Features: HostedAgents=V1Preview" \
  -d '{
    "message": "Process this task"
  }'

Crear una nueva versión

Implemente el código o la configuración actualizados mediante la creación de una nueva versión:

curl -X POST "$BASE_URL/agents/my-agent/versions?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "definition": {
      "kind": "hosted",
      "image": "myacr.azurecr.io/my-agent:v2",
      "cpu": "1",
      "memory": "2Gi",
      "container_protocol_versions": [
        {"protocol": "responses", "version": "1.0.0"}
      ],
      "environment_variables": {
        "MODEL_DEPLOYMENT_NAME": "gpt-5-mini"
      }
    }
  }'

Limpieza de recursos

Para evitar cargos, limpie los recursos cuando termine. El proceso del agente se desactiva tras 15 minutos de inactividad, por lo que no hay ningún coste cuando un agente no atiende solicitudes.

limpieza de la CLI para desarrolladores de Azure

azd down

Limpieza del SDK

Elimine una sola versión:

project.agents.delete_version(agent_name="my-agent", agent_version=agent.version)

O elimine todo el agente y todas sus versiones:

project.agents.delete(agent_name="my-agent")

Limpieza de la API REST

Elimine una sola versión:

curl -X DELETE "$BASE_URL/agents/my-agent/versions/1?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN"

O elimine todo el agente:

curl -X DELETE "$BASE_URL/agents/my-agent?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN"

Solución de problemas

Los errores de aprovisionamiento aparecen en los campos error.code y error.message del objeto de versión. Compruebe el estado de la versión después de la creación para identificar problemas.

Para los errores 5xx, póngase en contacto con el soporte técnico de Microsoft.

Para obtener información detallada sobre los requisitos de RBAC y la solución de problemas de permisos, consulte Referencia de permisos del agente hospedado.

Pasos siguientes

Contenido relacionado

• ¿Qué son los agentes hospedados?
• Conceptos de identidad del agente
• Aplicaciones del agente
• documentación de Azure Container Registry