Ativando o Modo de Depuração
Saiba como ativar o log de depuração no ADK para diagnóstico e solução de problemas.
Depurar log-in no ADK
Quando você desenvolve ou soluciona problemas de um aplicativo criado com o ADK, para obter informações mais detalhadas sobre o que está acontecendo nos bastidores, você pode ativar o modo de registro de depuração. Você pode ativar esse modo no ADK por meio de uma variável de ambiente.
Ativando o modo de depuração
Para ativar o log de depuração no ADK, defina a variável de ambiente ADK_LOG_LEVEL como DEBUG:
export ADK_LOG_LEVEL=DEBUG
No Windows, você pode definir essa variável de ambiente usando o comando set:
set ADK_LOG_LEVEL=DEBUG
Depois de definir essa variável de ambiente, execute seu aplicativo ADK como de costume e você verá um log mais detalhado na saída.
As informações do modo de depuração
Quando o modo de depuração estiver ativado, você obterá as seguintes informações:
- OCIDs de Recursos: Identificadores exclusivos para os recursos do OCI que estão sendo usados
- IDs de Solicitação do OPC: os identificadores de solicitação a serem referenciados ao trabalhar com o Oracle Support
- Detalhes de Solicitação/Resposta de API: Detalhes sobre a comunicação com serviços do OCI
- Logs de Operação Internos: Informações sobre como o ADK está processando suas solicitações
- Rastreamentos de Execução da Ferramenta: Logs detalhados sobre chamadas de ferramentas e seus resultados
Dica: Se você encontrar um problema, salve seus logs de depuração. Esses logs são úteis ao relatar problemas à equipe de serviço do OCI Generative AI Agents ou ao Suporte Técnico da Oracle.
Exemplo de saída
Veja um exemplo de saída após a execução de um aplicativo ADK, com o modo de log de depuração ativado:
[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 usar o modo de depuração
Ativar o modo de depuração quando:
- Diagnosticando e solucionando problemas de comportamentos ou erros inesperados
- Trabalhando com o Suporte Técnico da Oracle em um problema
- Compreendendo o fluxo de execução do seu agente
- Desenvolvendo novos recursos do agente e querendo ver as interações detalhadas
Observação: Lembre-se de desativar o modo de depuração em ambientes de produção cancelando a definição dessa variável de ambiente porque esse modo gera logs detalhados que podem afetar o desempenho.
unset ADK_LOG_LEVEL
Integração com Frameworks de Log
O ADK usa o módulo de log padrão do Python. Se seu aplicativo usar uma configuração de log personalizada, você também poderá controlar o nível de log do ADK de forma programática:
import logging
logging.getLogger('adk').setLevel(logging.DEBUG)
Este método oferece um controle mais detalhado sobre o registro em aplicativos complexos.