智能体开发工具包（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 选项。

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

Note: The command-line setting always takes precedence over the 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.

Example using adk web:

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

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

The available log levels for the --log_level option are:

DEBUG
INFO（默认）
WARNING
ERROR
CRITICAL

You can also use -v or --verbose as a a shortcut for --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.

Level	Description	Type of Information Logged
`DEBUG`	Crucial for debugging. The most verbose level for fine-grained diagnostic information.	Full LLM Prompts: The complete request sent to the language model, including system instructions, history, and tools. Detailed API responses from services. Internal state transitions and variable values.
`INFO`	General information about the agent's lifecycle.	Agent initialization and startup. Session creation and deletion events. Execution of a tool, including its name and arguments.
`WARNING`	Indicates a potential issue or deprecated feature use. The agent continues to function, but attention may be required.	Use of deprecated methods or parameters. Non-critical errors that the system recovered from.
`ERROR`	A serious error that prevented an operation from completing.	Failed API calls to external services (e.g., LLM, Session Service). Unhandled exceptions during agent execution. Configuration errors.

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.

如何阅读和理解日志¶

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

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
`DEBUG`	`%(levelname)s`	Severity level
`google_adk.models.google_llm`	`%(name)s`	Logger name (the module that produced the log)
`LLM Request: contents { ... }`	`%(message)s`	The actual log message

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

日志调试实战示例¶

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

步骤：

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

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

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

检查日志： 在控制台输出中查找来自 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。
...

分析提示内容： 通过检查日志中的 System Instruction、contents、functions 部分，你可以验证：
- 系统指令是否正确？
- 对话历史（user 和 model 回合）是否准确？
- 最新用户请求是否包含？
- 是否为模型提供了正确的工具？
- 模型是否正确调用了工具？
- 模型响应耗时如何？

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