Eseguire il debug di un agente ospitato

Diagnosticare e risolvere i problemi comuni durante la compilazione, l'esecuzione e la distribuzione di agenti con azd ai agent per Microsoft Foundry. Iniziare con i comandi di diagnostica. Usare quindi le sezioni basate sui sintomi per risolvere i problemi di autenticazione, sviluppo locale, distribuzione, comandi diretti, log e routine.

Prerequisiti

Raccogli informazioni diagnostiche

Prima di esaminare errori specifici, usare questi comandi per raccogliere il contesto:

# 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

Per un report sull'integrità strutturata, eseguire azd ai agent doctor. Per altre informazioni, vedere Diagnosticare un progetto con il medico agente.

Correggere gli errori di autenticazione

Correggere AuthenticationError

Sintomi: L'agente non viene avviato in locale o restituisce 401/403 quando si chiama il modello di intelligenza artificiale.

Cause e correzioni:

  • Credenziali scadute: eseguire azd auth login per aggiornare la sessione di Azure.
  • Abbonamento errato -- Verificare con azd env get-values | grep AZURE_SUBSCRIPTION_ID e confrontarlo con l'abbonamento del progetto Foundry.
  • Ruoli RBAC mancanti: l'identità richiede l'accesso utente Foundry o equivalente al progetto Foundry.

Importante

I ruoli di Controllo degli accessi in base al ruolo di Foundry sono stati recentemente rinominati. Foundry User, Foundry Owner, Foundry Account Owner e Foundry Project Manager erano precedentemente denominati Azure AI User, Azure AI Owner, Azure AI Account Owner e Azure AI Project Manager. È possibile che i nomi precedenti vengano visualizzati in alcune posizioni durante l'esecuzione della ridenominazione. Gli ID ruolo e le autorizzazioni di base sono invariati dalla ridenominazione.

L'identità richiede anche il ruolo Utente OpenAI di Servizi cognitivi per usare le distribuzioni dei modelli.

Correggi AuthorizationFailed durante il provisioning

Sintomi:azd up o azd provision ha esito negativo con un errore di autorizzazione.

Correzione: Richiedere il ruolo Collaboratore nella sottoscrizione Azure. Per CI/CD, l'entità servizio necessita del ruolo Proprietario di Foundry.

Correggere SubscriptionNotRegistered

Sintomi: Il provisioning non riesce perché un provider di risorse richiesto non è registrato.

Correzione :

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

Risolvere i problemi di sviluppo locale

Correzione della connessione rifiutata sulla porta 8088

Sintomi:azd ai agent invoke --local non riesce a connettersi.

Cause e correzioni:

  • Agente non in esecuzione : avviarlo con azd ai agent run in un terminale separato.

  • Conflitto di porte : un altro processo usa la porta 8088. Arrestarlo o usare una porta personalizzata:

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

  • Arresto anomalo durante l'avvio: controllare l'output degli errori nel terminale in cui è in esecuzione azd ai agent run. Le cause comuni includono dipendenze mancanti, errori di importazione o configurazioni errate di startupCommand in azure.yaml.

Correggere gli errori di installazione delle dipendenze

Sintomi:azd ai agent run non riesce durante l'installazione delle dipendenze.

Cause e correzioni:

  • Versione di runtime errata: verificare che sia installata Python 3.10 o versioni successive o .NET 8+.
  • Manca requirements.txt o .csproj -- La CLI rileva automaticamente il tipo di progetto da questi file. Verificare che siano presenti nella directory dell'agente.
  • Problemi di rete : i registri pacchetti potrebbero essere bloccati dal proxy aziendale. Controlla la configurazione di pip o dotnet.

Correggi ResourceNotFound o DeploymentNotFound

Sintomi: l'agente si avvia ma non riesce a chiamare il modello.

Cause e correzioni:

  • Endpoint non corrispondente: eseguire azd env get-values e verificare che FOUNDRY_PROJECT_ENDPOINT corrisponda all'endpoint visualizzato nel portale di Foundry.
  • Nome distribuzione del modello non corrispondente : il nome della distribuzione del modello configurato in azure.yaml deve corrispondere al nome della distribuzione nel progetto Foundry. Controlla nel portale, in Distribuzioni.
  • Risorse non sottoposte a provisioning : se non è ancora stato eseguito azd up , le risorse cloud non esistono. Eseguire azd up prima di tutto, quindi testare localmente. L'agente locale chiama ancora modelli ospitati nel cloud.

Risolvere i problemi di distribuzione

Correggere gli errori di compilazione dei contenitori

Sintomi:azd up si interrompe durante la fase di build di Docker.

Cause e correzioni:

  • Dockerfile mancante -- Assicurati che la directory dell'agente contenga Dockerfile. Se è stato inizializzato da un template, viene generato automaticamente.
  • Errori del contesto di compilazione : Dockerfile deve trovarsi nella directory specificata dal percorso del servizio project in azure.yaml.
  • Installazione delle dipendenze in Docker: se il comando pip/dotnet restore non riesce all'interno del contenitore, verificare che requirements.txt o .csproj disponga di tutte le dipendenze aggiunte correttamente.

Correggere i blocchi o i timeout di azd up

Sintomi: Il provisioning o la distribuzione richiede tempi insolitamente lunghi.

Cause e correzioni:

  • Prima distribuzione -- il primo azd up crea tutte le risorse di Azure, inclusi il progetto Foundry, ACR, l'identità gestita e la distribuzione del modello, e può richiedere 5-10 minuti. Le distribuzioni successive sono più veloci.
  • Build remoto -- Per impostazione predefinita, le immagini di contenitori vengono create in remoto in Azure Container Registry (ACR). Questo può essere più lento, ma non richiede Docker in locale. Per compilare invece in locale, imposta docker.remoteBuild: false nella configurazione del servizio azure.yaml.
  • Capacità dell'area : alcune aree possono avere capacità limitata per determinati SKU del modello. Provare un'area diversa se il provisioning non riesce in modo coerente.

Correggere un agente che viene distribuito ma non risponde

Sintomi:azd ai agent invoke restituisce timeout o errori dopo una distribuzione completata correttamente.

Cause e correzioni:

  • Controllo di integrità non riuscito -- Il contenitore deve rispondere a GET /readiness sulla porta 8088 con un codice di stato 200. Controllare i log con azd ai agent monitor --follow.
  • Mancata corrispondenza del protocollo: assicurarsi che il protocollo definito nel azure.ai.agent servizio corrisponda a azure.yaml quello implementato dal codice. Se azure.yaml indica responses, ma il codice gestisce solo invocations, o viceversa, le richieste non vanno a buon fine.
  • Arresti anomali del contenitore: controllare nei log di sistema gli eventi di riavvio: azd ai agent monitor --type system. Le cause comuni includono eccezioni non gestite e problemi di memoria insufficiente. Se necessario, aumentare le risorse azure.yaml del contenitore.

Correggere gli errori di direct-command

Questi errori provengono dai azd ai comandi diretti, ad esempio azd ai connection, azd ai toolboxe azd ai routine, quando vengono eseguiti su un progetto Foundry.

Correzione dell'endpoint del progetto Foundry non risolto

Sintomi: Un comando diretto viene chiuso con No Foundry project endpoint resolved. Run azd ai project set to set one, or pass --project-endpoint.

Causa: L'interfaccia della riga di comando non è riuscita a trovare un endpoint di progetto Foundry in nessuna delle origini supportate: il --project-endpoint flag, l'ambiente attivo azd , la configurazione globale o la FOUNDRY_PROJECT_ENDPOINT variabile di ambiente.

Correzioni:

  • Eseguire azd ai project set <endpoint> per archiviare l'endpoint nella configurazione globale azd (~/.azd/config.json).
  • Passare --project-endpoint (-p) a ogni comando: azd ai connection list -p https://my-proj.services.ai.azure.com/api/projects/my-project.
  • Imposta FOUNDRY_PROJECT_ENDPOINT nel tuo ambiente shell.

Per l'ordine di risoluzione completo e quando ogni origine vince, vedere Informazioni sul contesto del progetto azd.

Correggere gli errori di creazione per le risorse esistenti

Sintomi:azd ai connection create, azd ai toolbox create, azd ai routine create o azd ai skill create non riesce con l'errore "esiste già".

Causa: per progettazione, create non supporta l'upsert. La modalità di errore predefinita impedisce a uno sviluppatore di sovrascrivere automaticamente lo stato di un altro in un progetto Foundry condiviso.

Correzioni:

  • Selezionare un nome diverso e rieseguire.
  • Passa --force se il comando create lo supporta, per sostituire la risorsa esistente tramite un'operazione ARM PUT. La sostituzione è distruttiva: sovrascrive direttamente la risorsa esistente e qualsiasi deriva dovuta a modifiche manuali nel portale, ai metadati o alle credenziali va persa. Il azd ai toolbox create comando non supporta --force. Eliminare la casella degli strumenti esistente o usare invece un nuovo nome.

Correggere l'output delle credenziali di connection show

Sintomi:azd ai connection show <name> restituisce il nome, il tipo, la destinazione e il tipo di autenticazione della connessione, ma nessun valore di chiave API o credenziale.

Causa: Per impostazione predefinita, i valori delle credenziali non vengono mai restituiti per impostazione predefinita. Richiedono il flag esplicito --show-credentials .

Correzione :

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

Viene richiamata l'API del piano dati e sono necessarie autorizzazioni del piano dati per il progetto Foundry, ad esempio Foundry User o equivalenti. Se si dispone solo dell'accesso Reader o Contributor al piano di gestione, la chiamata non riesce con un errore 403. Chiedi al responsabile del progetto il ruolo del data plane.

Leggere i log dell'agente

Usare azd ai agent monitor per controllare il comportamento dell'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>

I modelli di log comuni includono:

Messaggio di log Meaning
Listening on 0.0.0.0:8088 L'agente è stato avviato correttamente.
AuthenticationError Problema relativo alle credenziali o a RBAC. Controllare l'identità gestita.
ModelNotFound Il nome della distribuzione del modello non corrisponde a azure.yaml.
Riavvio del contenitore negli eventi di sistema Ciclo di arresto anomalo. Controllare gli errori del codice o aumentare i limiti delle risorse.

Diagnosticare gli errori di routine

Le routine falliscono in modo diverso dalle chiamate interattive agent invoke perché non c'è alcun chiamante che segnali l'errore. Una routine è un'esecuzione di un agente ricorrente, attivata da timer, da un problema di GitHub o da un evento personalizzato. Usare azd ai routine run list per controllare cosa è successo.

Visualizza le esecuzioni precedenti

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

Filtrare in base agli errori

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

Combinare con --top per ampliare o restringere la finestra.

Eseguire il drill-down di una singola esecuzione

# 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

L'output JSON include il payload di input, la risposta dell'agente e un collegamento diretto alla traccia distribuita, la stessa traccia visualizzata per una chiamata interattiva.

Riattivare manualmente una routine

Se è necessario riprodurre un errore o testare una correzione, attivare la routine su richiesta con dispatch:

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

dispatch viene eseguito in modo asincrono e stampa un ID di invio. Controllare il risultato con azd ai routine run list <name>.

Correzione di un'esecuzione di routine non riuscita

azd ai routine run list mostra l'esecuzione con status: failed. Segui il link di traccia per visualizzare l'errore sottostante dell'agente, ad esempio un errore del modello, un errore dello strumento o un timeout. Le correzioni lato agente sono le stesse di quelle per gli errori interattivi. Vedere Correggere gli errori di autenticazione e leggere i log dell'agente.

Correggere una routine che non si attiva mai

Se azd ai routine run list non restituisce alcuna esecuzione, il trigger non è attivato:

  1. Controllare che la routine sia abilitata: azd ai routine show <name>. Cerca enabled: true.
  2. Per i trigger timer, verificare che --at sia impostato per il futuro e non sia già attivato.
  3. Per i trigger recurring, verifica che l'espressione --cron sia valida e che --time-zone corrisponda a quanto previsto.
  4. Per i trigger github-issue, verificare che --connection-id venga risolto in una connessione integra e che il repository GitHub e --issue-event corrispondano agli eventi emessi dal repository.
  5. Per i trigger custom, verifica che gli ambiti --provider, --event-name e --parameters corrispondano agli eventi che il provider pubblica.

Ottenere altre informazioni

  • Modalità di debug -- Aggiungi --debug a qualsiasi comando azd per un output dettagliato.
  • Azure portale: controllare il progetto Foundry nel portale di Azure per informazioni sull'integrità e la diagnostica delle risorse.
  • Segnalare un bug: segnalare i problemi in github.com/Azure/azure-dev/issues.

Contenuti correlati

  • Last updated on