¿Qué hace Agentes Alojados de Azure AI (Python)?
Construye agentes alojados basados en contenedores usando ImageBasedHostedAgentDefinition del SDK de Azure AI Projects.
Instalación
pip install azure-ai-projects>=2.0.0b3 azure-identity
Versión mínima del SDK: 2.0.0b3 o posterior para soporte de agente alojado.
Variables de Entorno
AZURE_AI_PROJECT_ENDPOINT=https://<resource>.services.ai.azure.com/api/projects/<project>
Prerrequisitos
Antes de crear agentes alojados:
- Imagen de Contenedor - Construir y subir a Azure Container Registry (ACR)
- Permisos de extracción de ACR - Conceder el rol
AcrPulla la identidad gestionada de tu proyecto en el ACR - Capability Host - Host de capacidad a nivel de cuenta con
enablePublicHostingEnvironment=true - Versión del SDK - Asegurar
azure-ai-projects>=2.0.0b3
Autenticación
Usar siempre DefaultAzureCredential:
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
credential = DefaultAzureCredential()
client = AIProjectClient(
endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
credential=credential
)
Flujo de Trabajo Principal
1. Importaciones
import os
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
ImageBasedHostedAgentDefinition,
ProtocolVersionRecord,
AgentProtocol,
)
2. Crear Agente Alojado
client = AIProjectClient(
endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
credential=DefaultAzureCredential()
)
agent = client.agents.create_version(
agent_name="my-hosted-agent",
definition=ImageBasedHostedAgentDefinition(
container_protocol_versions=[
ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="v1")
],
cpu="1",
memory="2Gi",
image="myregistry.azurecr.io/my-agent:latest",
tools=[{"type": "code_interpreter"}],
environment_variables={
"AZURE_AI_PROJECT_ENDPOINT": os.environ["AZURE_AI_PROJECT_ENDPOINT"],
"MODEL_NAME": "gpt-4o-mini"
}
)
)
print(f"Agente creado: {agent.name} (versión: {agent.version})")
3. Listar Versiones del Agente
versions = client.agents.list_versions(agent_name="my-hosted-agent")
for version in versions:
print(f"Versión: {version.version}, Estado: {version.state}")
4. Eliminar Versión del Agente
client.agents.delete_version(
agent_name="my-hosted-agent",
version=agent.version
)
Parámetros de ImageBasedHostedAgentDefinition
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
container_protocol_versions | list[ProtocolVersionRecord] | Sí | Versiones de protocolo que soporta el agente |
image | str | Sí | Ruta completa de la imagen del contenedor (registro/imagen:tag) |
cpu | str | No | Asignación de CPU (ej., "1", "2") |
memory | str | No | Asignación de memoria (ej., "2Gi", "4Gi") |
tools | list[dict] | No | Herramientas disponibles para el agente |
environment_variables | dict[str, str] | No | Variables de entorno para el contenedor |
Versiones de Protocolo
El parámetro container_protocol_versions especifica qué protocolos soporta tu agente:
from azure.ai.projects.models import ProtocolVersionRecord, AgentProtocol
# Protocolo RESPONSES - respuestas estándar del agente
container_protocol_versions=[
ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="v1")
]
Protocolos Disponibles:
| Protocolo | Descripción |
|---|---|
AgentProtocol.RESPONSES | Protocolo de respuesta estándar para interacciones del agente |
Asignación de Recursos
Especifica CPU y memoria para tu contenedor:
definition=ImageBasedHostedAgentDefinition(
container_protocol_versions=[...],
image="myregistry.azurecr.io/my-agent:latest",
cpu="2", # 2 núcleos de CPU
memory="4Gi" # 4 GiB de memoria
)
Límites de Recursos:
| Recurso | Mín | Máx | Predeterminado |
|---|---|---|---|
| CPU | 0.5 | 4 | 1 |
| Memoria | 1Gi | 8Gi | 2Gi |
Configuración de Herramientas
Añade herramientas a tu agente alojado:
Intérprete de Código
tools=[{"type": "code_interpreter"}]
Herramientas MCP
tools=[
{"type": "code_interpreter"},
{
"type": "mcp",
"server_label": "my-mcp-server",
"server_url": "https://my-mcp-server.ejemplo.com"
}
]
Múltiples Herramientas
tools=[
{"type": "code_interpreter"},
{"type": "file_search"},
{
"type": "mcp",
"server_label": "custom-tool",
"server_url": "https://custom-tool.ejemplo.com"
}
]
Variables de Entorno
Pasa configuración a tu contenedor:
environment_variables={
"AZURE_AI_PROJECT_ENDPOINT": os.environ["AZURE_AI_PROJECT_ENDPOINT"],
"MODEL_NAME": "gpt-4o-mini",
"LOG_LEVEL": "INFO",
"CUSTOM_CONFIG": "value"
}
Mejores Prácticas: Nunca codificar secretos. Usa variables de entorno o Azure Key Vault.
Ejemplo Completo
import os
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
ImageBasedHostedAgentDefinition,
ProtocolVersionRecord,
AgentProtocol,
)
def create_hosted_agent():
"""Crea un agente alojado con imagen de contenedor personalizada."""
client = AIProjectClient(
endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
credential=DefaultAzureCredential()
)
agent = client.agents.create_version(
agent_name="data-processor-agent",
definition=ImageBasedHostedAgentDefinition(
container_protocol_versions=[
ProtocolVersionRecord(
protocol=AgentProtocol.RESPONSES,
version="v1"
)
],
image="myregistry.azurecr.io/data-processor:v1.0",
cpu="2",
memory="4Gi",
tools=[
{"type": "code_interpreter"},
{"type": "file_search"}
],
environment_variables={
"AZURE_AI_PROJECT_ENDPOINT": os.environ["AZURE_AI_PROJECT_ENDPOINT"],
"MODEL_NAME": "gpt-4o-mini",
"MAX_RETRIES": "3"
}
)
)
print(f"Agente alojado creado: {agent.name}")
print(f"Versión: {agent.version}")
print(f"Estado: {agent.state}")
return agent
if __name__ == "__main__":
create_hosted_agent()
Patrón Asíncrono
import os
from azure.identity.aio import DefaultAzureCredential
from azure.ai.projects.aio import AIProjectClient
from azure.ai.projects.models import (
ImageBasedHostedAgentDefinition,
ProtocolVersionRecord,
AgentProtocol,
)
async def create_hosted_agent_async():
"""Crea un agente alojado de forma asíncrona."""
async with DefaultAzureCredential() as credential:
async with AIProjectClient(
endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
credential=credential
) as client:
agent = await client.agents.create_version(
agent_name="async-agent",
definition=ImageBasedHostedAgentDefinition(
container_protocol_versions=[
ProtocolVersionRecord(
protocol=AgentProtocol.RESPONSES,
version="v1"
)
],
image="myregistry.azurecr.io/async-agent:latest",
cpu="1",
memory="2Gi"
)
)
return agent
Errores Comunes
| Error | Causa | Solución |
|---|---|---|
ImagePullBackOff | Permiso de extracción de ACR denegado | Conceder rol AcrPull a la identidad gestionada del proyecto |
InvalidContainerImage | Imagen no encontrada | Verificar que la ruta y etiqueta de la imagen existan en ACR |
CapabilityHostNotFound | No hay host de capacidad configurado | Crear host de capacidad a nivel de cuenta |
ProtocolVersionNotSupported | Versión de protocolo no válida | Usar AgentProtocol.RESPONSES con versión "v1" |
Mejores Prácticas
- Versiona tus Imágenes - Usa etiquetas específicas, no
latesten producción - Recursos Mínimos - Comienza con CPU/memoria mínimos, escala según sea necesario
- Variables de Entorno - Usa para toda la configuración, nunca codificar
- Manejo de Errores - Envuelve la creación del agente en bloques try/except
- Limpieza - Elimina versiones de agentes no utilizadas para liberar recursos
Enlaces de Referencia
Cuándo Usar
Esta habilidad es aplicable para ejecutar el flujo de trabajo o las acciones descritas en la visión general.
Limitaciones
- Usa esta habilidad solo cuando la tarea coincida claramente con el alcance descrito anteriormente.
- No trates la salida como un sustituto de la validación específica del entorno, pruebas o revisión de expertos.
- Detente y pide aclaración si faltan entradas requeridas, permisos, límites de seguridad o criterios de éxito.