AI Agent Tools — 面向 AI Agent 的 Python 工具库

📖 概述

本库提供一系列开箱即用的 Python 函数，供 AI Agent 执行各类任务，涵盖文件操作、文本分析、数据转换、内存管理及数据校验等场景。

⚡ 快速上手

安装

方式 1：从 GitHub 克隆

git clone https://github.com/cerbug45/ai-agent-tools.git
cd ai-agent-tools

方式 2：直接下载

wget https://raw.githubusercontent.com/cerbug45/ai-agent-tools/main/ai_agent_tools.py

方式 3：复制粘贴

将 ai_agent_tools.py 文件直接复制到您的项目目录中即可。

运行环境要求

• Python 3.7 或更高版本
• 无外部依赖（仅使用 Python 标准库）

🛠️ 可用工具

1. FileTools — 文件操作

用于读取、写入与管理文件的操作集合。

可用方法：

from ai_agent_tools import FileTools

# 读取文件
content = FileTools.read_file("path/to/file.txt")

# 写入文件
FileTools.write_file("path/to/file.txt", "Hello World!")

# 列出指定目录下的文件（可按扩展名过滤）
files = FileTools.list_files(".", extension=".py")

# 检查文件是否存在
exists = FileTools.file_exists("path/to/file.txt")

典型应用场景：

• 读取配置文件
• 保存 Agent 输出结果
• 枚举可用资源列表
• 在执行操作前检查文件是否存在

2. TextTools — 文本处理

从文本中提取信息并进行格式化处理。

可用方法：

from ai_agent_tools import TextTools

text = "Contact: john@example.com, phone: 0532 123 45 67"

# 提取邮箱地址
emails = TextTools.extract_emails(text)
# 输出: ['john@example.com']

# 提取 URL
urls = TextTools.extract_urls("Visit https://example.com")
# 输出: ['https://example.com']

# 提取电话号码
phones = TextTools.extract_phone_numbers(text)
# 输出: ['0532 123 45 67']

# 统计词数
count = TextTools.word_count("Hello world from AI")
# 输出: 4

# 文本摘要生成
summary = TextTools.summarize_text("Long text here...", max_length=50)

# 清理多余空白字符
clean = TextTools.clean_whitespace("Too   many    spaces")
# 输出: "Too many spaces"

典型应用场景：

• 从文档中提取联系人信息
• 清洗与标准化文本格式
• 生成文本摘要
• 从非结构化文本中抽取结构化数据

3. DataTools — 数据转换

支持多种数据格式之间的相互转换。

可用方法：

from ai_agent_tools import DataTools

# 将数据保存为 JSON 文件
data = {"name": "Alice", "age": 30}
DataTools.save_json(data, "output.json")

# 加载 JSON 文件
loaded_data = DataTools.load_json("output.json")

# 将 CSV 格式字符串转为字典列表
csv_text = """name,age,city
Alice,30,New York
Bob,25,London"""
data_list = DataTools.csv_to_dict(csv_text)
# 输出: [{'name': 'Alice', 'age': '30', 'city': 'New York'}, ...]

# 将字典列表转为 CSV 字符串
data = [
    {"name": "Alice", "age": 30},
    {"name": "Bob", "age": 25}
]
csv = DataTools.dict_to_csv(data)

典型应用场景：

• 持久化结构化数据
• 跨格式数据迁移与转换
• 解析 API 响应体
• 生成报表或导出数据

4. UtilityTools — 通用工具函数

常用辅助功能封装。

可用方法：

from ai_agent_tools import UtilityTools

# 获取当前时间戳
timestamp = UtilityTools.get_timestamp()
# 输出: "2026-02-15 14:30:25"

# 基于文本生成唯一 ID
id = UtilityTools.generate_id("user_john_doe")
# 输出: "a3f5b2c1"

# 计算百分比
percent = UtilityTools.calculate_percentage(25, 100)
# 输出: 25.0

# 安全除法（自动规避除零异常）
result = UtilityTools.safe_divide(10, 0, default=0.0)
# 输出: 0.0

典型应用场景：

• 事件打标（添加时间戳）
• 生成唯一标识符（如 session ID、记录 ID）
• 执行安全数学运算
• 数据分析中的中间计算

5. MemoryTools — 内存管理

在 Agent 执行过程中临时存储与检索数据。

可用方法：

from ai_agent_tools import MemoryTools

# 初始化内存实例
memory = MemoryTools()

# 存储键值对
memory.store("user_name", "Alice")
memory.store("session_id", "abc123")

# 检索值
name = memory.retrieve("user_name")
# 输出: "Alice"

# 列出所有键名
keys = memory.list_keys()
# 输出: ["user_name", "session_id"]

# 删除指定键
memory.delete("session_id")

# 清空全部内存
memory.clear()

典型应用场景：

• 维护多轮对话上下文
• 暂存中间计算结果
• 会话状态管理
• 缓存高频访问或耗时计算结果

6. ValidationTools — 数据校验

对多种类型的数据进行有效性验证。

可用方法：

from ai_agent_tools import ValidationTools

# 校验邮箱格式
is_valid = ValidationTools.is_valid_email("user@example.com")
# 输出: True

# 校验 URL 格式
is_valid = ValidationTools.is_valid_url("https://example.com")
# 输出: True

# 校验土耳其手机号格式（含空格分隔）
is_valid = ValidationTools.is_valid_phone("0532 123 45 67")
# 输出: True

典型应用场景：

• 用户输入合法性校验
• 数据质量检查（ETL 流程中）
• 表单提交前验证
• 预处理阶段的数据清洗与过滤

💡 完整使用示例

from ai_agent_tools import (
    FileTools, TextTools, DataTools, 
    UtilityTools, MemoryTools, ValidationTools
)

# 初始化会话内存
memory = MemoryTools()

# 读取输入文件
text = FileTools.read_file("contacts.txt")

# 提取关键信息
emails = TextTools.extract_emails(text)
phones = TextTools.extract_phone_numbers(text)

# 对提取结果进行校验
valid_emails = [e for e in emails if ValidationTools.is_valid_email(e)]
valid_phones = [p for p in phones if ValidationTools.is_valid_phone(p)]

# 构建结构化联系人数据
contacts = []
for i, (email, phone) in enumerate(zip(valid_emails, valid_phones)):
    contact = {
        "id": UtilityTools.generate_id(f"contact_{i}"),
        "email": email,
        "phone": phone,
        "timestamp": UtilityTools.get_timestamp()
    }
    contacts.append(contact)

# 保存结果至 JSON 文件
DataTools.save_json(contacts, "output/contacts.json")

# 将元信息存入内存
memory.store("total_contacts", len(contacts))
memory.store("last_processed", UtilityTools.get_timestamp())

print(f"Processed {len(contacts)} contacts")
print(f"Saved to: output/contacts.json")

🎯 最佳实践

1. 错误处理

务必对文件操作使用 try-except 包裹：

try:
    content = FileTools.read_file("data.txt")
    # 处理内容
except Exception as e:
    print(f"Error reading file: {e}")

2. 内存管理

不再需要时及时清空内存：

memory = MemoryTools()
# ... 使用内存 ...
memory.clear()  # 显式清理

3. 数据校验

始终在校验通过后再执行后续逻辑：

if ValidationTools.is_valid_email(email):
    # 处理邮箱
    pass
else:
    print(f"Invalid email: {email}")

4. 路径处理

推荐使用绝对路径，或确保当前工作目录正确：

import os

base_dir = os.path.dirname(__file__)
filepath = os.path.join(base_dir, "data", "file.txt")
content = FileTools.read_file(filepath)

🔧 高级用法

链式调用（Pipeline）

# 读取 → 处理 → 校验 → 保存 流水线
text = FileTools.read_file("input.txt")
cleaned = TextTools.clean_whitespace(text)
emails = TextTools.extract_emails(cleaned)
valid = [e for e in emails if ValidationTools.is_valid_email(e)]
DataTools.save_json({"emails": valid}, "output.json")

构建自定义工作流

class DataProcessor:
    def __init__(self):
        self.memory = MemoryTools()
        
    def process_document(self, filepath):
        # 读取
        text = FileTools.read_file(filepath)
        
        # 提取
        emails = TextTools.extract_emails(text)
        urls = TextTools.extract_urls(text)
        
        # 存储结果
        self.memory.store("emails", emails)
        self.memory.store("urls", urls)
        
        # 生成报告
        report = {
            "timestamp": UtilityTools.get_timestamp(),
            "file": filepath,
            "emails_found": len(emails),
            "urls_found": len(urls)
        }
        
        return report

📦 与 AI Agent 框架集成

示例：LangChain 集成

from langchain.tools import Tool
from ai_agent_tools import FileTools, TextTools

def create_file_reader_tool():
    return Tool(
        name="ReadFile",
        func=FileTools.read_file,
        description="Read contents of a file"
    )

def create_email_extractor_tool():
    return Tool(
        name="ExtractEmails",
        func=TextTools.extract_emails,
        description="Extract email addresses from text"
    )

tools = [create_file_reader_tool(), create_email_extractor_tool()]

示例：OpenAI Function Calling

tools = [
    {
        "type": "function",
        "function": {
            "name": "read_file",
            "description": "Read a file and return its contents",
            "parameters": {
                "type": "object",
                "properties": {
                    "filepath": {
                        "type": "string",
                        "description": "Path to the file"
                    }
                },
                "required": ["filepath"]
            }
        }
    }
]

# 在您的 Agent 主循环中
def execute_function(name, arguments):
    if name == "read_file":
        return FileTools.read_file(arguments["filepath"])

🧪 测试

运行内置测试套件：

python ai_agent_tools.py

预期输出：

=== AI Ajanları İçin Araçlar Kütüphanesi ===

1. Dosya Araçları:
   Okunan içerik: Merhaba AI Ajanı!

2. Metin Araçları:
   Bulunan emailler: ['ali@example.com']
   Bulunan telefonlar: ['0532 123 45 67']

3. Veri Araçları:
   CSV çıktısı:
   isim,yaş
   Ali,25
   Ayşe,30

...

✓ Tüm araçlar test edildi!

🤝 贡献指南

欢迎参与贡献！贡献流程如下：

1. Fork 本仓库
2. 创建特性分支：git checkout -b feature/new-tool
3. 提交更改：git commit -am 'Add new tool'
4. 推送分支：git push origin feature/new-tool
5. 提交 Pull Request

📝 许可证

本项目为开源项目，采用 MIT License 发布。

👤 作者

GitHub： @cerbug45

🐛 问题反馈与支持

发现 Bug 或需要帮助？请在 GitHub 提交 Issue： https://github.com/cerbug45/ai-agent-tools/issues

📚 补充资源

• Python 官方文档
• 正则表达式入门指南
• JSON 格式规范

🔄 版本历史

v1.0.0（2026-02-15）

• 初始发布
• 涵盖 6 类工具模块
• 提供 25+ 个实用函数
• 完整中文文档
• 附带完整测试套件

Happy Coding! 🚀