Implementación de un agente hospedado

En este artículo se muestra cómo implementar un agente en contenedor en el servicio Foundry Agent 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 desea 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. En el inicio rápido se utiliza la CLI de Azure para Desarrolladores (azd) o la extensión de VS Code, que gestionan automáticamente la compilación, el empuje, el control de versiones y la configuración de RBAC.

Ciclo de vida de la implementación

Cada implementación del agente hospedado sigue esta secuencia:

1. Build and push: 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 dedicada del agente Entra.
3. Sondear el estado — esperar a que el estado de la versión alcance active.
4. Invoke: envíe solicitudes al punto de conexión dedicado del agente.

Requisitos previos

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

Permisos necesarios

Usted necesita Azure AI Project Manager en el alcance del proyecto para crear y desplegar agentes hospedados. Este rol incluye los permisos del plano de datos para crear agentes y la capacidad de asignar el rol Azure usuario de IA a la identidad del agente creada por la plataforma. La identidad del agente necesita 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)
• Azure AI User para la identidad de agente creada por la plataforma (acceso a modelo de tiempo de ejecución y herramientas)

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

Requisitos de contenedor

La imagen de contenedor debe cumplir los siguientes requisitos para ejecutarse en la plataforma del 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. Utilice las bibliotecas de protocolos en su marco existente, ya sea que se trate de Microsoft Agent Framework, LangChain o código personalizado.

Puntos finales 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 un entorno de producción, el gateway de Foundry controla el enrutamiento; 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 insertadas en la plataforma; agent.yaml se establecen automáticamente.

Las variables que declaras tú mismo, 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.

Empaquetar y probar el agente localmente

Antes de realizar la implementación en Foundry, valide que el agente funciona localmente mediante la biblioteca de protocolos. El contenedor provee los mismos puntos de conexión en local 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 de invocaciones

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 de Azure Developer (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 implementaciones de agente directamente desde Python código.

Requisitos previos adicionales

• Python 3.10 o posterior

• Imagen de contenedor en Azure Container Registry

• Escritor de repositorios de Container Registry o rol AcrPush en el registro de contenedor (para insertar imágenes)

• Azure SDK de proyectos de IA 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. Empujar al Registro de Contenedores de Azure

   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 a la identidad administrada del proyecto acceso para obtener imágenes.

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

2. Seleccione Identidad y copie el identificador de objeto (principal) en Asignado por el sistema.

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:

Invoca al agente

Una vez que la versión alcance el estado active, utilice get_openai_client para crear un cliente de OpenAI vinculado 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)

Para el protocolo de invocaciones, llame directamente al endpoint 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 los 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 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)

Creación de 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 aprovisionamiento.

Consultar el estado de la versión

Sondee el punto de conexión de 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

Invoca al agente

Use el punto de conexión dedicado del agente para enviar solicitudes. Configura "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"
  }'

Creación de 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 cómputo del agente se desaprovisiona después de 15 minutos de inactividad, por lo que no hay ningún costo cuando un agente no está sirviendo 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 surgen 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 alojados?
• Conceptos de identidad del agente
• Aplicaciones del agente
• documentación de Azure Container Registry