智能体开发工具包（ADK）中的日志记录

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

智能体开发工具包（ADK）使用 Python 标准库的 logging 模块，提供灵活且强大的日志记录能力。理解如何配置和解读这些日志，对于监控智能体行为和高效调试问题至关重要。

日志理念

ADK 的日志理念是：在默认情况下提供详细的诊断信息，但不过度冗余。日志设计为由应用开发者自行配置，你可以根据开发或生产环境的具体需求，定制日志输出。

• 标准库： 使用标准的 logging 库，因此任何适用于该库的配置或处理器都适用于 ADK。
• 分层日志器： 日志器名称基于模块路径分层命名（如 google_adk.google.adk.agents.llm_agent），允许你精细控制框架中哪些部分产生日志。
• 用户配置： 框架本身不会主动配置日志。由使用该框架的开发者在应用入口处设置所需的日志配置。

如何配置日志

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

配置示例

要启用详细日志（包括 DEBUG 级别信息），在脚本顶部添加如下内容：

import logging

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

# 你的 ADK 智能体代码在下方...
# from google.adk.agents import LlmAgent
# ...

使用 ADK CLI 配置日志

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

这提供了一种在不修改智能体源代码的情况下设置日志级别的便捷方法。

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

使用 adk web 的示例：

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

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

可用于 --log_level 选项的日志级别有：

• DEBUG
• INFO（默认）
• WARNING
• ERROR
• CRITICAL

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

adk web -v path/to/your/agents_dir

日志级别

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

级别	描述	记录的信息类型
DEBUG	对调试至关重要。 最详细的级别，用于细粒度的诊断信息。	完整的 LLM 提示： 发送给语言模型的完整请求，包括系统指令、历史记录和工具。 来自服务的详细 API 响应。 内部状态转换和变量值。
INFO	关于智能体生命周期的通用信息。	智能体初始化和启动。 会话创建和删除事件。 工具的执行，包括其名称和参数。
WARNING	表示潜在问题或使用了已弃用的功能。智能体继续运行，但可能需要注意。	使用了已弃用的方法或参数。 系统已从中恢复的非关键错误。
ERROR	阻止操作完成的严重错误。	对外部服务（例如 LLM、会话服务）的 API 调用失败。 智能体执行期间未处理的异常。 配置错误。

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

如何阅读和理解日志

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

这是一个示例日志条目：

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

日志段落	格式说明符	含义
2025-07-08 11:22:33,456	%(asctime)s	时间戳
DEBUG	%(levelname)s	严重级别
google_adk.models.google_llm	%(name)s	日志器名称（产生日志的模块）
LLM Request: contents { ... }	%(message)s	实际的日志消息

通过查看日志器名称，你可以立即定位日志来源，并理解其在智能体架构中的上下文。

日志调试实战示例

场景： 你的智能体未产生预期输出，你怀疑发送给 LLM 的提示有误或缺失信息。

步骤：

1. 启用 DEBUG 日志： 在 main.py 中，将日志级别设置为 DEBUG，如配置示例所示。

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

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

3. 检查日志： 在控制台输出中查找来自 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 the 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 the 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 the previous history on prime results.
   
   
   你是一个智能体。你的内部名称是 "hello_world_agent"。
   
   你的描述是 "可以掷 8 面骰子并检查质数的 hello world 智能体。"
   -----------------------------------------------------------
   Contents:
   {"parts":[{"text":"掷一个 6 面骰子"}],"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:
   我掷了一个 6 面骰子，结果是 2。
   ...
   

4. 分析提示内容： 通过检查日志中的 System Instruction、contents、functions 部分，你可以验证：

   • 系统指令是否正确？
   • 对话历史（user 和 model 回合）是否准确？
   • 最新用户请求是否包含？
   • 是否为模型提供了正确的工具？
   • 模型是否正确调用了工具？
   • 模型响应耗时如何？

这些详细输出让你可以直接通过日志文件诊断从提示工程到工具定义等各种问题。