Azure AI Hosted Agents (Python)

O que Azure AI Hosted Agents (Python) faz?

Construa agentes hospedados baseados em contêiner usando ImageBasedHostedAgentDefinition do SDK Azure AI Projects.

Instalação

pip install azure-ai-projects>=2.0.0b3 azure-identity

Versão mínima do SDK: 2.0.0b3 ou posterior necessária para suporte a agente hospedado.

Variáveis de Ambiente

AZURE_AI_PROJECT_ENDPOINT=https://<resource>.services.ai.azure.com/api/projects/<project>

Pré-requisitos

Antes de criar agentes hospedados:

1. Imagem do Contêiner - Construa e envie para o Azure Container Registry (ACR)
2. Permissões de Pull no ACR - Conceda à identidade gerenciada do seu projeto a função AcrPull no ACR
3. Host de Capacidade - Host de capacidade em nível de conta com enablePublicHostingEnvironment=true
4. Versão do SDK - Garanta azure-ai-projects>=2.0.0b3

Autenticação

Sempre use 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
)

Fluxo de Trabalho Principal

1. Importações

import os
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    ImageBasedHostedAgentDefinition,
    ProtocolVersionRecord,
    AgentProtocol,
)

2. Criar Agente Hospedado

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 criado: {agent.name} (versão: {agent.version})")

3. Listar Versões do Agente

versions = client.agents.list_versions(agent_name="my-hosted-agent")
for version in versions:
    print(f"Versão: {version.version}, Estado: {version.state}")

4. Excluir Versão do Agente

client.agents.delete_version(
    agent_name="my-hosted-agent",
    version=agent.version
)

Parâmetros do ImageBasedHostedAgentDefinition

Parâmetro	Tipo	Obrigatório	Descrição
container_protocol_versions	list[ProtocolVersionRecord]	Sim	Versões de protocolo que o agente suporta
image	str	Sim	Caminho completo da imagem do contêiner (registry/imagem:tag)
cpu	str	Não	Alocação de CPU (ex.: "1", "2")
memory	str	Não	Alocação de memória (ex.: "2Gi", "4Gi")
tools	list[dict]	Não	Ferramentas disponíveis para o agente
environment_variables	dict[str, str]	Não	Variáveis de ambiente para o contêiner

Versões de Protocolo

O parâmetro container_protocol_versions especifica quais protocolos seu agente suporta:

from azure.ai.projects.models import ProtocolVersionRecord, AgentProtocol

# Protocolo RESPONSES - respostas padrão do agente
container_protocol_versions=[
    ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="v1")
]

Protocolos Disponíveis:

Protocolo	Descrição
AgentProtocol.RESPONSES	Protocolo de resposta padrão para interações com o agente

Alocação de Recursos

Especifique CPU e memória para seu contêiner:

definition=ImageBasedHostedAgentDefinition(
    container_protocol_versions=[...],
    image="myregistry.azurecr.io/my-agent:latest",
    cpu="2",      # 2 núcleos de CPU
    memory="4Gi"  # 4 GiB de memória
)

Limites de Recursos:

Recurso	Mínimo	Máximo	Padrão
CPU	0.5	4	1
Memória	1Gi	8Gi	2Gi

Configuração de Ferramentas

Adicione ferramentas ao seu agente hospedado:

Interpretador de Código

tools=[{"type": "code_interpreter"}]

Ferramentas MCP

tools=[
    {"type": "code_interpreter"},
    {
        "type": "mcp",
        "server_label": "my-mcp-server",
        "server_url": "https://my-mcp-server.example.com"
    }
]

Múltiplas Ferramentas

tools=[
    {"type": "code_interpreter"},
    {"type": "file_search"},
    {
        "type": "mcp",
        "server_label": "custom-tool",
        "server_url": "https://custom-tool.example.com"
    }
]

Variáveis de Ambiente

Passe configuração para seu contêiner:

environment_variables={
    "AZURE_AI_PROJECT_ENDPOINT": os.environ["AZURE_AI_PROJECT_ENDPOINT"],
    "MODEL_NAME": "gpt-4o-mini",
    "LOG_LEVEL": "INFO",
    "CUSTOM_CONFIG": "value"
}

Melhor Prática: Nunca codifique segredos. Use variáveis de ambiente ou Azure Key Vault.

Exemplo 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():
    """Criar um agente hospedado com imagem de contêiner 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 hospedado criado: {agent.name}")
    print(f"Versão: {agent.version}")
    print(f"Estado: {agent.state}")
    
    return agent

if __name__ == "__main__":
    create_hosted_agent()

Padrão Assí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():
    """Criar um agente hospedado de forma assí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

Erros Comuns

Erro	Causa	Solução
ImagePullBackOff	Permissão de pull no ACR negada	Conceda a função AcrPull à identidade gerenciada do projeto
InvalidContainerImage	Imagem não encontrada	Verifique se o caminho e a tag da imagem existem no ACR
CapabilityHostNotFound	Nenhum host de capacidade configurado	Crie um host de capacidade em nível de conta
ProtocolVersionNotSupported	Versão de protocolo inválida	Use AgentProtocol.RESPONSES com versão "v1"

Melhores Práticas

1. Versionar Suas Imagens - Use tags específicas, não latest em produção
2. Recursos Mínimos - Comece com CPU/memória mínimos, aumente conforme necessário
3. Variáveis de Ambiente - Use para toda configuração, nunca codifique
4. Tratamento de Erros - Envolva a criação do agente em blocos try/except
5. Limpeza - Exclua versões não utilizadas do agente para liberar recursos

Links de Referência

• SDK Azure AI Projects
• Documentação de Agentes Hospedados
• Azure Container Registry

Quando Usar

Esta habilidade é aplicável para executar o fluxo de trabalho ou ações descritas na visão geral.

Limitações

• Use esta habilidade apenas quando a tarefa corresponder claramente ao escopo descrito acima.
• Não trate a saída como substituta para validação específica do ambiente, teste ou revisão de especialistas.
• Pare e peça esclarecimentos se as entradas necessárias, permissões, limites de segurança ou critérios de sucesso estiverem ausentes.