pydantic-ai-toolbox
wachawo/pydantic-ai-toolbox加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
微信扫码咨询客服
POMOAI — 让开源 AI 即刻运行
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
写一个能回答问题的 AI Agent 很简单——几行代码，调用大模型 API，就能跑起来。但真正做产品时，你会发现 Agent 只是个"大脑"，它还需要"手脚"：读文件、执行 SQL、做数据分析、记住对话上下文、检索本地文档。
第一次，你手写了一个文件读取的工具函数。第二次，又手写了一个 SQL 查询包装器。第三次、第四次……每个项目都在重复同样的脚手架代码。当"工具债"积累到一定程度，你突然意识到：我是在做 AI 应用，还是在做工具制造工厂？
pydantic-ai-toolbox 就是来解决这个问题的。作者 wachawo 在用 pydantic-ai 做了多个项目后，发现每个项目都在重复造同样的轮子，于是把文件操作、SQL 查询、数据分析、对话记忆、RAG 检索这五类最常用的工具函数打包成了一套标准化的工具集，贡献给社区。
这是一个专为 pydantic-ai 框架设计的工具集扩展库。pydantic-ai 是 Pydantic 团队推出的 AI Agent 开发框架，以"像写普通 Python 代码一样写 AI Agent"为理念，提供了类型安全的工具调用机制。而 pydantic-ai-toolbox 则补全了 Agent 在真实场景中必需的外部能力。
项目当前处于 Beta 阶段（版本 0.0.1），已发布到 PyPI，支持 pip 一键安装。截至分析时，GitHub 获得 2 颗星、10 个主题标签（topics），包括 pydantic-ai、llm-agents、mcp、rag 等核心关键词。
项目提供五个独立且可组合的工具集：
让 AI Agent 在指定目录范围内读写文件，支持创建、读取、追加、删除、目录创建、文件信息查询（stat）和 glob 模式匹配。内置路径穿越防护，Agent 无法访问 sandbox root 以外的目录；同时支持只读模式，防止误操作导致数据损坏。
基于 SQLAlchemy 的数据库查询工具集，支持 INSERT、UPDATE、SELECT 等操作。可以让 Agent 用自然语言查询数据库，例如"找出过去一周销售额超过 1 万的用户"，Agent 自动转换为 SQL 执行并返回结果。连接字符串通过 DSN 参数注入，支持 PostgreSQL、MySQL、SQLite 等主流数据库。
封装了 pandas 的常用操作：CSV 加载、按条件过滤、分组聚合、统计计算等。不需要 Agent 写 Python 代码，直接说"统计这个 CSV 中每个月的平均气温"，工具集自动调用 pandas API 完成计算返回结果。
为 Agent 提供跨轮次的上下文记忆能力。将对话中提取的关键信息持久化存储在 JSON 文件中，下一次对话时可以自动召回历史事实，Agent 不再是"金鱼记忆"。适合需要多轮交互的客服、助手类产品。
将本地文档（通过 embedder 向量化）建立向量索引，支持语义检索。Agent 收到问题时，先从本地知识库中找到相关片段作为上下文，再让大模型基于真实文档回答，有效降低幻觉。
所有工具集都遵循 pydantic-ai 的 FunctionToolset 接口规范，可以直接作为 toolsets 参数传入 Agent，一行配置全部搞定：
from pydantic_ai import Agent
from pydantic_ai_toolbox import (
FilesystemToolset, SQLToolset, PandasToolset, MemoryToolset, RAGToolset,
)
agent = Agent(
"openai:gpt-4o-mini",
toolsets=[
FilesystemToolset(root="./workspace", read_only=False),
SQLToolset(dsn="postgresql://user:pass@localhost/app"),
PandasToolset(),
MemoryToolset(storage_path="./memory.json"),
RAGToolset(embedder=my_embedder),
],
system_prompt="你是一个数据助手。",
)
result = agent.run_sync("读取 workspace 中的 README 并总结")
代码结构非常清晰：
pydantic_ai_toolbox/
__init__.py # 对外导出所有 Toolset
base.py # 基类 + @tool 装饰器
toolsets/
filesystem.py # 文件系统工具集
sql.py # SQL 工具集
pandas.py # 数据分析工具集
memory.py # 记忆工具集
rag.py # RAG 工具集
基类 BaseToolset 继承自 pydantic-ai 的 FunctionToolset，通过 @tool 装饰器将类方法注册为 Agent 可调用的工具函数。这种设计使得每个工具集既可以独立运行（单独测试），又可以无缝插入 Agent 上下文——真正做到了"零侵入"。
代码质量较高：有完整的 pytest 测试套件（覆盖率目标 80%）、pyright 静态类型检查、mypy 类型检查、ruff 代码风格检查、pre-commit 自动化钩子。多 Python 版本（3.10~3.13）兼容，通过 pyproject.toml 声明依赖。
这是纯 Python 工具库，不需要 GPU，不需要 Docker，不需要复杂配置。只要有一台安装了 Python 3.10+ 的机器，pip install pydantic-ai-toolbox 即可完成安装。基础安装只依赖 pydantic-ai-slim（stdlib），其他功能（SQL、pandas、RAG）通过可选依赖按需安装：
pip install "pydantic-ai-toolbox[sql]" # SQLAlchemy
pip install "pydantic-ai-toolbox[pandas]" # pandas + pyarrow
pip install "pydantic-ai-toolbox[rag]" # numpy
pip install "pydantic-ai-toolbox[all]" # 全量安装
可选依赖相互独立，按需安装，不会强制拉入不需要的包。
作为一个新发布的 Beta 项目，pydantic-ai-toolbox 也存在一些需要注意的问题：
1. 版本尚早，生产环境需谨慎 当前版本 0.0.1，开发者明确标注"Development Status :: 4 - Beta"。API 和行为可能在后续版本中发生变化，生产环境使用前建议锁定版本号，并关注 CHANGELOG。
2. 不支持原生 Web UI 项目定位是工具库而非完整应用，没有 Gradio/Streamlit 等 Web 界面。如果需要让非技术用户通过浏览器与 Agent 交互，需要自行包装。
3. 依赖 pydantic-ai 本身 这是一个扩展库而非独立框架，必须配合 pydantic-ai 使用。如果你的 Agent 框架不是 pydantic-ai，这个工具集无法直接使用。
4. RAG 工具集需要自行处理 Embedding RAGToolset 只负责向量检索，需要使用者自己配置 embedder。对于没有本地 Embedding 模型或不想管理第三方 API 的团队，增加了一定接入成本。
随着 pydantic-ai 社区的快速发展（GitHub 已有数万星），围绕它的生态工具正在快速丰富。pydantic-ai-toolbox 代表了一种趋势：从"造轮子"到"用轮子"——开发者不再需要为每个项目手写文件读取、SQL 查询代码，而是直接复用经过测试的工具集。
这种"工具集市场"的模式，与 LangChain 的 Tools 生态类似，但更轻量、更符合 Python 的习惯。如果 pydantic-ai 继续保持增长势头，这类工具集将成为 AI 应用开发的基础设施组件。
pydantic-ai-toolbox 是一个针对 pydantic-ai 框架的实用工具集扩展，提供了文件操作、数据库查询、数据分析、对话记忆和 RAG 检索五类开箱即用的能力。代码质量规范，API 设计简洁，安装部署极简，适合正在使用或计划使用 pydantic-ai 构建 AI 应用的开发者。对于只需要基础 stdlib 功能的用户，pip install pydantic-ai-toolbox 两分钟即可为 Agent 赋能完整工具能力。
适合人群： 使用 pydantic-ai 构建 AI Agent、需要快速接入文件系统/SQL/数据分析/RAG 能力的 Python 开发者。
不适合： 不使用 pydantic-ai 的用户、需要 Web UI 界面的产品团队、对稳定性要求极高的生产系统（Beta 版本）。