Implementación de un agente hospedado

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

La CLI para desarrolladores de Azure (azd) y el kit de herramientas Microsoft Foundry para Visual Studio Code automatizan el ciclo de vida completo de la implementación: compilar el contenedor, enviarlo a Azure Container Registry, crear la versión del agente y asignar roles RBAC. Para ver un tutorial guiado por primera vez, consulte inicio rápido: Creación e implementación de un agente hospedado.

Implementación con un comando

Desde el directorio del proyecto del agente, aprovisione la infraestructura e implemente en un solo paso:

azd up

azd up combina azd provision, que crea el proyecto de Foundry, el despliegue del modelo, el registro de contenedores, Application Insights y la identidad administrada, con azd deploy. Úselo para implementaciones por primera vez o cada vez que cambie tanto la infraestructura como el código del agente.

Implementar solo cambios de código

Si ya aprovisionó los recursos de Azure y solo necesita insertar una nueva versión del agente:

azd deploy

Durante azd deploy, la CLI:

1. Compila la imagen de contenedor de forma remota en Azure Container Registry, por lo que no necesita Docker local.
2. Inserta la imagen en el registro.
3. Crea una versión del agente alojado en el servicio Foundry Agent Service.
4. Crea una identidad de agente de Microsoft Entra dedicada y asigna los roles de RBAC que el agente necesita para acceder a modelos y herramientas.

Administración de versiones

Cada azd deploy crea una nueva versión del agente. La CLI conserva las versiones anteriores y la versión más reciente está activa de forma predeterminada.

Comprobación de la implementación

azd ai agent show

La salida incluye el nombre del agente, la versión, los protocolos, los recursos de contenedor, las variables de entorno y la marca de tiempo de creación. Se usa --output table para una vista de resumen.

Creación de imágenes localmente

De forma predeterminada, azd compila imágenes de contenedor de forma remota en Azure Container Registry. Para compilar imágenes localmente, establezca remoteBuild: false en azure.yaml. Las compilaciones locales requieren Docker Desktop.

Para filtrar las indicaciones y las respuestas conforme a una política de seguridad de contenidos, añade una barrera de seguridad de contenido a tu agente.

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)

• Azure SDK de proyectos de IA versión 2.3.0 o posterior

  pip install "azure-ai-projects>=2.3.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

Al crear una versión, la plataforma aprovisiona automáticamente el agente. 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 (
    AgentEndpointProtocol,
    ContainerConfiguration,
    HostedAgentDefinition,
    ProtocolVersionRecord,
)
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,
)

# Create a hosted agent version
agent = project.agents.create_version(
    agent_name="my-agent",
    definition=HostedAgentDefinition(
        protocol_versions=[
            ProtocolVersionRecord(protocol=AgentEndpointProtocol.RESPONSES, version="1.0.0")
        ],
        cpu="1",
        memory="2Gi",
        container_configuration=ContainerConfiguration(
            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 protocol_versions:

protocol_versions=[
    ProtocolVersionRecord(protocol=AgentEndpointProtocol.RESPONSES, version="1.0.0"),
    ProtocolVersionRecord(protocol=AgentEndpointProtocol.INVOCATIONS, version="1.0.0"),
    ProtocolVersionRecord(protocol=AgentEndpointProtocol.INVOCATIONS_WS, version="1.0.0"),
],

Parámetros clave:

Para configurar cuándo la capacidad de cómputo de la sesión pasa a estar inactiva, consulte Gestionar la inactividad de la sesión.

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",
}, 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 el SDK de JavaScript/TypeScript

Use el SDK cuando quiera administrar implementaciones de agente directamente desde Node.js código. El componente que llama al SDK se ejecuta en Node.js, pero la propia imagen del contenedor sigue ejecutando el código de su agente de Python o .NET compilado con las bibliotecas de protocolo Responses o Invocations; no existe un entorno de ejecución de agente alojado para Node.js.

Requisitos previos adicionales

• Node.js 22 o una versión 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)

• Los paquetes @azure/ai-projects y @azure/identity

  npm install @azure/ai-projects @azure/identity
  

Antes de empezar, compile e inserte la imagen de contenedor en Azure Container Registry (consulte la pestaña Python, por ejemplo, comandos de Docker) y conceda a la identidad administrada del proyecto el rol Lector del repositorio de Container Registry en el registro.

Creación de una versión del agente hospedado

Al crear una versión, la plataforma aprovisiona automáticamente el agente. 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.

import { AIProjectClient } from "@azure/ai-projects";
import { DefaultAzureCredential } from "@azure/identity";

// Format: "https://resource_name.services.ai.azure.com/api/projects/project_name"
const projectEndpoint =
  process.env["FOUNDRY_PROJECT_ENDPOINT"] || "your_project_endpoint";
const agentName = "my-agent";

const project = new AIProjectClient(
  projectEndpoint,
  new DefaultAzureCredential(),
);

// Create a hosted agent version
const agent = await project.agents.createVersion(agentName, {
  kind: "hosted",
  cpu: "1",
  memory: "2Gi",
  container_configuration: {
    image: "your-registry.azurecr.io/your-image:tag",
  },
  protocol_versions: [{ protocol: "responses", version: "1.0.0" }],
  environment_variables: { MODEL_DEPLOYMENT_NAME: "gpt-5-mini" },
});

console.log(`Agent created: ${agent.name}, version: ${agent.version}`);

Para exponer ambos protocolos, pase ambos en protocol_versions:

protocol_versions: [
  { protocol: "responses", version: "1.0.0" },
  { protocol: "invocations", version: "1.0.0" },
  { protocol: "invocations_ws", version: "1.0.0" },
],

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.

function sleep(ms: number) {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

// Poll until the agent version is active
for (;;) {
  const versionInfo = await project.agents.getVersion(
    agentName,
    agent.version,
  );
  console.log(`Status: ${versionInfo.status}`);
  if (versionInfo.status === "active") {
    break;
  }
  if (versionInfo.status === "failed") {
    console.log(`Provisioning failed: ${versionInfo.error}`);
    break;
  }
  await sleep(5_000);
}

Dirigir el punto de conexión del agente e invocarlo

Enrute el punto de conexión del agente a la versión que creó y, a continuación, enlace un cliente de OpenAI al punto de conexión.

Para el protocolo respuestas:

await project.agents.patchAgentObject(agentName, {
  agentEndpoint: {
    version_selector: {
      version_selection_rules: [
        {
          type: "FixedRatio",
          agent_version: agent.version,
          traffic_percentage: 100,
        },
      ],
    },
    protocol_configuration: { responses: {} },
  },
});

// Create an OpenAI client bound to the agent endpoint
const openAIClient = project.getOpenAIClient({
  azureConfig: { allowPreview: true, agentName },
});

const response = await openAIClient.responses.create({
  input: "Hello! What can you do?",
});
console.log(response.output_text);

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

const credential = new DefaultAzureCredential();
const token = await credential.getToken("https://ai.azure.com/.default");
if (!token) {
  throw new Error("Failed to acquire an access token.");
}
const url = `${projectEndpoint}/agents/my-agent/endpoint/protocols/invocations`;

const response = await fetch(`${url}?api-version=v1`, {
  method: "POST",
  headers: {
    Authorization: "Bearer " + token.token,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ message: "Process this task" }),
});
console.log(await response.json());

Referencia: AIProjectClient

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 en Azure Container Registry y conceda a la identidad administrada del proyecto el rol Lector de repositorio de Container Registry en el registro.

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",
      "container_configuration": {
        "image": "myacr.azurecr.io/my-agent:v1"
      },
      "cpu": "1",
      "memory": "2Gi",
      "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.

Para configurar cuándo la capacidad de cómputo de la sesión pasa a estar inactiva, consulte Gestionar la inactividad de la sesión.

Para filtrar las instrucciones y las respuestas conforme a una política de seguridad de contenido, incluya un objeto rai_config en definition. Consulte Añadir una protección de seguridad del contenido a un agente alojado.

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" \
  -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",
      "container_configuration": {
        "image": "myacr.azurecr.io/my-agent:v2"
      },
      "cpu": "1",
      "memory": "2Gi",
      "protocol_versions": [
        {"protocol": "responses", "version": "1.0.0"}
      ],
      "environment_variables": {
        "MODEL_DEPLOYMENT_NAME": "gpt-5-mini"
      }
    }
  }'

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 el agente completo y todas sus versiones. Use force=True para eliminar en cascada las sesiones activas, como justo después de invocar al agente; sin ella, la llamada produce un error de conflicto mientras las sesiones están activas:

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

Limpieza del SDK

Elimine una sola versión:

await project.agents.deleteVersion("my-agent", agent.version);

O elimine todo el agente y todas sus versiones:

await project.agents.delete("my-agent", { force: true });

Referencia: AIProjectClient

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"