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

智能体开发工具包（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 web 的示例：

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

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

--log_level 选项的可用日志级别有： - DEBUG - INFO（默认） - WARNING - ERROR - CRITICAL

对于 DEBUG 级别，你还可以使用 -v 或 --verbose 作为 --log_level DEBUG 的快捷方式。例如：

adk web -v path/to/your/agents_dir

此命令行设置会覆盖你在代码中为 ADK 的日志器设置的任何程序化配置（如 logging.basicConfig）。

日志级别

ADK 使用标准日志级别对消息的重要性进行分类：

• DEBUG：最详细的级别。用于细粒度诊断信息，如发送给 LLM 的完整提示、详细状态变更和内部逻辑流程。调试时至关重要。
• INFO：关于智能体生命周期的一般信息，包括智能体启动、会话创建和工具执行等事件。
• WARNING：表示潜在问题或使用了已弃用的功能。智能体可以继续运行，但可能需要关注。
• ERROR：发生严重错误，导致智能体无法完成某项操作。

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

日志内容

根据配置的日志级别，你可以看到如下信息：

级别	日志信息类型
DEBUG	- 完整 LLM 提示： 发送给大语言模型的完整请求，包括系统指令、历史记录和工具。
	- 来自服务的详细 API 响应。
	- 内部状态变更和变量值。
INFO	- 智能体初始化和启动。
	- 会话创建和删除事件。
	- 工具执行，包括工具名称和参数。
WARNING	- 使用了已弃用的方法或参数。
	- 系统可恢复的非关键错误。
ERROR	- 对外部服务（如 LLM、会话服务）的 API 调用失败。
	- 智能体执行期间未处理的异常。
	- 配置错误。

如何阅读和理解日志

basicConfig 示例中的 format 字符串决定了每条日志消息的结构。下面解析一个日志示例：

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.google.adk.models.google_llm：%(name)s - 日志器名称。该分层名称精确指示日志来源模块，此处为 Google LLM 模型封装器。
• 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 - 发送请求，模型：gemini-2.0-flash，后端：GoogleLLMVariant.GEMINI_API，流：False
   2025-07-10 15:26:13,778 - DEBUG - google_adk.google.adk.models.google_llm - 
   LLM Request:
   -----------------------------------------------------------
   System Instruction:
   
         你掷骰子并回答有关骰子结果的问题。
         你可以掷不同面的骰子。
         你可以通过并行调用函数（在一次请求和一轮中）并行使用多个工具。
         可以讨论之前的骰子结果，并对骰子结果进行评论。
         当你被要求掷骰子时，必须调用 roll_die 工具并传入面数。务必传入整数，不要传入字符串。
         你不应自行掷骰子。
         检查质数时，调用 check_prime 工具并传入整数列表。务必传入整数列表，绝不能传入字符串。
         在调用工具前不应检查质数。
         当你被要求掷骰子并检查质数时，必须始终执行以下两个函数调用：
         1. 首先调用 roll_die 工具获取结果。等待函数响应后再调用 check_prime 工具。
         2. 在收到 roll_die 工具的函数响应后，调用 check_prime 工具并传入 roll_die 结果。
           2.1 如果用户要求基于之前的骰子结果检查质数，确保包含之前的结果。
         3. 回答时，必须包含第 1 步的 roll_die 结果。
         当要求掷骰子并检查质数时，始终执行上述 3 步。
         不要依赖之前的质数检查历史。
   
   
   你是一个智能体。你的内部名称是 "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 已启用，最大远程调用数：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 回合）是否准确？
   • 最新用户请求是否包含？
   • 是否为模型提供了正确的工具？
   • 模型是否正确调用了工具？
   • 模型响应耗时如何？

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