Abilitazione della modalità di debug
Scopri come abilitare il log di debug in ADK per la risoluzione dei problemi.
Log di debug in ADK
Quando sviluppi o risolvi i problemi di un'applicazione creata con ADK, per ottenere informazioni più dettagliate su ciò che sta accadendo dietro le quinte, puoi abilitare la modalità di debug logging. È possibile abilitare questa modalità in ADK tramite una variabile di ambiente.
Abilitazione della modalità debug
Per abilitare il log di debug in ADK, impostare la variabile di ambiente ADK_LOG_LEVEL
su DEBUG
:
export ADK_LOG_LEVEL=DEBUG
In Windows, è possibile impostare questa variabile di ambiente utilizzando il comando set
:
set ADK_LOG_LEVEL=DEBUG
Dopo aver impostato questa variabile di ambiente, eseguire l'applicazione ADK come al solito e verrà visualizzato un log più dettagliato nell'output.
Informazioni sulla modalità di debug
Quando la modalità di debug è abilitata, verranno fornite le seguenti informazioni:
- OCID risorsa: identificativi univoci per le risorse OCI in uso
- ID richiesta OPC: identificativi di richiesta a cui fare riferimento quando si lavora con il Supporto Oracle
- Dettagli richiesta/risposta API: dettagli sulla comunicazione con i servizi OCI
- Log delle operazioni interne: informazioni su come l'ADK sta elaborando le richieste
- Tracce di esecuzione degli strumenti: log dettagliati sui richiami degli strumenti e sui relativi risultati
Suggerimento: se si verifica un problema, salvarne i log di debug. Questi log sono utili quando si segnalano problemi al team del servizio OCI Generative AI Agents o al Supporto Oracle.
Output di esempio
Di seguito è riportato un output di esempio dopo l'esecuzione di un'applicazione ADK, con la modalità di registrazione debug abilitata.
[05/08/25 15:19:35] DEBUG Invoking chat endpoint with data: {
"performed_actions": [
{
"action_id": "<example-action-id>",
"function_call_output": "{\"message\": {\"role\": \"AGENT\", \"content\":
{\"text\": \"Your most recent order, order_222222, has been refunded.\",
\"citations\": null, \"paragraph_citations\": null}, \"time_created\":
\"2025-05-08T22:19:33.669000+00:00\"}, \"traces\": [{\"time_created\":
\"2025-05-08T22:19:33.233000+00:00\", \"trace_type\": \"UNKNOWN_ENUM_VALUE\"}],
\"tool_results\": null, \"required_actions\": null, \"guardrail_result\": null}",
"performed_action_type": "FUNCTION_CALLING_PERFORMED_ACTION"
}
],
"session_id":
"ocid1.genaiagentsession.oc1.ap-osaka-1.xxx",
"should_stream": false,
"tool_parameters": null,
"user_message": "null"
}
[05/08/25 15:19:36] DEBUG Chat succeeded response: {
"guardrail_result": null,
"message": {
"content": {
"citations": null,
"paragraph_citations": null,
"text": "Your most recent order, order_222222, has been refunded."
},
"role": "AGENT",
"time_created": "2025-05-08T22:19:36.460000+00:00"
},
"required_actions": null,
"tool_results": null,
"traces": [
{
"time_created": "2025-05-08T22:19:36.048000+00:00",
"trace_type": "UNKNOWN_ENUM_VALUE"
}
]
}
DEBUG Chat succeeded opc-request-id:
5DF2A7C7E07F4DBDAE43373AADB51D22/4F09D0E8DAB0C8B3F72D1D684B4958C3/114ADCF1B6EBA536C
3A727BE80B570C1
Quando utilizzare la modalità debug
Abilita modalità di debug quando:
- Risoluzione dei problemi relativi a comportamenti o errori imprevisti
- Collaborazione con il Supporto Oracle su un problema
- Informazioni sul flusso di esecuzione dell'agente
- Sviluppare nuove funzionalità per gli agenti e voler visualizzare le interazioni dettagliate
Nota: ricordarsi di disabilitare la modalità di debug negli ambienti di produzione annullando l'impostazione di questa variabile di ambiente, poiché questa modalità genera log descrittivi che potrebbero influire sulle prestazioni.
unset ADK_LOG_LEVEL
Integrazione con i framework di log
ADK utilizza il modulo di log standard di Python. Se l'applicazione utilizza una configurazione di log personalizzata, è anche possibile controllare il livello di log ADK a livello di programmazione:
import logging
logging.getLogger('adk').setLevel(logging.DEBUG)
Questo metodo offre un controllo più dettagliato sul log in applicazioni complesse.