デバッグ・モードの有効化

トラブルシューティングのためにADKでデバッグ・ロギングを有効にする方法を学習します。

ADKでのデバッグ・ロギング

ADKを使用して構築されたアプリケーションを開発またはトラブルシューティングする場合、バックグラウンドで何が起こっているかについてより詳細な情報を取得するために、デバッグ・ロギング・モードを有効にできます。このモードは、環境変数を使用してADKで有効にできます。

デバッグ・モードの有効化

ADKでデバッグ・ロギングを有効にするには、ADK_LOG_LEVEL環境変数をDEBUGに設定します。

export ADK_LOG_LEVEL=DEBUG

Windowsでは、setコマンドを使用してこの環境変数を設定できます。

set ADK_LOG_LEVEL=DEBUG

この環境変数を設定した後、ADKアプリケーションを通常どおり実行すると、出力に詳細なログが表示されます。

デバッグ・モード情報

デバッグ・モードを有効にすると、次の情報が得られます。

リソースOCIDs: 使用されているOCIリソースの一意の識別子
OPCリクエストID: Oracleサポートでの作業時に参照するリクエスト識別子
APIリクエスト/レスポンスの詳細: OCIサービスとの通信の詳細
内部操作ログ: ADKによるリクエストの処理方法に関する情報
ツール実行トレース: ツールの起動とその結果に関する詳細なログ

ヒント:問題が発生した場合は、デバッグ・ログを保存します。これらのログは、OCI生成AIエージェント・サービス・チームまたはOracle Supportに問題を報告する際に役立ちます。

出力例

デバッグ・ロギング・モードを有効にしたADKアプリケーションを実行した後の出力例を次に示します。

[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

デバッグ・モードを使用する場合

次の場合にデバッグ・モードを有効化します。

予期しない動作またはエラーのトラブルシューティング
問題に対するOracle Supportの操作
エージェントの実行フローの理解
新しいエージェント機能の開発と詳細なインタラクションの確認

ノート:このモードはパフォーマンスに影響を与える可能性のある詳細なログを生成するため、この環境変数を設定解除して、本番環境ではデバッグ・モードを無効にしてください。

unset ADK_LOG_LEVEL

ロギング・フレームワークとの統合

ADKは、Pythonの標準ロギング・モジュールを使用します。アプリケーションでカスタム・ロギング構成を使用する場合、ADKログ・レベルをプログラムで制御することもできます。

import logging
logging.getLogger('adk').setLevel(logging.DEBUG)

この方法を使用すると、複雑なアプリケーションのログインをより詳細に制御できます。

Oracle Cloud Infrastructureドキュメント

デバッグ・モードの有効化

ADKでのデバッグ・ロギング