教程6.3：工具执行回调

教程 6.3：工具执行回调

您将学到的内容

• 工具执行前回调：监控工具开始执行的时间
• 工具执行后回调：跟踪工具完成及结果
• 工具上下文：了解如何监控工具执行

核心概念：工具执行监控

工具执行回调让您能够监控代理何时使用工具、跟踪其执行生命周期并分析结果。这为您提供了对代理如何与外部系统和 API 交互的可见性。

工具执行流程

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Tool Call     │───▶│  Before Tool    │───▶│  Tool Execution │
│   (Agent)       │    │   Callback      │    │   (External)    │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                              │                       │
                              ▼                       ▼
                       ┌─────────────────┐    ┌─────────────────┐
                       │  After Tool     │    │  Tool Result    │
                       │   Callback      │    │   (Agent)       │
                       └─────────────────┘    └─────────────────┘
​

回调执行时间线

Time → 0ms    5ms    10ms   15ms   20ms   25ms
       │      │      │      │      │      │
       ▼      ▼      ▼      ▼      ▼      ▼
    [Tool] [Before] [Exec] [After] [Result]
    Call   Callback Start  Callback Return
​

用例

• 执行监控：跟踪工具开始和完成的时间
• 参数校验：在执行前检查工具输入
• 结果记录：记录工具输出和错误
• 调试：理解工具执行模式
• 分析：监控哪些工具使用得最多

教程概述

在本教程中，我们将创建一个带有工具执行回调的代理：

• 使用一个简单的计算器工具
• 监控工具执行的开始和结束
• 跟踪工具参数和结果
• 提供详细的工具使用可视化

项目结构

6_3_tool_execution_callbacks/
├── README.md              # This file
├── requirements.txt       # Dependencies
├── agent.py              # Agent with tool callbacks
└── app.py                # Streamlit interface
​

学习目标

完成本教程后，您将掌握：

• ✅ 工具执行前回调：如何监控工具执行开始
• ✅ 工具执行后回调：如何跟踪工具完成
• ✅ 工具上下文：如何访问工具和代理信息
• ✅ FunctionTool：如何正确地将工具与回调注册
• ✅ 回调集成：如何将回调集成到代理中

开始使用

设置

1. 安装依赖：pip install -r requirements.txt
2. Set up environment: Create .env with GOOGLE_API_KEY=your_key
3. Run the app: streamlit run app.py

测试代理

# Run the Streamlit app
streamlit run app.py

# Try these test messages:
- "Calculate 15 + 27"
- "What is 100 divided by 4?"
- "Multiply 8 by 12"
​

关键概念

1. 工具执行前回调

• 触发条件：当工具执行开始时
• 参数：tool, args, tool_context
• Use Cases: Log tool usage, validate parameters, record start

2. After Tool Callback

• Trigger: When tool execution completes
• Parameters: tool, args, tool_context, tool_response
• Use Cases: Log results, handle errors, provide feedback

3. Tool Context

• Agent Information: Access tool_context.agent_name
• State Management: Use tool_context.state for data sharing
• Tool Details: Access tool information via tool.name

测试示例

基本工具使用

User: "Calculate 15 + 27"

 Tool calculator_tool started
 Parameters: {'operation': 'add', 'a': 15.0, 'b': 27.0}
 Agent: tool_execution_demo_agent

✅ Tool calculator_tool completed
⏱️ Duration: 0.0012s
 Result: 15 + 27 = 42
​

错误处理

User: "What is 10 divided by 0?"

 Tool calculator_tool started
 Parameters: {'operation': 'divide', 'a': 10.0, 'b': 0.0}
 Agent: tool_execution_demo_agent

✅ Tool calculator_tool completed
⏱️ Duration: 0.0008s
 Result: Error: Division by zero
​

每个指标告诉您什么

工具执行前回调输出

• ** 工具名称**：正在执行的工具
• ** 参数**：传递给工具的输入参数
• ** 代理**：使用该工具的代理

工具执行后回调输出

• ✅ 完成状态：工具执行成功完成
• ⏱️ 耗时：工具执行所花费的时间
• ** 结果**：工具的输出或结果

重要实现注意事项

FunctionTool 要求

工具必须用 FunctionTool 包装，回调才能正常工作：

# ✅ Correct - Use FunctionTool
calculator_function_tool = FunctionTool(func=calculator_tool)
agent = LlmAgent(tools=[calculator_function_tool], ...)

# ❌ Incorrect - Raw function won't trigger callbacks
agent = LlmAgent(tools=[calculator_tool], ...)
​

回调签名

请使用正确的参数顺序来定义工具回调：

# ✅ Correct signatures
def before_tool_callback(tool: BaseTool, args: dict, tool_context: ToolContext):
    pass

def after_tool_callback(tool: BaseTool, args: dict, tool_context: ToolContext, tool_response: any):
    pass
​

事件循环完成

不要在 is_final_response() 后立即中断事件循环：

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

高级模式

多个工具

使用相同的回调注册多个工具：

def weather_tool(city: str) -> str:
    return f"Weather in {city}: Sunny, 25°C"

def calculator_tool(operation: str, a: float, b: float) -> str:
    # ... implementation

# Register multiple tools
weather_function_tool = FunctionTool(func=weather_tool)
calculator_function_tool = FunctionTool(func=calculator_tool)

agent = LlmAgent(
    name="multi_tool_agent",
    model="gemini-3-flash-preview",
    tools=[calculator_function_tool, weather_function_tool],
    before_tool_callback=before_tool_callback,
    after_tool_callback=after_tool_callback
)
​

参数校验

在 before_tool_callback 中实现校验：

def before_tool_callback(tool: BaseTool, args: dict, tool_context: ToolContext):
    tool_name = tool.name
    
    # Validate calculator tool parameters
    if tool_name == "calculator_tool":
        if "operation" not in args:
            print("⚠️ Warning: Missing operation parameter")
        if "a" not in args or "b" not in args:
            print("⚠️ Warning: Missing numeric parameters")
    
    print(f" Tool {tool_name} started")
    print(f" Parameters: {args}")
    return None
​

结果修改

在 after_tool_callback 中修改工具结果：

def after_tool_callback(tool: BaseTool, args: dict, tool_context: ToolContext, tool_response: any):
    tool_name = tool.name
    
    # Add context to calculator results
    if tool_name == "calculator_tool" and "result" in tool_response:
        operation = args.get("operation", "unknown")
        tool_response["context"] = f"Performed {operation} operation"
    
    print(f"✅ Tool {tool_name} completed")
    print(f" Result: {tool_response}")
    return tool_response  # Return modified response
​

下一步

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

• 高级工具模式 - 复杂的工具架构
• 自定义工具开发 - 构建自定义工具
• 工具集成 - 集成外部 API

更多资源

• Google ADK 工具回调
• 工具开发指南
• FunctionTool 文档

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