Compatibilidade e Manutenção

Alias de compatibilidade de hosted-agents-v2-py; use esse ID para novas referências quando nenhum contrato existente exigir este. O procedimento apenas de instrução permanece local; nenhum arquivo de suporte executável é empacotado, então instalações existentes continuam funcionando offline. Este guia de compatibilidade documenta o procedimento do agente hospedado, não uma capacidade adicional; cópias mais antigas podem usar nomes de pré-visualização aposentados. Preserve o ID chamável quando um manifesto existente ou configuração de cliente o utiliza. Modificado em AAS em 2026-09-05; metadados originais e avisos de licença são retidos.

Agentes Hospedados do Azure AI (Python)

Crie agentes hospedados baseados em contêiner usando HostedAgentDefinition do SDK do Azure AI Projects.

Instalação

pip install 'azure-ai-projects==2.3.0' azure-identity

Estes são fragmentos de instrução do SDK 2.3.0 alinhados com o guia atual do agente hospedado da Microsoft. Valide o esquema instalado e o suporte do serviço antes do provisionamento; a inspeção da documentação não é um teste de integração na nuvem.

Variáveis de Ambiente

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

Pré-requisitos

Antes de criar agentes hospedados:

1. Imagem de Contêiner - Crie e envie para o Azure Container Registry (ACR)
2. Permissões de Pull do ACR - Conceda à identidade do projeto a função de registro suportada pelo seu modo de permissão; a orientação atual para agentes hospedados usa Container Registry Repository Reader
3. Host de Capacidade - Confirme a disponibilidade atual do agente hospedado no projeto/região e a política de rede da aplicação; não habilite o hospedagem pública automaticamente
4. Versão do SDK - Garanta azure-ai-projects==2.3.0

Autenticação

Use o fluxo de credenciais Azure aprovado para o tenant/assinatura pretendido; este esboço usa DefaultAzureCredential:

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

import os

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 (
    HostedAgentDefinition,
    ContainerConfiguration,
    ProtocolVersionRecord,
    AgentEndpointProtocol,
)

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=HostedAgentDefinition(
        protocol_versions=[
            ProtocolVersionRecord(protocol=AgentEndpointProtocol.RESPONSES, version="2.0.0")
        ],
        cpu="1",
        memory="2Gi",
        container_configuration=ContainerConfiguration(image=os.environ["REVIEWED_CONTAINER_IMAGE"]),
        environment_variables={
            "AZURE_AI_PROJECT_ENDPOINT": os.environ["AZURE_AI_PROJECT_ENDPOINT"],
            "MODEL_NAME": os.environ["MODEL_DEPLOYMENT_NAME"]
        }
    )
)

print(f"Created agent: {agent.name} (version: {agent.version})")

3. Listar Versões do Agente

versions = client.agents.list_versions(agent_name="my-hosted-agent")
for version in versions:
    print(f"Version: {version.version}")  # Inspect supported status fields via get_version

Inspecione o modelo exato retornado para campos suportados; uma versão criada não é prova de que um contêiner em execução está saudável. Feche os recursos síncronos do cliente/credenciais através de seus gerenciadores de contexto suportados ou métodos close().

4. Excluir Versão do Agente

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

Parâmetros de HostedAgentDefinition

Versões de Protocolo

…