ADK-Python核心回调配置：事件处理与钩子函数
项目地址: https://gitcode.com/GitHub_Trending/ad/adk-python 在构建复杂的AI Agent系统时，事件处理和钩子函数是至关重要的组件。ADK-Python（Agent Development Kit）提供了强大而灵活的回调配置机制，让开发者能够在Agent执行的关键节点注入自定义逻辑。本文将深入探讨ADK-Python的核心回调配置体系，帮助您掌握事件处理的最佳实践。
🔧 回调配置概览
ADK-Python的回调系统覆盖了Agent生命周期的各个关键阶段，包括：
| 回调类型 | 触发时机 | 主要用途 |
|---|---|---|
| Agent回调 | Agent执行前后 | 日志记录、状态监控、权限验证 |
| Model回调 | LLM调用前后 | 请求/响应处理、内容过滤、成本控制 |
| Tool回调 | 工具执行前后 | 参数验证、结果处理、错误恢复 |
| 插件回调 | 各种事件节点 | 扩展功能、集成第三方服务 |
🎯 核心回调类型详解
1. Agent级别回调
Agent回调在Agent执行的关键节点触发，主要用于全局状态管理和监控。
# 示例：Agent前后回调函数
async def before_agent_callback(callback_context):
"""Agent执行前的回调"""
print(f'Agent {callback_context.agent.name} 开始执行')
# 可以在这里添加权限验证、日志记录等逻辑
return None
async def after_agent_callback(callback_context):
"""Agent执行后的回调"""
print(f'Agent {callback_context.agent.name} 执行完成')
# 可以在这里添加状态清理、性能统计等逻辑
return None
2. Model级别回调
Model回调在LLM模型调用前后触发，用于处理模型请求和响应。
# 示例：Model前后回调函数
async def before_model_callback(callback_context, llm_request):
"""模型调用前的回调"""
print('准备调用LLM模型')
# 可以在这里修改请求参数、添加提示词等
return None
async def after_model_callback(callback_context, llm_response):
"""模型调用后的回调"""
print('LLM模型调用完成')
# 可以在这里处理响应内容、记录使用情况等
return None
3. Tool级别回调
Tool回调在工具函数执行前后触发，用于参数验证和结果处理。
# 示例：Tool前后回调函数
def before_tool_callback(tool, args, tool_context):
"""工具执行前的回调"""
print(f'准备执行工具: {tool.name}')
# 可以在这里验证参数、检查权限等
return None
def after_tool_callback(tool, args, tool_context, tool_response):
"""工具执行后的回调"""
print(f'工具 {tool.name} 执行完成')
# 可以在这里处理工具结果、记录执行日志等
return {'processed_response': tool_response}
📋 回调配置YAML示例
ADK-Python支持通过YAML配置文件定义回调链，实现声明式的回调管理。
name: advanced_agent_with_callbacks
model: gemini-2.0-flash
description: 带有完整回调链的高级Agent
instruction: |
你是一个智能助手，能够处理各种任务并使用工具。
tools:
- name: my_tools.roll_die
- name: my_tools.check_prime
# Agent级别回调配置
before_agent_callbacks:
- name: my_callbacks.before_agent_callback1
- name: my_callbacks.before_agent_callback2
after_agent_callbacks:
- name: my_callbacks.after_agent_callback1
- name: my_callbacks.after_agent_callback2
# Model级别回调配置
before_model_callbacks:
- name: my_callbacks.before_model_callback
after_model_callbacks:
- name: my_callbacks.after_model_callback
# Tool级别回调配置
before_tool_callbacks:
- name: my_callbacks.before_tool_callback1
- name: my_callbacks.before_tool_callback2
after_tool_callbacks:
- name: my_callbacks.after_tool_callback1
- name: my_callbacks.after_tool_callback2
🔄 回调执行流程
ADK-Python的回调系统遵循严格的执行顺序，确保逻辑的连贯性和可预测性。
💡 高级回调模式
1. 回调链处理
多个回调函数可以形成处理链，每个回调都可以修改上下文或返回值。
def callback_chain_example(callback_context):
"""回调链示例"""
# 第一个回调：记录开始时间
if not hasattr(callback_context.state, 'start_time'):
callback_context.state.start_time = time.time()
# 第二个回调：验证权限
if not validate_permission(callback_context):
raise PermissionError("权限验证失败")
# 第三个回调：准备执行环境
prepare_execution_environment(callback_context)
return None
2. 状态管理回调
利用回调上下文进行状态管理和数据传递。
def state_management_callback(callback_context):
"""状态管理回调示例"""
# 初始化状态
if not hasattr(callback_context.state, 'execution_count'):
callback_context.state.execution_count = 0
# 更新状态
callback_context.state.execution_count += 1
# 记录详细执行信息
execution_info = {
'timestamp': time.time(),
'agent_name': callback_context.agent.name,
'execution_id': str(uuid.uuid4())
}
if not hasattr(callback_context.state, 'execution_history'):
callback_context.state.execution_history = []
callback_context.state.execution_history.append(execution_info)
return None
3. 错误处理回调
专门处理执行过程中的异常情况。
async def error_handling_callback(callback_context, exception):
"""错误处理回调示例"""
print(f"发生错误: {str(exception)}")
# 记录错误日志
error_log = {
'timestamp': time.time(),
'error_type': type(exception).__name__,
'error_message': str(exception),
'stack_trace': traceback.format_exc()
}
# 可以在这里集成错误报告系统
report_error_to_monitoring_system(error_log)
# 决定是否继续执行或终止
if is_critical_error(exception):
return None # 终止执行
else:
return {'recovered': True} # 继续执行
🛠️ 实战案例：完整的回调配置
下面是一个完整的回调配置实战案例，展示了如何在实际项目中应用回调机制。
# callbacks.py - 完整的回调实现
import time
import logging
from typing import Dict, Any
from google.genai import types
# 配置日志
logger = logging.getLogger(__name__)
class AdvancedCallbacks:
"""高级回调集合"""
@staticmethod
async def before_agent_execution(callback_context):
"""Agent执行前回调"""
logger.info(f"Agent {callback_context.agent.name} 开始执行")
# 初始化执行上下文
callback_context.state.start_time = time.time()
callback_context.state.execution_phase = "agent_start"
return None
@staticmethod
async def after_agent_execution(callback_context):
"""Agent执行后回调"""
execution_time = time.time() - callback_context.state.start_time
logger.info(f"Agent执行完成，耗时: {execution_time:.2f}秒")
# 记录性能指标
record_performance_metrics({
'agent_name': callback_context.agent.name,
'execution_time': execution_time,
'completion_status': 'success'
})
return None
@staticmethod
async def before_model_invocation(callback_context, llm_request):
"""模型调用前回调"""
logger.info("准备调用LLM模型")
# 可以在这里修改提示词或添加系统指令
if hasattr(llm_request, 'contents'):
enhanced_content = enhance_prompt(llm_request.contents)
llm_request.contents = enhanced_content
return None
@staticmethod
async def after_model_invocation(callback_context, llm_response):
"""模型调用后回调"""
logger.info("LLM模型调用完成")
# 处理模型响应
processed_response = process_model_response(llm_response)
return processed_response
@staticmethod
def before_tool_execution(tool, args, tool_context):
"""工具执行前回调"""
logger.info(f"准备执行工具: {tool.name}")
# 参数验证
if not validate_tool_arguments(tool.name, args):
raise ValueError("工具参数验证失败")
# 权限检查
if not check_tool_permission(tool.name, tool_context):
raise PermissionError("没有执行该工具的权限")
return None
@staticmethod
def after_tool_execution(tool, args, tool_context, tool_response):
"""工具执行后回调"""
logger.info(f"工具 {tool.name} 执行完成")
# 结果处理
processed_result = {
'original_response': tool_response,
'processed_at': time.time(),
'tool_name': tool.name,
'execution_context': tool_context.state
}
return processed_result
# 辅助函数
def enhance_prompt(contents):
"""增强提示词"""
# 实际实现中可以根据需要修改提示词
return contents
def process_model_response(response):
"""处理模型响应"""
# 可以在这里进行内容过滤、格式转换等操作
return response
def validate_tool_arguments(tool_name, args):
"""验证工具参数"""
# 根据不同的工具进行参数验证
return True
def check_tool_permission(tool_name, context):
"""检查工具执行权限"""
# 实现权限检查逻辑
return True
def record_performance_metrics(metrics):
"""记录性能指标"""
# 实现指标记录逻辑
pass
📊 回调配置最佳实践
1. 性能考虑
| 实践 | 说明 | 推荐做法 |
|---|---|---|
| 异步回调 | 提高并发性能 | 尽量使用async/await |
| 回调链优化 | 减少不必要的回调 | 按需配置，避免过度使用 |
| 状态管理 | 高效的状态操作 | 使用callback_context.state |
2. 错误处理
def safe_callback_execution(callback_func, *args):
"""安全的回调执行包装器"""
try:
result = callback_func(*args)
return result
except Exception as e:
logger.error(f"回调执行失败: {str(e)}")
# 根据错误类型决定是否继续
if is_recoverable_error(e):
return {'error_handled': True}
else:
raise
3. 监控和日志
class MonitoredCallback:
"""带监控的回调装饰器"""
def __init__(self, callback_name):
self.callback_name = callback_name
def __call__(self, func):
def wrapper(*args, **kwargs):
start_time = time.time()
try:
result = func(*args, **kwargs)
execution_time = time.time() - start_time
# 记录执行指标
record_callback_metrics({
'name': self.callback_name,
'execution_time': execution_time,
'status': 'success'
})
return result
except Exception as e:
execution_time = time.time() - start_time
record_callback_metrics({
'name': self.callback_name,
'execution_time': execution_time,
'status': 'error',
'error': str(e)
})
raise
return wrapper
# 使用示例
@MonitoredCallback("before_agent_callback")
def monitored_before_agent_callback(callback_context):
"""带监控的Agent前回调"""
# 回调逻辑
return None
🚀 总结
ADK-Python的回调配置系统为开发者提供了强大的事件处理能力，通过合理的回调配置可以实现：
- 精细化的执行控制：在Agent生命周期的各个关键节点注入自定义逻辑
- 强大的扩展能力：通过回调机制集成第三方服务和处理复杂业务逻辑
- 完善的监控体系：利用回调进行性能监控、错误处理和状态管理
- 灵活的配置方式：支持代码配置和YAML声明式配置两种方式
掌握ADK-Python的回调配置，将帮助您构建更加健壮、可维护的AI Agent系统。无论是简单的日志记录还是复杂的业务逻辑处理，回调机制都能为您提供强大的支持。
在实际项目中，建议根据具体需求选择合适的回调类型和配置方式，平衡功能性和性能要求，打造高效的AI Agent解决方案。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
