教程6：回调

确保翻译不显得太生硬。确保翻译注释。
这个文件是用Markdown格式写的。不要把它当作XML或HTML。
不要翻译任何[!NOTE]、[!WARNING]、[!TIP]、[!IMPORTANT]或[!CAUTION]。
不要翻译任何实体，如变量名、函数名、类名，或占位符如@@INLINE_CODE_x@@或@@CODE_BLOCK_x@@，但保留它们在文件中。
不要翻译任何URL或路径，但保留它们在文件中。
请从左到右写输出。

教程 6：回调

你将学到的内容

• 代理生命周期回调：监控代理的创建、初始化和清理过程
• LLM 交互回调：跟踪模型请求、响应和令牌使用情况
• 工具执行回调：监控工具调用、参数和执行结果

核心概念：回调

回调是在代理执行过程中特定时刻被调用的函数，允许你在不修改核心逻辑的情况下，监控、记录并控制代理的行为。

回调流程图

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Agent Start   │───▶│  LLM Request    │───▶│  Tool Execution │
│   Callback      │    │   Callback      │    │   Callback      │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│  Agent End      │    │  LLM Response   │    │  Tool Result    │
│  Callback       │    │   Callback      │    │   Callback      │
└─────────────────┘    └─────────────────┘    └─────────────────┘
​

为什么使用回调？

• 监控：跟踪代理的性能和行为
• 日志记录：记录交互以进行调试和分析
• 控制：根据特定事件修改行为
• 集成：将代理连接到外部系统
• 调试：了解代理内部发生了什么

教程概览

本教程涵盖 Google ADK 中三种关键的回调模式：

1. 代理生命周期回调：监控代理的创建、初始化和清理事件
2. LLM 交互回调：跟踪模型请求、响应和令牌使用情况
3. 工具执行回调：监控工具调用、参数和执行结果

每个子教程都提供了简单而专注的示例，演示具体的回调模式。

项目结构

6_callbacks/
├── README.md                           # This file - concept explanation
├── 6_1_agent_lifecycle_callbacks/      # Agent lifecycle monitoring
│   ├── README.md                       # Lifecycle callback patterns
│   ├── agent.py                        # Agent with lifecycle callbacks
│   ├── app.py                          # Streamlit interface
│   └── requirements.txt                # Dependencies
├── 6_2_llm_interaction_callbacks/      # LLM request/response tracking
│   ├── README.md                       # LLM callback patterns
│   ├── agent.py                        # Agent with LLM callbacks
│   ├── app.py                          # Streamlit interface
│   └── requirements.txt                # Dependencies
└── 6_3_tool_execution_callbacks/       # Tool execution monitoring
    ├── README.md                       # Tool callback patterns
    ├── agent.py                        # Agent with tool callbacks
    ├── app.py                          # Streamlit interface
    └── requirements.txt                # Dependencies
​

学习目标

完成本教程后，你将掌握以下内容：

• ✅ 回调基础：回调在 Google ADK 中的工作原理
• ✅ 生命周期监控：跟踪代理的创建、初始化和清理过程
• ✅ LLM 跟踪：监控模型请求、响应和性能
• ✅ 工具监控：跟踪工具的执行和结果
• ✅ 实际应用：回调的实际应用场景
• ✅ 调试技巧：利用回调进行故障排除

开始使用

前提条件

• Python 3.11+
• Google AI Studio API 密钥
• 对 Google ADK 的基本理解（教程 1-5）

设置

1. 获取 API 密钥：访问 Google AI Studio
2. 创建 .env 文件：添加 GOOGLE_API_KEY=your_key_here
3. Install dependencies: pip install -r requirements.txt

运行教程

# Agent Lifecycle Callbacks
cd 6_1_agent_lifecycle_callbacks
streamlit run app.py

# LLM Interaction Callbacks  
cd ../6_2_llm_interaction_callbacks
streamlit run app.py

# Tool Execution Callbacks
cd ../6_3_tool_execution_callbacks
streamlit run app.py
​

⚙️ 回调模式

1. 代理生命周期回调

def on_agent_start(agent_name: str):
    print(f"▶️ Agent {agent_name} started")

def on_agent_end(agent_name: str, result: str):
    print(f"✅ Agent {agent_name} completed: {result}")

# Register callbacks
agent = LlmAgent(
    name="my_agent",
    model="gemini-3-flash-preview",
    on_start=on_agent_start,
    on_end=on_agent_end
)
​

2. LLM 交互回调

def on_llm_request(model: str, prompt: str):
    print(f" LLM Request to {model}: {prompt[:50]}...")

def on_llm_response(model: str, response: str, tokens: int):
    print(f" LLM Response from {model}: {tokens} tokens")

# Register callbacks
agent = LlmAgent(
    name="my_agent",
    model="gemini-3-flash-preview",
    on_llm_request=on_llm_request,
    on_llm_response=on_llm_response
)
​

3. 工具执行回调

def on_tool_start(tool_name: str, params: dict):
    print(f" Tool {tool_name} started with params: {params}")

def on_tool_end(tool_name: str, result: str):
    print(f"✅ Tool {tool_name} completed: {result}")

# Register callbacks
agent = LlmAgent(
    name="my_agent",
    model="gemini-3-flash-preview",
    tools=[my_tool],
    on_tool_start=on_tool_start,
    on_tool_end=on_tool_end
)
​

使用场景

监控与分析

• 跟踪代理的性能指标
• 监控令牌使用量和成本
• 分析工具使用模式
• 调试代理行为

日志记录与调试

• 记录所有代理交互
• 调试工具执行问题
• 监控 LLM 响应质量
• 跟踪错误模式

集成与控制

• 连接到外部监控系统
• 实现自定义错误处理
• 添加身份验证和校验
• 动态控制代理行为

下一步

完成本教程后，你将准备好：

• 高级代理模式：复杂代理架构
• 生产部署：将代理部署到生产环境
• 自定义工具：构建自定义工具和集成

更多资源

• Google ADK 文档
• 回调 API 参考
• 最佳实践指南

免责声明：
本文档采用基于机器的 AI 翻译服务进行翻译。尽管我们力求准确，但请注意，自动翻译可能存在错误或不准确之处。应以原文语言版本的文档作为权威依据。如需获取关键信息，建议使用专业的人工翻译。对于因使用本翻译而产生的任何误解或误读，我们概不负责。