Depurar um agente hospedado

Diagnostica e corrige problemas comuns quando crias, executas e implementas agentes com azd ai agent o Microsoft Foundry. Começa pelos comandos de diagnóstico. Depois, use as secções baseadas em sintomas para diagnosticar autenticação, desenvolvimento local, implementação, comandos diretos, registos e rotinas.

Pré-requisitos

Recolher contexto de diagnóstico

Antes de entrar em erros específicos, use estes comandos para recolher 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 saúde estruturado, execute azd ai agent doctor. Para mais informações, consulte Diagnosticar um projeto com o Agent Doctor.

Diagnosticar latência de invocação

Utilize os cabeçalhos de depuração de latência para determinar se um pedido a um agente alojado lento demorou tempo na plataforma, no aprovisionamento da infraestrutura, à espera do contentor ou no processamento do pedido no seu agente. Estes cabeçalhos são sinais de diagnóstico, não SLA ou métricas de faturação.

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

  1. Adicione o cabeçalho de latência a um pedido do protocolo Responses ou Invocations de um agente alojado. Este exemplo utiliza o protocolo Responses:

    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. Inspeciona 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 da sessão que acionou o pedido: arranque a frio (cold), arranque a quente (warm) ou retoma após inatividade (resume).
    x-ms-debug-latency-platform-preprocessing-ms Tempo da plataforma para admissão, autenticação, pesquisa de sessões e orquestração. Não inclui o provisionamento de micro-VMs nem atrasos na preparação dos contentores. Disponível para inícios frios, quentes e retomados das sessões.
    x-ms-debug-latency-infra-setup-ms Está na hora de provisionar a micro-VM. Omitido para pedidos calorosos.
    x-ms-debug-latency-container-readiness-ms Tempo decorrido desde a criação da micro-VM até o contentor indicar que está pronto. Omitido para pedidos calorosos.
    x-ms-debug-latency-container-response-ms Tempo desde o reencaminhamento pelo proxy até que os cabeçalhos de resposta sejam enviados. Inclui transferência de pedidos, configuração de ligações, gestão de agentes, tentativas e buffering de políticas de saída.
    x-ms-debug-latency-response-begin-ms Tempo total entre a aceitação do serviço e o envio dos cabeçalhos da resposta. Este valor não corresponde ao tempo até ao primeiro byte do corpo da resposta nem ao primeiro evento enviado pelo servidor.

    Os quatro componentes de temporização somam-se a x-ms-debug-latency-response-begin-ms. Num pedido frio ou retomado, se a plataforma não conseguir captar todos os limites de provisionamento, 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 temporização para identificar a provável fonte do 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 é elevado A plataforma dedicou tempo a provisionar a micro-VM. Compare vários pedidos novos ou retomados. Se o atraso persistir, grave o ID da resposta, o carimbo temporal e os cabeçalhos de latência para um pedido de suporte.
    x-ms-debug-latency-session-start-type é cold ou resume, e x-ms-debug-latency-container-readiness-ms é elevado O contentor demorou muito tempo a arrancar e a reportar que estava pronto. Meça os passos de inicialização nos seus registos de arranque, reduza o trabalho antes de o endpoint de prontidão ficar disponível e pré-compila 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 micro-VM ou de os contentores estarem prontos. Crie uma solicitação de suporte. Inclua o ID da resposta, carimbo temporal, tipo de início da sessão e 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 por proxy. Instrumente o handler de pedidos e inspecione registos de agentes, chamadas de modelo, chamadas de ferramenta, tentativas e buffering de saída.

Reduzir o tempo de prontidão dos contentores

O valor de prontidão do contentor inclui o tempo necessário para iniciar o seu processo, carregar a aplicação e devolver HTTP 200 de /readiness. Adicione carimbos temporais aos registos de arranque para identificar importações lentas, carregamento de dependências, chamadas de rede e outros trabalhos de inicialização.

Aplique estas otimizações aos passos lentos que identificar:

  • Instala dependências e compila código quando criares a imagem. Não execute a instalação, restauração ou compilação de pacotes no arranque do contentor.
  • Use uma compilação em múltiplos estágios e exclua ferramentas de compilação, caches de empacotamento, testes e outros ficheiros de desenvolvimento da imagem de runtime.
  • Evite chamadas ao modelo, migrações, deteção de ferramentas e transferências de recursos antes de estar tudo pronto. Paralelize a inicialização independente que tenha de estar concluída primeiro.
  • Mantenha /readiness o foco em saber se o agente pode aceitar pedidos. Se adiar a inicialização, meça a primeira solicitação para se certificar de que não transferiu o atraso da inicialização para o processamento da solicitação.

Instala dependências num ambiente virtual que copias para a imagem de runtime. Compile as dependências na medida do possível para que um ficheiro que não possa ser analisado num pacote de terceiros não faça falhar a compilação. Compila a aplicação estritamente para que erros de sintaxe falhem na compilação.

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"]

Desmarcar PYTHONDONTWRITEBYTECODE nesta etapa de compilação permite ao Python escrever o bytecode na imagem. A variável de ambiente bloqueia as escritas de bytecode, não as leituras, pelo que o contentor em execução ainda pode usar os ficheiros compilados.

Referência: compileall - Bibliotecas Python compiladas por bytes

Crie uma de entre as 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 .NET.

Referência: Requisitos de contentores para agentes alojados

Investigar a latência do agente e do modelo

Se o estado de prontidão do contentor for rápido, mas a resposta do contentor ou o tempo até ao primeiro byte forem elevados, concentre a sua investigação no percurso do pedido depois de começar o encaminhamento. Execute azd ai agent monitor --follow enquanto reproduz a solicitação e adicione rastreio às chamadas ao modelo, às chamadas de ferramentas, aos serviços externos, às novas tentativas e à serialização da resposta. Para mais informações, consulte Monitorizar registos de agente alojado.

Para um agente que chama um modelo de linguagem grande, meça a latência do modelo separadamente antes de alterar a implementação. Compare o tempo com o primeiro token, o tempo entre tokens, a contagem de tokens gerados, o tamanho do prompt, a utilização da implementação e a limitação. Depois avalie a escolha do modelo, os limites dos tokens de saída, o streaming e a separação da carga de trabalho. Veja 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 implementação provisionada e dimensione-a para os tokens de entrada, tokens de saída e taxa de pedido observados. Ver Débito provisionado.

Verificar os tempos de conclusão

No HTTP/2 ou posterior, o serviço pode devolver o trailer de resposta x-ms-debug-latency-final em regime de melhor esforço. Repete os valores do cabeçalho de resposta e pode adicionar estes campos:

Campo Meaning
first_byte_ms Tempo desde a aceitação do serviço até ao primeiro byte do corpo de resposta ou ao evento enviado pelo servidor.
total_last_byte_ms Tempo desde a aceitação do serviço até à conclusão do encaminhamento da resposta.

O trailer utiliza 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 cancelamento, desconexão do cliente, erro a meio do fluxo, ou quando um gateway ou SDK não preserva os 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 com a resposta ou a invocação. Um pedido GET posterior para o mesmo ID de resposta ou de invocação devolve as informações de temporização do pedido original nos cabeçalhos da resposta. O pedido GET não requer o cabeçalho de latência e não mede o pedido GET em si.

O pedido GET pode também devolver estes valores de conclusão como cabeçalhos comuns:

Cabeçalho Meaning
x-ms-debug-latency-first-byte-ms Tempo até ao primeiro byte do corpo da resposta.
x-ms-debug-latency-total-last-byte-ms Tempo até à conclusão do encaminhamento da resposta.

O armazenamento acaba por ser consistente, por isso um pedido GET imediatamente após o pedido original pode ainda não incluir os cabeçalhos. Para uma resposta ou invocação assíncrona, apenas os valores de overhead da plataforma estão disponíveis: tipo de início de sessão, pré-processamento da plataforma, configuração da infraestrutura e prontidão do contentor. Os cabeçalhos de latência não são gerados para respostas do proxy com falha nem para pedidos de WebSocket (invocations_ws).

Corrigir erros de autenticação

Corrigir AuthenticationError

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

Causas e soluções:

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

Importante

As funções RBAC do Foundry foram recentemente renomeadas. Foundry User, Foundry Owner, Foundry Account Owner e Foundry Project Manager foram anteriormente nomeados Azure AI User, Azure AI Owner, Azure AI Account Owner e Azure AI Project Manager. Poderá ainda ver os nomes anteriores em alguns locais enquanto esta alteração de nome está a ser implementada. Os IDs das funções e as permissões principais não são alterados por esta mudança de nome.

A sua identidade também necessita de Cognitive Services OpenAI User para utilizar implementações de modelo.

Corrigir AuthorizationFailed durante o aprovisionamento

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

Correção: Solicite o papel de Contribuinte na sua subscrição do Azure. Para CI/CD, a entidade de serviço também precisa de Foundry Owner.

Corrigir SubscriptionNotRegistered

Sintomas: O provisionamento falha porque um fornecedor de recursos obrigatório não está registado.

Correção:

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

Resolver problemas de desenvolvimento local

Corrigir ligação recusada na porta 8088

Sintomas:azd ai agent invoke --local não consegue ligar.

Causas e soluções:

  • O agente não está em execução -- Inicie-o com azd ai agent run num terminal separado.

  • Conflito de portas -- Outro processo é usar a porta 8088. Ou parem ou usam uma porta personalizada:

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

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

Corrigir falhas de instalação de dependências

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

Causas e soluções:

  • Versão de runtime errada -- Certifique-se de que o Python 3.10+ ou .NET 8+ está instalado.
  • Falta requirements.txt ou .csproj -- A CLI deteta automaticamente o tipo de projeto a partir destes ficheiros. Verifica se existem no teu diretório de agentes.
  • Problemas de rede -- Os registos de encomendas podem ser bloqueados pelo seu procurador corporativo. Verifica a tua configuração de pip ou dotnet.

Corrigir ResourceNotFound ou DeploymentNotFound

Sintomas: O agente começa mas falha ao tentar ligar para o modelo.

Causas e soluções:

  • Incompatibilidade de endpoint -- Execute azd env get-values e verifique se FOUNDRY_PROJECT_ENDPOINT corresponde ao endpoint mostrado no portal Foundry.
  • Incompatibilidade no nome da implementação do modelo -- O nome da implementação do modelo configurado em azure.yaml deve corresponder ao nome da implementação no seu projeto do Foundry. Consulte o portal em Destacamentos.
  • Recursos não provisionados -- Se ainda não executou azd up , os recursos na cloud não existirão. Executa azd up primeiro, depois testa localmente. O agente local continua a invocar modelos alojados na cloud.

Corrigir problemas de implementação

Corrigir falhas na construção do contentor

Sintomas:azd up falha durante a fase de construção do Docker.

Causas e soluções:

  • Dockerfile em falta -- Certifique-se de que o diretório do agente contém um Dockerfile. Se 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 de serviço project em azure.yaml.
  • Instalação de dependências no Docker -- Se o comando pip/dotnet restore falhar no contentor, verifique se o seu requirements.txt ou .csproj tem todas as dependências devidamente fixadas.

Corrigir azd up bloqueios ou tempos de espera

Sintomas: O provisionamento ou implementação demora um tempo invulgarmente longo.

Causas e soluções:

  • Primeira implementação -- A primeira azd up disponibiliza todos os recursos do Azure, incluindo o projeto Foundry, ACR, identidade gerida e implementação do modelo, e pode demorar entre 5 a 10 minutos. As implementações subsequentes são mais rápidas.
  • Compilação remota -- Por defeito, as imagens dos contentores são criadas remotamente no ACR. Isto pode ser mais lento, mas não requer Docker localmente. Para compilar localmente em alternativa, define docker.remoteBuild: false na configuração do serviço azure.yaml.
  • Capacidade regional -- Algumas regiões podem ter capacidade limitada para certos modelos SKUs. Tenta uma região diferente se o provisionamento falhar consistentemente.

Corrige um agente que é implementado mas não responde

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

Causas e soluções:

  • Falha da sonda de estado de funcionamento -- O seu contentor tem de responder a GET /readiness na porta 8088 com o código de estado 200. Verifique os registos com azd ai agent monitor --follow.
  • Incompatibilidade de protocolo -- Garanta que o protocolo definido no azure.ai.agent serviço corresponde azure.yaml ao que o seu código implementa. Se azure.yaml indicar responses, mas o teu código apenas processar invocations, ou vice-versa, os pedidos falham.
  • Falhas de contentores -- Verifique os registos do sistema para eventos de reinício: azd ai agent monitor --type system. As causas comuns incluem exceções não tratadas e problemas de falta de memória. Aumente os recursos do contentor em azure.yaml, se necessário.

Corrigir falhas de comando direto

Estes erros vêm dos azd ai comandos diretos, como azd ai connection, azd ai toolbox, e azd ai routine, quando executados contra um projeto Foundry.

Corrigir o endpoint não resolvido do projeto Foundry

Sintomas: Um comando direto termina 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 de projeto Foundry em nenhuma das fontes suportadas: a --project-endpoint flag, o ambiente ativo azd , a configuração global ou a FOUNDRY_PROJECT_ENDPOINT variável de ambiente.

Correções:

  • Execute azd ai project set <endpoint> para armazenar o endpoint na sua configuração global azd (~/.azd/config.json).
  • Passar --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 no ambiente da shell.

Para a ordem de resolução total e quando cada fonte vence, veja Compreender o contexto do projeto azd.

Corrigir falhas de criação de recursos existentes

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

Causa: Por design, create não é upsert. O modo de falha padrão impede que um programador sobrescrita silenciosamente o estado de outro num projeto Foundry partilhado.

Correções:

  • Escolhe outro nome e repete.
  • Passe --force, onde o create comando o suporta, para substituir o recurso existente através de um ARM PUT. A substituição é destrutiva: sobrescrive o recurso existente e perde-se qualquer desvio devido a edições manuais do portal, metadados ou credenciais. O azd ai toolbox create comando não suporta --force. Elimina a caixa de ferramentas existente ou usa um nome novo em vez disso.

Corrigir a saída de credenciais connection show

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

Causa: Por conceção, os valores das credenciais nunca são devolvidos por predefinição. Exigem a bandeira explícita --show-credentials .

Correção:

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

Isto invoca a API do plano de dados e requer permissões do plano de dados no projeto Foundry, como Utilizador Foundry ou equivalente. Se tiveres apenas acesso ao plano de gestão Reader ou Contributor, a chamada falha com um erro 403. Peça ao responsável pelo projeto que lhe atribua a função de plano de dados.

Leia os registos dos agentes

Utilizar 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>

Padrões comuns de registo incluem:

Mensagem de log Meaning
Listening on 0.0.0.0:8088 O agente começou com sucesso.
AuthenticationError Problema de credenciais ou de RBAC. Verifique a identidade gerida.
ModelNotFound O nome da implementação do modelo não corresponde a azure.yaml.
Reinício do contentor em eventos do sistema Ciclo de colisão. Verifique erros de código ou aumente os limites de recursos.

Diagnosticar falhas rotineiras

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

Inspecionar as corridas passadas

# 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 alargar ou estreitar a janela.

Furar numa única corrida

# 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 a carga útil de entrada, a resposta do agente e uma ligação profunda ao traço distribuído, o mesmo traço que veria numa invocação interativa.

Reativar manualmente uma rotina

Se precisar de reproduzir uma falha ou testar uma correção, acione a rotina a pedido com dispatch:

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

dispatch corre de forma assíncrona e imprime um ID de despacho. Verifique o resultado com azd ai routine run list <name>.

Corrigir uma execução que falhou

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

Corrige uma rotina que nunca funciona

Se azd ai routine run list não devolver nenhuma execução, o acionador em si não está a ser acionado:

  1. Verifique se a rotina está ativada: azd ai routine show <name>. Procure enabled: true.
  2. Para os gatilhos timer, verifique se --at está no futuro e ainda não disparou.
  3. Para acionadores recurring, verifique se a expressão --cron é válida e se --time-zone corresponde ao esperado.
  4. Para acionadores github-issue, verifique se --connection-id estabelece uma ligação em bom estado e se o repositório do GitHub e --issue-event correspondem aos eventos que o repositório emite.
  5. Para acionadores custom, verifique se o âmbito de --provider, --event-name e --parameters corresponde aos eventos que o fornecedor está a publicar.

Procura mais ajuda

  • Modo de depuração -- Adicionar --debug a qualquer azd comando para saída detalhada.
  • Portal Azure -- Consulte o projeto Foundry no portal Azure para saúde dos recursos e diagnósticos.
  • Registar um bug -- Reportar problemas em github.com/Azure/azure-dev/issues.

Conteúdo relacionado

  • Última atualização a