Implantar um agente hospedado

Este artigo mostra como implantar um agente em contêineres no Serviço do Agente do Foundry usando a CLI do Desenvolvedor do Azure (azd), o SDK do Python ou a API REST. Escolha um método de implantação usando o seletor na parte superior do artigo. Use as abordagens SDK ou REST quando quiser gerenciar implantações de agente diretamente de seus próprios aplicativos ou serviços.

Se você estiver implantando pela primeira vez ou quiser um passo a passo guiado, confira o Início Rápido: Criar e implantar um agente hospedado. A CLI do Desenvolvedor do Azure (azd) e a extensão do VS Code cuidam automaticamente da compilação, do envio, do versionamento e da configuração de RBAC.

Dica

Prefere um loop interno sem Docker? Você também pode implantar um agente hospedado diretamente do código-fonte – carregar um .zip de seus Python ou .NET código e a plataforma compila e hospeda-o para você.

Ciclo de vida da implantação

Cada implantação de agente hospedado segue esta sequência:

  1. Compile e envie - Empacote o código do agente em uma imagem de contêiner e envie-a para o Registro de Contêiner do Azure.
  2. Criar uma versão do agente - Registre a imagem com o Serviço de Agente do Foundry. A plataforma provisiona a infraestrutura e cria uma identidade de agente do Entra dedicada.
  3. Verificar o status - Aguarde até que o status da versão atinja active.
  4. Invocar - Enviar solicitações para o endpoint dedicado do agente.

Pré-requisitos

Permissões necessárias

Você precisa ter a função Gerenciador de Projeto do Foundry no escopo do projeto para implantar um agente hospedado. Essa função concede permissões de plano de dados para criar e atualizar agentes, além da capacidade de criar atribuições de função para a identidade do agente criada pela plataforma, se necessário. Para obter um detalhamento das permissões envolvidas, consulte a referência de permissões do agente hospedado.

Importante

As funções RBAC do Foundry foram renomeadas recentemente. Foundry User, Foundry Owner, Foundry Account Owner e Foundry Project Manager eram anteriormente chamados de Usuário do Azure AI, Proprietário do Azure AI, Proprietário da conta do Azure AI e Gerente de Projeto do Azure AI. Você ainda pode ver os nomes anteriores em alguns lugares enquanto essa mudança de nome está sendo implementada. Os IDs das funções e as permissões principais não são alterados com a mudança de nome.

A plataforma cria uma identidade de agente de Microsoft Entra dedicada para cada agente hospedado no momento da implantação. Essa identidade é um principal de serviço que o contêiner em execução usa para acessar modelos e ferramentas. Você não precisa configurar identidades gerenciadas manualmente. A identidade do agente pode acessar a inferência de modelos por meio do endpoint do projeto e do armazenamento de sessão, por padrão. Para recursos externos (por exemplo, seu próprio Armazenamento do Azure), atribua funções RBAC manualmente à Microsoft Entra ID do agente. Para obter mais informações, consulte o acesso do Agente além dos padrões.

Se você usar azd ou a extensão do VS Code, as ferramentas lidam com a maioria das atribuições de RBAC automaticamente, incluindo Leitor de Repositório de Registro de Contêiner para a identidade gerenciada do projeto (extrações de imagem).

Para obter mais informações, consulte Autenticação e autorização.

Importante

O suporte para implantar o Registro de Contêiner do Azure do seu agente hospedado em uma rede privada (ponto de extremidade privado com o acesso à rede pública desativado) depende de quando o projeto Foundry foi criado. Os projetos criados após 25 de junho de 2026 dão suporte a um registro privado. Projetos criados antes dessa data exigem que o registro esteja acessível por meio do seu endpoint público para que a plataforma possa baixar a imagem. Os projetos existentes não são afetados. Para obter a lista completa de restrições de rede, consulte Limitações.

Requisitos de contêiner

Sua imagem de contêiner deve atender aos requisitos a seguir para ser executada na plataforma do agente hospedado.

Importante

A plataforma de hospedagem requer imagens de contêiner x86_64 (linux/amd64). Se você estiver desenvolvendo no Apple Silicon ou em outros computadores baseados em ARM, use docker build --platform linux/amd64 . para evitar a criação de uma imagem ARM incompatível.

Bibliotecas de protocolo

Os agentes hospedados se comunicam com o gateway do Foundry por meio de bibliotecas de protocolo. Escolha o protocolo que corresponde ao padrão de interação do agente:

Protocolo biblioteca de Python biblioteca de .NET Ponto de extremidade Melhor para
Respostas azure-ai-agentserver-responses Azure.AI.AgentServer.Responses /responses Chatbots de conversa, streaming, vários turnos com histórico gerenciado pela plataforma
Invocações azure-ai-agentserver-invocations Azure.AI.AgentServer.Invocations /invocations Receptores de webhook, processamento não conversacional, fluxos de trabalho assíncronos personalizados
Invocações (WebSocket) azure-ai-agentserver-invocations Azure.AI.AgentServer.Invocations /invocations_ws Streaming bidirecional: agentes de voz em tempo real, mídia interativa

O protocolo WebSocket usa o identificador invocations_ws e envia no mesmo azure-ai-agentserver-invocations pacote que a rota HTTP /invocations , para que um contêiner possa atender a ambos. Use isso quando precisar de streaming persistente e bidirecional completo, por exemplo, para enviar PCM do microfone ao agente e receber de volta áudio sintetizado. Para cenários de voz, consulte Criar um agente de voz com agentes hospedados.

Um único contêiner pode expor vários protocolos simultaneamente declarando-os quando você cria o agente - no protocols campo do azure.ai.agent serviço em azure.yaml, uma chamada do SDK ou uma solicitação de API REST - e importando as bibliotecas necessárias. Use as bibliotecas de protocolo em sua estrutura existente, seja o Microsoft Agent Framework, o LangChain ou o código personalizado.

Biblioteca de protocolos de respostas

As bibliotecas Python e .NET para o protocolo Respostas implementam a API de Respostas de IA Azure. Importe o pacote e implemente a IResponseHandler interface. A biblioteca lida com roteamento, streaming com SSE (eventos enviados pelo servidor), execução em segundo plano, cancelamento, cache e gerenciamento do ciclo de vida de resposta.

IResponseHandler

IResponseHandler é a abstração principal que você implementa. A biblioteca chama CreateAsync para cada solicitação de entrada e entrega o IAsyncEnumerable<ResponseStreamEvent> retornado aos clientes por meio de SSE:

public class EchoHandler : ResponseHandler
{
    public override IAsyncEnumerable<ResponseStreamEvent> CreateAsync(
        CreateResponse request,
        ResponseContext context,
        CancellationToken cancellationToken)
    {
        return new TextResponse(context, request,
            createText: async ct =>
            {
                var input = await context.GetInputTextAsync(cancellationToken: ct);
                return $"Echo: {input}";
            });
    }
}

ResponseEventStream

ResponseEventStream gerencia sequenceNumber, outputIndex, contentIndex, itemId e o ciclo de vida completo de Response automaticamente. Cada yield return corresponde diretamente a um evento SSE, então você não precisa acompanhar esse estado sozinho.

Modos de streaming e em segundo plano

  • Modo de streaming (padrão): os eventos SSE são entregues em tempo real ao cliente conectado.
  • Modo de plano de fundo: o manipulador é executado até a conclusão sem um cliente SSE conectado. Os eventos são armazenados em buffer e estão disponíveis para reprodução por meio do GET /responses/{id}.

Ciclo de vida de resposta

A biblioteca orquestra o ciclo de vida completo da resposta: created ->in_progress ->completed (ou failed ou cancelled). A biblioteca também gerencia automaticamente o cancelamento, o tratamento de erros e as garantias de eventos terminais.

Segurança de thread

Todas as instâncias de serviço registradas por meio de AddResponsesServer() são seguras para threads. As instâncias do manipulador são definidas por solicitação.

Para obter diretrizes detalhadas de implementação do manipulador, consulte o guia de implementação handler. Para obter exemplos executáveis, consulte os exemplos de protocolo Responses.

Pontos de extremidade de integridade

As bibliotecas de protocolo expõem automaticamente um(a) /readiness endpoint para verificações de integridade da plataforma. Você não precisa implementar isso por conta própria.

Porta

Os contêineres atendem o tráfego na porta 8088 localmente. Na produção, o gateway do Foundry cuida do roteamento; seu contêiner não precisa expor uma porta pública.

Variáveis de ambiente injetadas na plataforma

A plataforma do agente hospedado injeta automaticamente variáveis de ambiente no contêiner em runtime. Seu código pode ler essas variáveis sem declará-las no mapa env do serviço azure.ai.agent em azure.yaml nem nas configurações de variáveis de ambiente do SDK e da REST. O FOUNDRY_* prefixo é reservado para uso de plataforma.

Variável Propósito
FOUNDRY_PROJECT_ENDPOINT URL do endpoint do projeto Foundry
FOUNDRY_PROJECT_ARM_ID ID do recurso ARM do projeto Foundry
FOUNDRY_AGENT_NAME Nome do agente em execução
FOUNDRY_AGENT_VERSION Versão do agente em execução
FOUNDRY_AGENT_SESSION_ID ID da sessão para a solicitação atual (somente contêineres hospedados)
APPLICATIONINSIGHTS_CONNECTION_STRING Cadeia de conexão do Application Insights para telemetria

Não redeclare variáveis injetadas na plataforma em azure.yaml : elas são definidas automaticamente.

Variáveis que você declara, como MODEL_DEPLOYMENT_NAME ou pontos de extremidade MCP da caixa de ferramentas, vão no env mapa do azure.ai.agent serviço em azure.yaml ou na chamada do SDK create_version.

Importante

Quando você implanta seu agente hospedado no Serviço de Agente do Foundry, a plataforma injeta automaticamente uma cadeia de conexão do Application Insights no contêiner do agente como uma variável de ambiente, permitindo o rastreamento do OpenTelemetry por padrão. Para exibir rastreamentos distribuídos, solicitações e dependências, abra o recurso do Application Insights provisionado durante a configuração no portal do Azure e navegue até Investigar > Pesquisa de transações ou Desempenho. Use azd ai agent monitor os para logs de console ao vivo. Quando o AppInsights está habilitado, esse projeto registra rastreamentos para ajudar a monitorar e avaliar as interações no nível do usuário com agentes. Membros do projeto aos quais foi atribuída a função Leitor do Log Analytics no AppInsights podem visualizar dados de rastreamento, os quais podem conter dados pessoais e/ou Conteúdo do Cliente. Se as tabelas de Log Analytics subjacentes estiverem protegidas, os membros precisarão da função Leitor de Dados de Monitoramento Privilegiado para exibir esses dados de rastreamento. Examine quais dados de rastreamento são coletados e quem pode exibir e usar esses dados. Preços adicionais do Azure Monitor App Insights podem ser aplicados. Saiba mais.

Referenciar conexões de projeto em variáveis de ambiente

Em vez de codificar secretos (chaves de API, tokens, pontos de extremidade) diretamente no seu código azure.yaml ou na sua imagem, obtenha-os a partir de uma conexão com um projeto do Foundry no momento da inicialização da área restrita. Qualquer valor que você declarar como variável de ambiente pode ser uma expressão de marcador que a plataforma resolve antes que seu contêiner seja iniciado.

Sintaxe de marcador

Um marcador tem a forma ${{connections.<name>.<path>}}, em que <name> é o nome do recurso da conexão (visível no portal em Detalhes do projeto>Recursos conectados) e <path> é um dos seguintes:

Caminho É resolvido desta forma
credentials.<field> Um campo secreto na conexão
target A propriedade target da conexão (por exemplo, uma URL de endpoint)
metadata.<field> Um campo abaixo de metadata da conexão

O nome do campo a ser usado depende da categoria de conexão:

Categoria de conexão Nome do campo no espaço reservado
ApiKey, AppInsights Sempre key--por exemplo, credentials.key
CustomKeys O nome da chave que você forneceu ao criar a conexão, por exemplo, credentials.github_token

Example

Primeiro, crie uma CustomKeys conexão no projeto que armazena o segredo. Consulte Adicionar uma nova conexão no Microsoft Foundry. Em seguida, faça referência a ele a partir do env mapa no azure.ai.agent serviço em azure.yaml:

services:
  my-agent:
    host: azure.ai.agent
    env:
      MODEL_DEPLOYMENT_NAME: gpt-5-mini
      GITHUB_TOKEN: ${{connections.agent-secrets.credentials.github_token}}

Na inicialização do sandbox, a Foundry resolve o marcador e injeta o valor resolvido como uma variável de ambiente comum. Seu código o lê como qualquer outro env var:

import os
token = os.environ["GITHUB_TOKEN"]

Um GET na versão do agente retorna o texto literal ${{...}} – o segredo resolvido nunca é ecoado novamente por meio da API de gerenciamento.

Considerações

  • Crie a conexão antes de implantar a versão. Se a conexão ou o campo referenciado estiver ausente na inicialização do sandbox, o placeholder não é resolvido e a variável fica vazia.
  • Os segredos são somente gravação. GET em uma conexão retorna credentials: null. Verifique a resolução lendo o env var de dentro do contêiner em execução, não inspecionando a conexão.
  • Registre você mesmo os nomes dos campos CustomKeys. A API de gerenciamento nunca os ecoa novamente após a criação. Mantenha-os próximos à sua fonte de agente (por exemplo, em modelos de IaC ou ao lado de azure.yaml) para que você possa criar placeholders posteriormente sem precisar adivinhar.
  • O Foundry gerencia o nome do segredo de backup. Quando você cria a conexão, o Foundry armazena o valor no Key Vault com um nome que ele mesmo escolhe — você não pode referenciar um segredo existente do Key Vault pelo nome. Para usar seu próprio Key Vault como repositório de suporte, consulte Configure uma conexão com o Key Vault.

Empacote e execute teste no seu agente em ambiente local

Antes de implantar no Foundry, valide se o agente funciona localmente usando a biblioteca de protocolos. O contêiner atende aos mesmos pontos de extremidade localmente como em produção.

Testar o protocolo de respostas

POST http://localhost:8088/responses
Content-Type: application/json

{
    "input": "Where is Seattle?",
    "stream": false
}

Testar o protocolo Invocations

POST http://localhost:8088/invocations
Content-Type: application/json

{
    "message": "Hello!"
}

Implantar usando a CLI do desenvolvedor Azure ou o VS Code

A CLI do Desenvolvedor do Azure (azd) e o Kit de Ferramentas do Microsoft Foundry para Visual Studio Code automatizam todo o ciclo de vida da implantação: compilar o contêiner, enviá-lo para o Registro de Contêiner do Azure, criar a versão do agente e atribuir funções RBAC. Para obter um passo a passo guiado pela primeira vez, consulte o Início Rápido: Criar e implantar um agente hospedado.

Implante com um comando

No diretório do projeto do agente, provisione a infraestrutura e implante em uma única etapa:

azd up

azd up combina azd provision, que cria o projeto Foundry, a implantação de modelo, o registro de contêineres, o Application Insights e a identidade gerenciada, com azd deploy. Use-o em implantações iniciais ou sempre que você alterar tanto a infraestrutura quanto o código do agente.

Implantar apenas alterações no código

Se você já provisionou seus recursos de Azure e só precisa enviar por push uma nova versão do agente:

azd deploy

Durante azd deploy, a CLI:

  1. Cria sua imagem de contêiner remotamente em Registro de Contêiner do Azure, para que você não precise do Docker local.
  2. Efetua push da imagem para o registro.
  3. Cria uma versão hospedada do agente no Foundry Agent Service.
  4. Cria uma identidade de agente Microsoft Entra dedicada e atribui as funções RBAC que o agente precisa para acessar modelos e ferramentas.

Gerenciar versões

Cada azd deploy cria uma nova versão do agente. A CLI preserva as versões anteriores e a versão mais recente está ativa por padrão.

Verificar a implantação

azd ai agent show

A saída inclui o nome do agente, a versão, os protocolos, os recursos do contêiner, as variáveis de ambiente e a data e hora de criação. Use --output table para uma exibição de resumo.

Criar imagens localmente

Por padrão, azd cria imagens de contêiner remotamente em Registro de Contêiner do Azure. Para criar imagens localmente, defina remoteBuild: false em azure.yaml. Os builds locais exigem o Docker Desktop.

Para verificar prompts e respostas com base em uma política de segurança de conteúdo, adicione uma proteção de segurança de conteúdo ao seu agente.

Implantar usando o SDK do Python

Use o SDK quando quiser gerenciar implantações de agente diretamente de Python código.

Pré-requisitos adicionais

  • Python 3.10 ou posterior

  • Uma imagem de contêiner em Registro de Contêiner do Azure

  • Gravador de Repositório do Registro de Contêiner ou AcrPush no registro de contêiner (para fazer push de imagens)

  • Azure SDK de Projetos de IA versão 2.3.0 ou posterior

    pip install "azure-ai-projects>=2.3.0"

Compilar e enviar a imagem do contêiner

  1. Crie sua imagem do Docker:

    docker build --platform linux/amd64 -t myagent:v1 .

    Consulte exemplos de Dockerfiles para Python e C#.

  2. Envie para o Registro de Contêiner do Azure

    az acr login --name myregistry
docker tag myagent:v1 myregistry.azurecr.io/myagent:v1
docker push myregistry.azurecr.io/myagent:v1

Dica

Use marcas de imagem exclusivas em vez de :latest para implantações reproduzíveis.

Configurar permissões do Registro de Contêiner

Conceda à identidade gerenciada do seu projeto acesso para extrair imagens:

  1. No portal Azure, acesse o recurso de projeto do Foundry.

  2. Selecione Identidade e copie a ID do Objeto (principal) em Atribuído pelo sistema.

  3. Atribua a função Leitor do Repositório de Registro de Contêiner a essa identidade no registro de contêiner. Consulte Registro de Contêiner do Azure funções e permissões.

Criar uma versão do agente hospedado

Quando você cria uma versão, a plataforma provisiona automaticamente o agente. Não há nenhuma etapa inicial separada. A plataforma cria um instantâneo de contêiner e prepara o agente para atender às solicitações.

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import HostedAgentDefinition, ProtocolVersionRecord, AgentEndpointProtocol, ContainerConfiguration
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 expor ambos os protocolos, passe-os ambos no 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 de chave:

Parâmetro Descrição
agent_name Nome exclusivo (alfanumérico com hifens, máximo de 63 caracteres)
container_configuration.image URL completa da imagem do Registro de Contêiner do Azure com tag
cpu Alocação de CPU (por exemplo, "1")
memory Alocação de memória (por exemplo, "2Gi")
protocol_versions Protocolos que o contêiner expõe (responsesou invocationsambos)

Sondar o status da versão

Depois de criar uma versão, pressione até que o status seja active antes de invocar o agente. O provisionamento normalmente leva menos de um minuto, dependendo do tamanho da imagem.

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 status de versão:

Status Descrição
creating Provisionamento de infraestrutura em andamento
active O agente está pronto para atender às solicitações
failed Falha no provisionamento – verifique se há detalhes no error campo
deleting A versão está sendo otimizada
deleted A versão foi totalmente removida

Invocar o agente

Depois que a versão atingir o status active, use get_openai_client para criar um cliente do OpenAI vinculado ao ponto de extremidade do agente.

Para o protocolo Respostas :

# 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 o protocolo Invocações, chame o endpoint de invocações diretamente:

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 obter exemplos mais completos, consulte os exemplos de agente hospedado.

Implantar usando a API REST

Use a API REST para implantações diretas baseadas em HTTP ou ao integrar com ferramentas personalizadas.

Antes de começar, compile e envie por push sua imagem de contêiner para o Registro de Contêiner do Azure e conceda à identidade gerenciada do projeto a função Container Registry Repository Reader no registro.

Configurar variáveis

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)

Criar um 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"
      }
    }
  }'

A criação de um agente também cria a versão 1 e dispara o provisionamento.

Para filtrar prompts e respostas de acordo com uma política de segurança de conteúdo, inclua um objeto rai_config no definition. Consulte Adicionar um guardrail de segurança de conteúdo a um agente hospedado.

Sondar o status da versão

Consultar o ponto de extremidade de versão até que status seja 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 o agente

Use o endpoint dedicado do agente para enviar solicitações. Defina "stream": true para receber eventos enviados pelo servidor.

Protocolo de respostas:

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 invocações:

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"
  }'

Criar uma nova versão

Implante o código ou a configuração atualizados criando uma nova versão:

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"
      }
    }
  }'

Limpar recursos

Para evitar custos, libere os recursos quando concluir. A computação do agente é desprovisionada após 15 minutos de inatividade, portanto, não há custo quando um agente não está atendendo solicitações.

Limpeza da CLI para Desenvolvedores do Azure

azd down

Limpeza do SDK

Excluir uma única versão:

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

Ou exclua todo o agente e todas as suas versões:

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

Limpeza da API REST

Excluir uma única versão:

curl -X DELETE "$BASE_URL/agents/my-agent/versions/1?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN"

Ou exclua todo o agente:

curl -X DELETE "$BASE_URL/agents/my-agent?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN"

Aviso

Excluir um agente remove todas as suas versões e encerra as sessões ativas. Esta ação não pode ser desfeita.

Solucionando problemas

Os erros de provisionamento aparecem nos campos error.code e error.message do objeto de versão. Verifique o status da versão após a criação para identificar problemas.

Código de erro Código HTTP Solução
image_pull_failed 400 Verifique o URI da imagem. Confirme se a identidade gerenciada do projeto possui o Leitor de Repositório do Registro de Contêiner no ACR e se o status da política azureADAuthenticationAsArmPolicy do registro é enabled
SubscriptionIsNotRegistered 400 Registrar o provedor de assinatura
InvalidAcrPullCredentials 401 Corrigir a identidade gerenciada ou o RBAC do registro
UnauthorizedAcrPull 403 Fornecer credenciais ou identidade corretas
AcrImageNotFound 404 Corrigir nome/etiqueta da imagem ou publicar imagem
RegistryNotFound 400/404 Corrigir o DNS do Registro ou a acessibilidade de rede

Para erros 5xx, entre em contato com Microsoft suporte.

Para obter requisitos de RBAC detalhados e solução de problemas de permissão, consulte a referência de permissões do agente hospedado.

Próximas etapas

Gerenciar o ciclo de vida do agente hospedado

Conteúdo relacionado

  • Last updated on