Logging in the Agent Development Kit (ADK)

在智能体开发工具包 (ADK) 中进行日志记录

Supported in ADKPython v0.1.0TypeScript v0.2.0Go v0.1.0Java v0.1.0

The Agent Development Kit (ADK) uses Python's standard logging module to provide flexible and powerful logging capabilities. Understanding how to configure and interpret these logs is crucial for monitoring agent behavior and debugging issues effectively.

智能体开发工具包 (ADK) 使用 Python 的标准 logging 模块提供灵活而强大的日志记录功能。了解如何配置和解释这些日志对于有效监控智能体行为和调试问题至关重要。

Logging Philosophy

日志记录理念

ADK's approach to logging is to provide detailed diagnostic information without being overly verbose by default. It is designed to be configured by the application developer, allowing you to tailor the log output to your specific needs, whether in a development or production environment.

ADK 的日志记录方法是在默认情况下不过于冗长地提供详细的诊断信息。它旨在由应用程序开发人员进行配置，允许您根据特定需求定制日志输出，无论是在开发还是生产环境中。

• Standard Library: It uses the standard logging library, so any configuration or handler that works with it will work with ADK.

标准库： 它使用标准的 logging 库，因此任何适用于它的配置或处理程序都适用于 ADK。

• Hierarchical Loggers: Loggers are named hierarchically based on the module path (e.g., google_adk.google.adk.agents.llm_agent), allowing for fine-grained control over which parts of the framework produce logs.

分层记录器： 记录器基于模块路径进行分层命名（例如，google_adk.google.adk.agents.llm_agent），允许对框架的哪些部分生成日志进行细粒度控制。

• User-Configured: The framework does not configure logging itself. It is the responsibility of the developer using the framework to set up the desired logging configuration in their application's entry point.

用户配置： 框架本身不配置日志记录。这是使用框架的开发人员的责任，需要在他们的应用程序入口点设置所需的日志配置。

How to Configure Logging

如何配置日志记录

You can configure logging in your main application script (e.g., main.py) before you initialize and run your agent. The simplest way is to use logging.basicConfig.

您可以在初始化和运行智能体之前，在主应用程序脚本（例如，main.py）中配置日志记录。最简单的方法是使用 logging.basicConfig。

Example Configuration

配置示例

To enable detailed logging, including DEBUG level messages, add the following to the top of your script:

要启用详细日志记录，包括 DEBUG 级别的消息，请在脚本顶部添加以下内容：

import logging

logging.basicConfig(
    level=logging.DEBUG,
    format='%(asctime)s - %(levelname)s - %(name)s - %(message)s'
)

Configuring Logging with the ADK CLI

使用 ADK CLI 配置日志记录

When running agents using ADK's built-in web or API servers, you can easily control log verbosity directly from the command line. The adk web, adk api_server, and adk deploy cloud_run commands all accept a --log_level option.

当使用 ADK 的内置 Web 或 API 服务器运行智能体时，您可以直接从命令行轻松控制日志详细程度。adk web、adk api_server 和 adk deploy cloud_run 命令都接受 --log_level 选项。

This provides a convenient way to set the logging level without modifying your agent's source code.

这提供了一种方便的方法来设置日志级别，而无需修改智能体的源代码。

Note: The command-line setting always takes precedence over programmatic configuration (like logging.basicConfig) for ADK's loggers. It's recommended to use INFO or WARNING in production and enable DEBUG only when troubleshooting.

注意： 命令行设置始终优先于 ADK 记录器的编程配置（如 logging.basicConfig）。建议在生产环境中使用 INFO 或 WARNING，仅在故障排除时启用 DEBUG。

Example using adk web:

使用 adk web 的示例：

To start the web server with DEBUG level logging, run:

要以 DEBUG 级别日志记录启动 Web 服务器，请运行：

adk web --log_level DEBUG path/to/your/agents_dir

You can also use -v or --verbose as a shortcut for --log_level DEBUG.

您还可以使用 -v 或 --verbose 作为 --log_level DEBUG 的快捷方式。

adk web -v path/to/your/agents_dir

Log Levels

日志级别

ADK uses standard log levels to categorize messages. The configured level determines what information gets logged.

ADK 使用标准日志级别来对消息进行分类。配置的级别决定了记录哪些信息。

Level	Description	Type of Information Logged	级别	描述	记录的信息类型
DEBUG	Crucial for debugging. The most verbose level for fine-grained diagnostic information.	DEBUG	对调试至关重要。 用于细粒度诊断信息的最详细级别。	完整的 LLM 提示： 发送到语言模型的完整请求，包括系统指令、历史记录和工具。 来自服务的详细 API 响应。 内部状态转换和变量值。
INFO	General information about the agent's lifecycle.	INFO	关于智能体生命周期的一般信息。	智能体初始化和启动。 会话创建和删除事件。 工具的执行，包括其名称和参数。
WARNING	Indicates a potential issue or deprecated feature use. The agent continues to function, but attention may be required.	WARNING	指示潜在问题或已弃用功能的使用。智能体继续运行，但可能需要注意。	使用已弃用的方法或参数。 系统从中恢复的非关键错误。
ERROR	A serious error that prevented an operation from completing.	ERROR	阻止操作完成的严重错误。	对外部服务（例如，LLM、会话服务）失败的 API 调用。 智能体执行期间未处理的异常。 配置错误。

Note: It is recommended to use INFO or WARNING in production environments. Only enable DEBUG when actively troubleshooting an issue, as DEBUG logs can be very verbose and may contain sensitive information.

注意： 建议在生产环境中使用 INFO 或 WARNING。仅在主动排查问题时启用 DEBUG，因为 DEBUG 日志可能非常冗长，并且可能包含敏感信息。

Reading and Understanding Logs

阅读和理解日志

The format string in the basicConfig example determines the structure of each log message.

basicConfig 示例中的 format 字符串确定了每条日志消息的结构。

Here's a sample log entry:

这是一个示例日志条目：

2025-07-08 11:22:33,456 - DEBUG - google_adk.google.adk.models.google_llm - LLM Request: contents { ... }

Log Segment	Format Specifier	Meaning	日志段	格式说明符	含义
2025-07-08 11:22:33,456	%(asctime)s	Timestamp	2025-07-08 11:22:33,456	%(asctime)s	时间戳
DEBUG	%(levelname)s	Severity level	DEBUG	%(levelname)s	严重级别
google_adk.models.google_llm	%(name)s	Logger name (the module that produced the log)	google_adk.models.google_llm	%(name)s	记录器名称（产生日志的模块）
LLM Request: contents { ... }	%(message)s	The actual log message	LLM Request: contents { ... }	%(message)s	实际日志消息

By reading the logger name, you can immediately pinpoint the source of the log and understand its context within the agent's architecture.

通过读取记录器名称，您可以立即确定日志的来源，并理解其在智能体架构中的上下文。

Debugging with Logs: A Practical Example

使用日志进行调试：实用示例

Scenario: Your agent is not producing the expected output, and you suspect the prompt being sent to the LLM is incorrect or missing information.

场景： 您的智能体没有产生预期的输出，您怀疑发送到 LLM 的提示不正确或缺少信息。

Steps:

步骤：

1. Enable DEBUG Logging: In your main.py, set the logging level to DEBUG as shown in the configuration example.

   启用 DEBUG 日志记录： 在您的 main.py 中，按照配置示例将日志级别设置为 DEBUG。

   logging.basicConfig(
       level=logging.DEBUG,
       format='%(asctime)s - %(levelname)s - %(name)s - %(message)s'
   )
   

2. Run Your Agent: Execute your agent's task as you normally would.

   运行您的智能体： 像往常一样执行您的智能体的任务。

3. Inspect the Logs: Look through the console output for a message from the google.adk.models.google_llm logger that starts with LLM Request:.

   检查日志： 查看控制台输出，寻找来自 google.adk.models.google_llm 记录器的以 LLM Request: 开头的消息。

   ...
   2025-07-10 15:26:13,778 - DEBUG - google_adk.google.adk.models.google_llm - Sending out request, model: gemini-2.0-flash, backend: GoogleLLMVariant.GEMINI_API, stream: False
   2025-07-10 15:26:13,778 - DEBUG - google_adk.google.adk.models.google_llm -
   LLM Request:
   -----------------------------------------------------------
   System Instruction:
   
         You roll dice and answer questions about the outcome of the dice rolls.
         You can roll dice of different sizes.
         You can use multiple tools in parallel by calling functions in parallel(in one request and in one round).
         It is ok to discuss previous dice roles, and comment on dice rolls.
         When you are asked to roll a die, you must call the roll_die tool with the number of sides. Be sure to pass in an integer. Do not pass in a string.
         You should never roll a die on your own.
         When checking prime numbers, call the check_prime tool with a list of integers. Be sure to pass in a list of integers. You should never pass in a string.
         You should not check prime numbers before calling the tool.
         When you are asked to roll a die and check prime numbers, you should always make the following two function calls:
         1. You should first call the roll_die tool to get a roll. Wait for the function response before calling the check_prime tool.
         2. After you get the function response from roll_die tool, you should call the check_prime tool with the roll_die result.
           2.1 If user asks you to check primes based on previous rolls, make sure you include previous rolls in the list.
         3. When you respond, you must include the roll_die result from step 1.
         You should always perform the previous 3 steps when asking for a roll and checking prime numbers.
         You should not rely on previous history on prime results.
   
   你掷骰子并回答关于骰子结果的问题。
   你可以掷不同大小的骰子。
   你可以通过并行调用函数（在一个请求中和一轮中）来并行使用多个工具。
   讨论以前的骰子结果并评论骰子掷是可以的。
   当你被要求掷骰子时，你必须使用骰子面数调用 roll_die 工具。确保传递整数。不要传递字符串。
   你不应该自己掷骰子。
   当检查质数时，使用整数列表调用 check_prime 工具。确保传递整数列表。你不应该传递字符串。
   你不应该在调用工具之前检查质数。
   当你被要求掷骰子和检查质数时，你应该始终执行以下两个函数调用：
         1. 你应该首先调用 roll_die 工具来获得掷骰结果。在调用 check_prime 工具之前等待函数响应。
         2. 在你从 roll_die 工具获得函数响应后，你应该使用 roll_die 结果调用 check_prime 工具。
           2.1 如果用户要求你根据以前的掷骰检查质数，确保在列表中包括以前的掷骰结果。
         3. 当你响应时，你必须包括步骤 1 中的 roll_die 结果。
         当要求掷骰子和检查质数时，你应该始终执行前面的 3 个步骤。
         你不应该在质数结果上依赖以前的历史记录。
   
   You are an agent. Your internal name is "hello_world_agent".
   
   你是一个智能体。你的内部名称是 "hello_world_agent"。
   
   The description about you is "hello world agent that can roll a dice of 8 sides and check prime numbers."
   关于你的描述是"可以掷 8 面骰子并检查质数的 hello world 智能体"。
   
   -----------------------------------------------------------
   Contents:
   {"parts":[{"text":"Roll a 6 sided dice"}],"role":"user"}
   {"parts":[{"function_call":{"args":{"sides":6},"name":"roll_die"}}],"role":"model"}
   {"parts":[{"function_response":{"name":"roll_die","response":{"result":2}}}],"role":"user"}
   -----------------------------------------------------------
   Functions:
   roll_die: {'sides': {'type': <Type.INTEGER: 'INTEGER'>}}
   check_prime: {'nums': {'items': {'type': <Type.INTEGER: 'INTEGER'>}, 'type': <Type.ARRAY: 'ARRAY'>}}
   -----------------------------------------------------------
   
   2025-07-10 15:26:13,779 - INFO - google_genai.models - AFC is enabled with max remote calls: 10.
   2025-07-10 15:26:14,309 - INFO - google_adk.google.adk.models.google_llm -
   LLM Response:
   -----------------------------------------------------------
   Text:
   I have rolled a 6 sided die, and the result is 2.
   我已经掷了一个 6 面骰子，结果是 2。
   ...
   

4. Analyze the Prompt: By examining the System Instruction, contents, functions sections of the logged request, you can verify:

   分析提示： 通过检查记录请求的 System Instruction、contents、functions 部分，您可以验证：

   • Is the system instruction correct? 系统指令是否正确？
   • Is the conversation history (user and model turns) accurate? 对话历史（user 和 model 轮次）是否准确？
   • Is the most recent user query included? 是否包含最新的用户查询？
   • Are the correct tools being provided to the model? 是否向模型提供了正确的工具？
   • Are the tools correctly called by the model? 模型是否正确调用了工具？
   • How long does it take for the model to respond? 模型响应需要多长时间？

This detailed output allows you to diagnose a wide range of issues, from incorrect prompt engineering to problems with tool definitions, directly from the log files.

这种详细的输出使您能够直接从日志文件中诊断广泛的问题，从不正确的提示工程到工具定义的问题。