6.1代理生命周期回调

文档摘要

6.1 代理生命周期回调本教程演示如何使用和监控代理执行的生命周期。学习目标理解代理生命周期回调学习如何监控代理执行的时间了解如何在回调之间共享状态练习实现性能监控项目结构设置安装依赖：设置 API 密钥：运行演示命令行演示 Web 界面核心概念：代理生命周期监控代理生命周期回调允许您监控代理执行的开始和结束，从而了解代理何时启动并完成任务。代理生命周期流程回调执行时间线代码详解 1.

6.1 代理生命周期回调

本教程演示如何使用before_agent_callback 和 after_agent_callback 监控代理执行的生命周期。

学习目标

理解代理生命周期回调
学习如何监控代理执行的时间
了解如何在回调之间共享状态
练习实现性能监控

项目结构


6_1_agent_lifecycle_callbacks/
├── agent.py          # Agent with lifecycle callbacks
├── app.py            # Streamlit web interface
├── requirements.txt  # Python dependencies
└── README.md         # This file

设置

安装依赖：
```
pip install -r requirements.txt
```

设置 API 密钥：


# Create .env file
echo "GOOGLE_API_KEY=your_api_key_here" > .env

运行演示

命令行演示


python agent.py

Web 界面


streamlit run app.py

核心概念：代理生命周期监控

代理生命周期回调允许您监控代理执行的开始和结束，从而了解代理何时启动并完成任务。

代理生命周期流程


┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   User Input    │───▶│  Agent Start    │───▶│  Agent End      │
│                 │    │   Callback      │    │   Callback      │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                              │                       │
                              ▼                       ▼
                       ┌─────────────────┐    ┌─────────────────┐
                       │  Agent Logic    │    │  Performance    │
                       │  Execution      │    │  Metrics        │
                       └─────────────────┘    └─────────────────┘

回调执行时间线


Timeline: ──────────────────────────────────────────────────────────▶

User Message
    │
    ▼
┌─────────────────┐
│ before_agent    │ ← Records start time, agent info
│ _callback       │
└─────────────────┘
    │
    ▼
┌─────────────────┐
│ Agent Logic     │ ← Core agent processing
│ Execution       │
└─────────────────┘
    │
    ▼
┌─────────────────┐
│ after_agent     │ ← Calculates duration, logs completion
│ _callback       │
└─────────────────┘
    │
    ▼
Response to User

代码详解

1. 回调函数

这些回调成对工作，以监控完整的代理生命周期：

Before 回调 (before_agent_callback)：

记录执行开始时间戳
将开始时间存储在会话状态中，供 after 回调使用
记录代理执行开始（代理名称、时间）
返回 None 以允许正常执行

After 回调 (after_agent_callback)：

从会话状态中获取开始时间
计算总的执行时长
记录完成情况及性能指标
返回 None 以使用原始结果

2. 回调之间的状态管理


Session State Flow:
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│ before_callback │───▶│  Session State  │───▶│ after_callback  │
│ stores:         │    │                 │    │ retrieves:      │
│ - start_time    │    │ - request_start │    │ - start_time    │
│                 │    │   _time         │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘

3. 代理设置

该代理配置了两个生命周期回调：

before_agent_callback：监控代理执行开始
after_agent_callback：监控代理执行完成
使用 InMemoryRunner 以正确触发回调

测试示例

示例输出格式


 Agent LifecycleDemoAgent started at 19:15:30
⏰ Start time: 2024-01-15 19:15:30

✅ Agent LifecycleDemoAgent completed
⏱️ Duration: 1.23s
⏰ End time: 2024-01-15 19:15:31
 Performance: 1.23s | LifecycleDemoAgent

每个指标所代表的意义

** 开始时间**：代理开始处理的时间
✅ 完成时间：代理完成处理的时间
⏱️ 持续时间：总执行时长，单位为秒
** 性能**：格式化的性能摘要

关键概念

代理生命周期监控

执行开始：跟踪代理何时开始处理
执行结束：跟踪代理何时完成任务
性能计时：计算总的执行时长
状态共享：在回调之间传递计时数据

CallbackContext

agent_name：正在执行的代理名称
invocation_id：本次执行的唯一标识符
state：在回调之间持续的会话状态

状态管理

使用 callback_context.state.to_dict() to get current state
Use callback_context.state.update() 修改状态
状态在 before 和 after 回调之间共享

使用场景

性能监控：跟踪执行时间
日志记录：记录代理活动
分析：收集使用统计信息
调试：监控代理行为
自定义逻辑：添加前后处理

常见错误

忘记等待会话创建：


# ❌ Wrong
session_service.create_session(...)

# ✅ Correct
await session_service.create_session(...)

使用了错误的回调签名：


# ❌ Wrong
def after_agent_callback(context, result):

# ✅ Correct
def after_agent_callback(callback_context: CallbackContext):

未使用 InMemoryRunner：


# ❌ Wrong - callbacks won't trigger
agent.run(message)

# ✅ Correct
runner.run_async(...)

⚠️ 重要实现注意事项

事件循环完成：如果您在接收到 is_final_response() 后立即中断事件循环，after_agent_callback 将不会触发。

正确模式：让事件循环自然完成：


# ❌ Wrong - breaks loop early, after_agent_callback won't run
if event.is_final_response() and event.content:
    response_text = event.content.parts[0].text.strip()
    break  # This prevents after_agent_callback from running

# ✅ Correct - let loop complete naturally
if event.is_final_response() and event.content:
    response_text = event.content.parts[0].text.strip()
    # Don't break - let the loop complete to ensure callbacks run

这是已知的 ADK 行为，提前中断循环会导致清理回调无法执行。

下一步

尝试教程 6.2：LLM 交互回调
实验回调之间的状态管理
添加自定义日志记录或分析
实现慢响应的性能告警

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