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:

1. Risoluzione dei problemi relativi a comportamenti o errori imprevisti
2. Collaborazione con il Supporto Oracle su un problema
3. Informazioni sul flusso di esecuzione dell'agente
4. 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.