⚡ 函数工具

函数工具是您创建并集成到智能体中的自定义 Python 函数。这是为智能体添加特定功能时最灵活且最常用的方法。

您将学到的内容

• 函数工具的创建：构建自定义 Python 函数作为工具
• 工具注册：如何将函数注册到您的智能体中
• 参数处理：管理工具的输入和输出
• 错误处理：工具中稳健的错误管理
• 最佳实践：设计有效的函数工具模式

核心概念：函数工具

函数工具是具有特殊属性的Python 函数：

• 描述性文档字符串：帮助智能体理解何时使用它们
• 类型注解：清晰的输入和输出规范
• 返回字典：结构化、信息丰富的响应
• 错误处理：优雅的失败管理

主要优势

• ✅ 最大灵活性：可创建任何所需功能
• ✅ 易于集成：简单的 Python 函数
• ✅ 完全控制：对行为的完全掌控
• ✅ 调试方便：易于测试和调试

函数工具的要求

1. 描述性文档字符串

def calculate_compound_interest(principal: float, rate: float, years: int) -> dict:
    """
    Calculate compound interest for an investment.
    
    Use this function when users ask about investment growth,
    compound interest calculations, or future value of investments.
    
    Args:
        principal: Initial investment amount
        rate: Annual interest rate (as decimal, e.g., 0.05 for 5%)
        years: Number of years to compound
    
    Returns:
        Dictionary with calculation results and breakdown
    """
​

2. 类型注解

• 始终指定参数类型
• 包含返回值类型注解
• 使用合适的 Python 类型（str、int、float、dict、list）

3. 结构化返回值

return {
    "result": final_amount,
    "calculation_breakdown": {
        "principal": principal,
        "rate": rate,
        "years": years,
        "total_interest": total_interest
    },
    "status": "success"
}
​

4. 错误处理

try:
    # Tool logic here
    return {"result": result, "status": "success"}
except ValueError as e:
    return {"error": str(e), "status": "error"}
​

教程示例

本子示例包含两个实用实现：

计算器智能体

位置：./calculator_agent/

• Mathematical Operations: Basic arithmetic, compound interest, percentage calculations
• Unit Conversions: Temperature conversions (Celsius, Fahrenheit, Kelvin)
• Statistical Analysis: Mean, median, mode, standard deviation for data sets
• Financial Calculations: Investment growth, compound interest projections
• Number Utilities: Rounding, formatting, and mathematical expressions

Utility Agent

Location: ./utility_agent/

• 文本处理：单词计数、大小写转换、文本变换
• 数据提取：电子邮件和 URL 提取、词频分析
• 日期/时间操作：格式转换、日期差、年龄计算
• 数据实用工具：UUID 生成、文本哈希、Base64 编码/解码
• 验证工具：URL 验证、JSON 格式化与验证

项目结构

4_2_function_tools/
├── README.md                    # This file - function tools guide
├── requirements.txt             # Dependencies for function tools
├── .env.example                # Environment variables template (shared)
├── calculator_agent/           # Mathematical tools implementation
│   ├── __init__.py
│   ├── agent.py               # Calculator agent with custom tools
│   └── tools.py               # Mathematical function tools
└── utility_agent/              # Utility tools implementation
    ├── __init__.py
    ├── agent.py               # Utility agent with various tools
    └── tools.py               # Text processing, date/time, and data utilities
​

学习目标

完成本子示例后，您将掌握：

• ✅ 如何将自定义 Python 函数创建为工具
• ✅ 工具设计与文档的最佳实践
• ✅ 如何有效处理参数和返回值
• ✅ 错误处理与验证策略
• ✅ 何时使用函数工具而非其他方法

开始使用

1. 设置您的环境：

   cd 4_2_function_tools
   
   # Copy the environment template
   cp env.example .env
   
   # Edit .env and add your Google AI API key
   # Get your API key from: https://aistudio.google.com/
   ​

2. 安装依赖：

   # Install required packages
   pip install -r requirements.txt
   ​

3. 运行智能体：

   # Start the ADK web interface
   adk web
   
   # In the web interface, select:
   # - calculator_agent: For mathematical calculations and conversions
   # - utility_agent: For text processing, date/time, and data utilities
   ​

4. 尝试智能体：

   • 计算器智能体：“计算 200 的 15%”、“将 100°F 转换为摄氏度”、“查找 [1,2,3,4,5] 的统计信息”
   • 实用智能体：“统计这段文本中的单词数”、“格式化日期 2023-12-25”、“生成一个 UUID”

5. 创建您自己的工具：针对您的用例构建自定义工具

专业提示

• 每个工具只做一件事：每个函数应专精于一项任务
• 丰富的文档字符串：文档字符串对智能体的理解至关重要
• 验证输入：始终验证函数参数
• 返回字典：结构化返回值更易于使用
• 独立测试：先在智能体外单独测试工具

常见函数工具模式

1. 简单计算器模式

def add_numbers(a: float, b: float) -> dict:
    """Add two numbers together."""
    return {"result": a + b, "operation": "addition"}
​

2. 数据处理模式

def analyze_text(text: str) -> dict:
    """Analyze text for word count, sentiment, etc."""
    return {
        "word_count": len(text.split()),
        "character_count": len(text),
        "sentiment": "neutral"  # Placeholder
    }
​

3. API 集成模式

def get_weather(city: str) -> dict:
    """Get weather information for a city."""
    try:
        # API call logic here
        return {"temperature": 72, "condition": "sunny"}
    except Exception as e:
        return {"error": str(e), "status": "failed"}
​

4. 转换模式

def convert_temperature(temp: float, from_unit: str, to_unit: str) -> dict:
    """Convert temperature between units."""
    # Conversion logic
    return {
        "original": {"value": temp, "unit": from_unit},
        "converted": {"value": converted_temp, "unit": to_unit}
    }
​

重要提示

• 无默认参数：ADK 不支持默认参数
• 返回字典：始终返回结构化数据
• 错误处理：实施恰当的错误处理
• 文档：编写清晰、有用的文档字符串
• 测试：在添加到智能体前独立测试函数

常见用例

数学工具（计算器智能体）

• 基本算术运算与表达式
• 统计计算（均值、中位数、众数、标准差）
• 金融计算（复利、百分比）
• 单位转换（温度、度量）
• 数字格式化与四舍五入

文本处理工具（实用智能体）

• 单词与字符计数
• 大小写转换与文本变换
• 从文本中提取电子邮件与 URL
• 词频分析
• 字符串操作与格式化

日期/时间工具（实用智能体）

• 日期格式转换
• 年龄计算与日期差
• 时区处理
• 持续时间计算
• 日期解析与验证

数据实用工具（实用智能体）

• UUID 生成用于唯一标识符
• 文本哈希使用多种算法
• Base64 编码与解码
• URL 验证与解析
• JSON 格式化与验证

集成工具

• API 调用与外部服务集成
• 数据库查询与数据获取
• 文件操作与数据处理
• 自定义业务逻辑实现

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