Depurar um agente hospedado

Diagnosticar e corrigir problemas comuns ao criar, executar e implantar agentes para azd ai agent Microsoft Foundry. Comece com os comandos de diagnóstico. Em seguida, use as seções baseadas em sintomas para solucionar problemas de autenticação, desenvolvimento local, implantação, comandos diretos, logs e rotinas.

Pré-requisitos

Coletar contexto de diagnóstico

Antes de se aprofundar em erros específicos, use estes comandos para coletar contexto:

# Check extension version
azd ai agent version

# Verify Azure authentication
azd auth login

# Show current environment configuration
azd env get-values

# View agent details
azd ai agent show

# Show the resolved Foundry project endpoint and where it came from
azd ai project show

# Stream production logs
azd ai agent monitor --follow

Para um relatório de integridade estruturado, execute azd ai agent doctor. Para obter mais informações, consulte Diagnosticar um projeto com o agent doctor.

Diagnosticar latência de invocação

Use os cabeçalhos de depuração de latência para determinar se uma solicitação de agente hospedado lenta passou um tempo na plataforma, provisionando a infraestrutura, aguardando o contêiner ou processando a solicitação em seu agente. Esses cabeçalhos são sinais de diagnóstico, não SLA ou métricas de cobrança.

Habilite o diagnóstico em cada solicitação definindo x-ms-debug-latency-enabled: true. Se a solicitação não incluir esse cabeçalho, a resposta não incluirá os x-ms-debug-latency-* cabeçalhos.

  1. Adicione o cabeçalho de latência a uma requisição do protocolo Responses ou Invocations de um agente hospedado. Este exemplo usa o protocolo Respostas:

    ENDPOINT="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)
AGENT="my-code-agent"

curl --http2 -i -X POST \
  "$ENDPOINT/agents/$AGENT/endpoint/protocols/openai/responses?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "x-ms-debug-latency-enabled: true" \
  -d '{"model":"gpt-5.4-mini","input":"Hello, agent!","stream":false}'

  2. Inspecione os cabeçalhos de resposta. Todos os valores de latência são milissegundos inteiros:

    Cabeçalho Meaning
    x-ms-debug-latency-session-start-type Tipo de início de sessão acionado pela solicitação: inicialização a frio (cold), inicialização a quente (warm) ou retomada após ociosidade (resume).
    x-ms-debug-latency-platform-preprocessing-ms Tempo da plataforma para admissão, autenticação, busca de sessão e orquestração. Ele não inclui atrasos de provisionamento de microVM ou preparação de contêiner. Disponível para inicializações de sessão a frio, a quente e retomadas.
    x-ms-debug-latency-infra-setup-ms Hora de provisionar a micro-VM. Omitido para solicitações em andamento.
    x-ms-debug-latency-container-readiness-ms Tempo desde a criação da micro-VM até que o contêiner indique que está pronto. Omitido para solicitações em andamento.
    x-ms-debug-latency-container-response-ms Tempo desde o encaminhamento pelo proxy até que os cabeçalhos de resposta sejam enviados. Inclui transferência de solicitação, configuração de conexão, tratamento de agente, novas tentativas e buffer de política de saída.
    x-ms-debug-latency-response-begin-ms Tempo total desde a aceitação do serviço até o envio dos cabeçalhos de resposta. Esse valor não corresponde ao tempo até o primeiro byte do corpo da resposta ou ao primeiro evento enviado pelo servidor.

    Os quatro componentes de temporização totalizam x-ms-debug-latency-response-begin-ms. Em uma solicitação fria ou retomada, se a plataforma não conseguir capturar todos os limites de provisionamento, ela omite os cabeçalhos de infraestrutura e prontidão e inclui esse tempo no pré-processamento da plataforma.

  3. Use o tipo de início da sessão e o maior componente de tempo para identificar a provável fonte de atraso:

    Result Interpretação O que fazer
    x-ms-debug-latency-session-start-type é cold ou resume, e x-ms-debug-latency-infra-setup-ms é alto A plataforma gastou tempo provisionando a micro-VM. Compare várias solicitações frias ou retomadas. Se o atraso persistir, registre a ID de resposta, o carimbo de data/hora e os cabeçalhos de latência para uma solicitação de suporte.
    x-ms-debug-latency-session-start-type é cold ou resume, e x-ms-debug-latency-container-readiness-ms é alto O contêiner demorou muito tempo para iniciar e sinalizar que estava pronto. Meça as etapas de inicialização nos logs de inicialização, reduza o trabalho antes que o endpoint de prontidão fique disponível e pré-compile o código da aplicação sempre que possível.
    x-ms-debug-latency-platform-preprocessing-ms é alto para qualquer tipo de início de sessão O atraso ocorreu na plataforma antes do provisionamento da microVM ou da preparação do contêiner. Crie uma solicitação de suporte. Inclua o ID da resposta, a data e hora, o tipo de início de sessão e os cabeçalhos de latência.
    x-ms-debug-latency-container-response-ms, x-ms-debug-latency-first-byte-ms, ou a first_byte_ms do reboque está alta O atraso ocorreu após o início do encaminhamento de proxy. Instrumente o manipulador de solicitação e inspecione os logs do agente, as chamadas ao modelo, as chamadas de ferramenta, as repetições e a bufferização de saída.

Reduzir o tempo de preparação do contêiner

O valor de preparação do contêiner inclui o tempo necessário para iniciar o processo, carregar o aplicativo e retornar HTTP 200 de /readiness. Adicione registros de data e hora aos logs de inicialização para identificar importações lentas, carregamento de dependências, chamadas de rede e outras tarefas de inicialização.

Aplique essas otimizações às etapas lentas que você identificar:

  • Instale dependências e compile o código ao compilar a imagem. Não execute a instalação, restauração ou compilação do pacote na inicialização do contêiner.
  • Use um build de vários estágios e exclua ferramentas de build, caches de pacotes, testes e outros arquivos de desenvolvimento da imagem de runtime.
  • Evite chamadas de modelo, migrações, descoberta de ferramentas e download de ativos antes que tudo esteja pronto. Paralelize as inicializações independentes que precisam ser concluídas primeiro.
  • Mantenha-se /readiness focado em saber se o agente pode aceitar solicitações. Se você adiar a inicialização, meça a primeira solicitação para garantir que não tenha movido o atraso de inicialização para o tratamento de solicitações.

Instale as dependências em um ambiente virtual que você copia para a imagem de execução. Compile as dependências na medida do possível para que um arquivo que não possa ser analisado em um pacote de terceiros não faça a compilação falhar. Compile o aplicativo de forma estrita para que erros de sintaxe façam a compilação falhar.

FROM python:3.13-slim AS build

WORKDIR /app
RUN python -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .
RUN PYTHONDONTWRITEBYTECODE= python -m compileall -q /opt/venv \
      || true; \
    PYTHONDONTWRITEBYTECODE= python -m compileall -q /app

FROM python:3.13-slim AS final

ENV PATH="/opt/venv/bin:$PATH"
WORKDIR /app

COPY --from=build /opt/venv /opt/venv
COPY --from=build /app /app

# Precompile the standard library in the runtime image.
RUN PYTHONDONTWRITEBYTECODE= python -m compileall -q \
    "$(python -c "import sysconfig; print(sysconfig.get_path('stdlib'))")" \
    || true

CMD ["python", "main.py"]

Limpar PYTHONDONTWRITEBYTECODE para esta etapa de construção permite que o Python grave o bytecode na imagem. A variável de ambiente bloqueia gravações de código de byte, não leituras, de modo que o contêiner em execução ainda pode usar os arquivos compilados.

Referência: compileall – Bibliotecas de Python de compilação de bytes

Crie uma das imagens para a arquitetura x86-64 exigida pelos agentes hospedados:

docker build --platform linux/amd64 -t my-agent:latest .

Aqui, linux/amd64 é uma plataforma Docker, não um identificador de runtime do .NET.

Referência: Requisitos de contêiner do agente hospedado

Investigar a latência do agente e do modelo

Se a prontidão do contêiner for rápida, mas a resposta do contêiner ou o tempo até o primeiro byte for alto, concentre sua investigação no caminho da requisição após o início do encaminhamento. Execute azd ai agent monitor --follow durante a reprodução da solicitação e adicione o rastreamento em torno de chamadas de modelo, chamadas de ferramenta, serviços externos, novas tentativas e serialização de resposta. Para obter mais informações, consulte Monitor hosted agent logs.

Para um agente que chama um modelo de linguagem de grande porte, meça a latência do modelo separadamente antes de alterar a implantação. Compare a hora com o primeiro token, o tempo entre tokens, a contagem de tokens gerada, o tamanho do prompt, a utilização da implantação e a limitação. Em seguida, avalie a escolha do modelo, os limites de token de saída, o streaming e a separação da carga de trabalho. Consulte Melhorar o desempenho do Azure OpenAI.

Se as medições mostrarem pressão de capacidade sustentada para uma carga de trabalho previsível, avalie uma implantação com capacidade provisionada e dimensione-a com base nos tokens de entrada, tokens de saída e na taxa de solicitações observados. Consulte a taxa de transferência provisionada.

Verificar os tempos de conclusão

Em HTTP/2 ou posterior, o serviço pode retornar o trailer de resposta de melhor esforço x-ms-debug-latency-final . Ele repete os valores de cabeçalho de resposta e pode adicionar estes campos:

Campo Meaning
first_byte_ms Tempo da aceitação do serviço até o primeiro byte do corpo da resposta ou evento enviado pelo servidor.
total_last_byte_ms Tempo da aceitação do serviço até que o encaminhamento de resposta seja concluído.

O trailer usa um formato versionado, delimitado por ponto e vírgula:

x-ms-debug-latency-final: v=1;start=cold;platform_pre_ms=...;
  infra_ms=...;ready_ms=...;container_response_ms=...;
  response_begin_ms=...;first_byte_ms=...;total_last_byte_ms=...

As respostas HTTP/1.1 não incluem este trailer. Um trailer também pode estar ausente após o cancelamento, a desconexão do cliente, um erro midstream ou quando um gateway ou SDK não preserva trailers. Trate os cabeçalhos de resposta como o contrato de diagnóstico garantido.

Recuperar resultados de latência armazenados

O serviço armazena os tempos capturados junto com a resposta ou invocação. Uma solicitação GET subsequente para a mesma resposta ou ID da invocação retorna os tempos da solicitação original como cabeçalhos de resposta. A solicitação GET não requer o cabeçalho de latência e não mede a solicitação GET em si.

A solicitação GET também pode retornar esses valores de conclusão como cabeçalhos comuns:

Cabeçalho Meaning
x-ms-debug-latency-first-byte-ms Tempo até o primeiro byte do corpo da resposta.
x-ms-debug-latency-total-last-byte-ms Tempo até que o encaminhamento de resposta seja concluído.

O armazenamento eventualmente é consistente, portanto, uma solicitação GET imediatamente após a solicitação original pode não incluir os cabeçalhos ainda. Para uma resposta ou invocação assíncrona, somente os valores de sobrecarga de plataforma estão disponíveis: tipo de início de sessão, pré-processamento de plataforma, configuração de infraestrutura e preparação de contêiner. Os cabeçalhos de latência não são emitidos para respostas de proxy com falha ou solicitações WebSocket (invocations_ws).

Corrigir erros de autenticação

Corrigir AuthenticationError

Sintomas: O agente falha ao iniciar localmente ou retorna 401/403 ao chamar o modelo de IA.

Causas e correções:

  • Credenciais expiradas – execute azd auth login para atualizar sua sessão de Azure.
  • Assinatura incorreta - Verifique com azd env get-values | grep AZURE_SUBSCRIPTION_ID e compare com a assinatura do projeto do Foundry.
  • Funções RBAC ausentes - sua identidade precisa da função Foundry User ou de acesso equivalente no projeto do Foundry.

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.

Sua identidade também precisa da função Usuário do OpenAI de Serviços Cognitivos para usar implantações de modelos.

Corrija AuthorizationFailed durante o provisionamento

Sintomas:azd up ou azd provision falha com um erro de permissões.

Corrigir: Solicite a função Colaborador em sua assinatura Azure. Para CI/CD, a entidade de serviço também precisa da função Foundry Owner.

Corrigir SubscriptionNotRegistered

Sintomas: O provisionamento falha porque um provedor de recursos necessário não está registrado.

Correção:

az provider register --namespace Microsoft.CognitiveServices
az provider register --namespace Microsoft.ContainerRegistry

Corrigir problemas de desenvolvimento local

Correção da conexão recusada na porta 8088

Sintomas:azd ai agent invoke --local falha ao se conectar.

Causas e correções:

  • Agente não está em execução -- Inicie-o com azd ai agent run em um terminal separado.

  • Conflito de porta – outro processo é usar a porta 8088. Interrompa ou use uma porta personalizada:

    azd ai agent run --port 9090
azd ai agent invoke --local --port 9090 "Hello!"

  • Falha de inicialização -- verifique o terminal onde azd ai agent run está em execução para ver a saída de erro. As causas comuns incluem dependências ausentes, erros de importação ou startupCommand incorretas em azure.yaml.

Corrigir falhas na instalação de dependências

Sintomas:azd ai agent run ocorre uma falha durante a instalação de dependências.

Causas e correções:

  • Versão de runtime incorreta – verifique se Python 3.10+ ou .NET 8+ está instalado.
  • Ausente requirements.txt ou .csproj -- a CLI detecta automaticamente o tipo de projeto desses arquivos. Verifique se eles existem no diretório do agente.
  • Problemas de rede – Os registros de pacote podem ser bloqueados pelo proxy corporativo. Verifique a configuração de pip ou dotnet.

Corrigir ResourceNotFound ou DeploymentNotFound

Sintomas: o agente inicia, mas falha ao tentar chamar o modelo.

Causas e correções:

  • Incompatibilidade de endpoint — execute azd env get-values e verifique se FOUNDRY_PROJECT_ENDPOINT corresponde ao endpoint mostrado no portal do Foundry.
  • Incompatibilidade entre nomes de implantação do modelo -- O nome da implantação do modelo configurado em azure.yaml deve corresponder ao nome da implantação no seu projeto do Foundry. Faça check-in no portal em Implantações.
  • Recursos não provisionados – se você ainda não tiver executado azd up , os recursos de nuvem não existirão. Execute azd up primeiro e teste localmente. O agente local ainda chama modelos hospedados na nuvem.

Corrigir problemas de implantação

Corrigir falhas na compilação de contêineres

Sintomas:azd up falha durante a fase de build do Docker.

Causas e correções:

  • Dockerfile ausente - verifique se o diretório do agente tem um Dockerfile. Se você inicializou a partir de um modelo, isto é gerado automaticamente.
  • Erros de contexto de compilação - o Dockerfile deve estar no diretório especificado pelo caminho project do serviço em azure.yaml.
  • Instalação de dependências no Docker -- Se o pip/dotnet restore falhar dentro do contêiner, verifique se o seu requirements.txt ou .csproj tem todas as dependências corretamente fixadas.

Corrigir azd up travamentos ou tempos limite

Sintomas: O provisionamento ou implantação leva muito tempo.

Causas e correções:

  • Primeira implantação – A primeira provisiona azd up todos os recursos Azure, incluindo o projeto foundry, o ACR, a identidade gerenciada e a implantação do modelo, e pode levar de 5 a 10 minutos. As implantações subsequentes são mais rápidas.
  • Build remoto - por padrão, as imagens de contêiner são criadas remotamente no ACR. Isso pode ser mais lento, mas não requer o Docker localmente. Para compilar localmente em vez disso, defina docker.remoteBuild: false na configuração do serviço azure.yaml.
  • Capacidade da região – algumas regiões podem ter capacidade limitada para determinadas SKUs de modelo. Tente uma região diferente se o provisionamento falhar consistentemente.

Corrigir um agente implantado que não responde

Sintomas:azd ai agent invoke expira ou retorna erros após uma implantação bem-sucedida.

Causas e correções:

  • Falha na investigação de integridade -seu contêiner deve responder a GET /readiness na porta 8088 com status 200. Verifique os logs com azd ai agent monitor --follow.
  • Incompatibilidade de protocolo -- Verifique se o protocolo definido no serviço azure.ai.agent em azure.yaml corresponde ao que seu código implementa. Se azure.yaml indicar responses, mas seu código só lida com invocations, ou vice-versa, as requisições falham.
  • Falhas de contêiner - verifique os logs do sistema para saber se há eventos de reinicialização: azd ai agent monitor --type system. As causas comuns incluem exceções sem tratamento e problemas de falta de memória. Aumente os recursos do contêiner azure.yaml, se necessário.

Corrigir falhas de comando direto

Esses erros vêm de comandos diretos azd ai, como azd ai connection, azd ai toolbox e azd ai routine, quando executados em um projeto Foundry.

Corrigir ausência de ponto de extremidade resolvido do projeto do Foundry

Sintomas: Um comando direto é encerrado com No Foundry project endpoint resolved. Run azd ai project set to set one, or pass --project-endpoint.

Causa: A CLI não conseguiu encontrar um endpoint do projeto Foundry em nenhuma das fontes compatíveis: o sinalizador --project-endpoint, o ambiente azd ativo, a configuração global ou a variável de ambiente FOUNDRY_PROJECT_ENDPOINT.

Correções:

  • Execute azd ai project set <endpoint> para armazenar o endpoint na configuração global do azd (~/.azd/config.json).
  • Passe --project-endpoint (-p) em cada comando: azd ai connection list -p https://my-proj.services.ai.azure.com/api/projects/my-project.
  • Defina FOUNDRY_PROJECT_ENDPOINT em seu ambiente de shell.

Para ver a ordem completa de resolução e quando cada fonte prevalece, consulte Entenda o contexto do projeto azd.

Corrigir falhas de criação para recursos existentes

Sintomas:azd ai connection create, azd ai toolbox create, azd ai routine create ou azd ai skill create falha com o erro "já existe".

Causa: por padrão, create não é executar upsert. O modo de falha padrão impede que um desenvolvedor substitua silenciosamente o estado de outro em um projeto de Foundry compartilhado.

Correções:

  • Escolha um nome diferente e execute novamente.
  • Passe --force, nos casos em que o comando create for compatível com ele, para substituir o recurso existente por meio de uma operação PUT do ARM. A substituição é destrutiva: ela substitui o recurso existente no local, e qualquer divergência decorrente de edições manuais no portal, metadados ou credenciais é perdida. O comando azd ai toolbox create não oferece suporte a --force. Exclua a caixa de ferramentas existente ou use um novo nome.

Corrigir connection show saída de credenciais

Sintomas:azd ai connection show <name> retorna o nome, o tipo, o destino e o tipo de autenticação da conexão, mas nenhuma chave de API ou valor de credencial.

Causa: Por design, os valores de credencial nunca são retornados por padrão. Eles exigem o sinalizador explícito --show-credentials.

Correção:

azd ai connection show tavily-conn --show-credentials

Isso invoca a API do plano de dados e requer permissões de plano de dados no projeto do Foundry, como o Usuário do Foundry ou equivalente. Se você tiver acesso apenas ao plano de gerenciamento Reader ou Contributor, a chamada falhará com status 403. Peça ao responsável pelo projeto a função do plano de dados.

Ler os logs do agente

Use azd ai agent monitor para inspecionar o comportamento do agente:

# Stream all recent logs
azd ai agent monitor --follow

# View system-level events (container starts, crashes, restarts)
azd ai agent monitor --type system

# Filter to a specific session
azd ai agent monitor --session-id <session-id>

Os padrões de log comuns incluem:

Mensagem de log Meaning
Listening on 0.0.0.0:8088 Agente iniciado com êxito.
AuthenticationError Problema de credenciais ou de RBAC. Verifique a identidade gerenciada.
ModelNotFound O nome da implantação de modelo não corresponde a azure.yaml.
Reinicialização de contêiner em eventos do sistema Loop de falha. Verifique os erros de código ou aumente os limites de recursos.

Diagnosticar falhas de rotina

As rotinas falham de forma diferente das chamadas interativas agent invoke porque nenhum chamador está presente para exibir o erro. Uma rotina é uma execução de um agente acionada por temporizador, recorrente, acionada por problema do GitHub ou acionada por evento personalizado. Use azd ai routine run list para inspecionar o que aconteceu.

Inspecionar execuções anteriores

# Recent runs of a routine: trigger time, agent input/output, status, trace link
azd ai routine run list daily-digest

Filtrar por falhas

# Failed runs only, with an OData filter
azd ai routine run list daily-digest --filter "status eq 'failed'"

Combine com --top para ampliar ou restringir a janela.

Analisar em detalhes uma única execução

# Full detail for the most recent runs as JSON, then look up the run you care about
azd ai routine run list daily-digest --top 5 --output json

A saída JSON inclui o payload de entrada, a resposta do agente e um link direto para o rastreamento distribuído, o mesmo rastreamento que você veria em uma invocação interativa.

Acionar manualmente uma rotina novamente

Se você precisar reproduzir uma falha ou testar uma correção, dispare a rotina sob demanda com dispatch:

azd ai routine dispatch daily-digest
azd ai routine dispatch triage-issues --input '{"issue":{"number":42}}'

dispatch é executado de forma assíncrona e imprime uma ID de expedição. Verifique o resultado com azd ai routine run list <name>.

Corrigir uma execução de rotina com falha

azd ai routine run list mostra a execução com status: failed. Siga o link de rastreamento para ver o erro do agente subjacente, como erro de modelo, falha de ferramenta ou tempo limite. As correções do lado do agente são as mesmas usadas para falhas interativas. Consulte Corrigir erros de autenticação e Ler os logs do agente.

Corrigir uma rotina que nunca é acionada

Se azd ai routine run list não retornar execução alguma, o gatilho em si não está sendo disparado:

  1. Verifique se a rotina está habilitada: azd ai routine show <name>. Busque enabled: true.
  2. Para gatilhos timer, verifique se --at está no futuro e ainda não tenha sido acionado.
  3. Para gatilhos recurring, verifique se a expressão --cron é válida e se o --time-zone é o que você esperava.
  4. Para gatilhos github-issue, verifique se o --connection-id se resolve em uma conexão válida e se o repositório do GitHub e --issue-event corresponde aos eventos emitidos pelo repositório.
  5. Para gatilhos custom, verifique se o escopo de --provider, --event-name e --parameters corresponde aos eventos que o provedor está publicando.

Obter mais ajuda

  • Modo de depuração - adicione --debug a qualquer comando azd para saída detalhada.
  • Azure portal -- Verifique o projeto foundry no portal Azure para obter diagnóstico e integridade do recurso.
  • Registrar um bug – relatar problemas em github.com/Azure/azure-dev/issues.

Conteúdo relacionado

  • Última atualização em