参考文档

本节提供了有关在ToolUniverse中进行工具开发的详细参考信息。

架构

了解 ToolUniverse 的内部架构有助于您构建更优质的工具，并更高效地与系统集成。

我想比较工具类型： → 请查看 Contributing to ToolUniverse 中的工具类型比较表

工具比较

了解本地工具与远程工具之间的差异，有助于您选择适合需求的正确方法。

主要差异：

方面 | 本地工具 | 远程工具 |

|--------|————-|--------------| | 性能 | 高（无网络开销） | 较低（存在网络延迟） | | 开发 | 简单的 Python 类 | MCP 服务器或 API 封装 | | 部署 | ToolUniverse 的一部分 | 独立服务器 | | 可扩展性 | 受进程限制 | 高度可扩展 | | 集成 | 完全访问 ToolUniverse | 仅限 MCP/API | | 贡献 | 需要修改 __init__.py | 无需代码修改 |

何时使用本地工具： - 数据处理与分析 - 文件操作工具 - 简单的 API 封装程序 - 需要完整 ToolUniverse 集成的工具

何时使用远程工具： - 外部服务集成 - 高强度计算任务 - 微服务架构 - 不同编程语言的工具

架构详情

ToolUniverse 核心组件： - 工具注册表：管理工具的发现和注册 - 执行引擎：处理工具执行和错误管理 - 配置系统：管理工具参数和设置 - MCP 集成：通过 MCP 协议连接远程工具

工具生命周期： 1. 注册：工具在注册表中进行注册 2. 发现：ToolUniverse 发现可用的工具 3. 配置：工具加载其配置 4. 执行：工具根据参数被调用 5. 响应：结果返回给调用方

错误处理： - 多层次的输入验证 - 优雅的错误恢复 - 全面的错误报告 - 远程工具的超时管理

最佳实践

本地工具： - 保持工具专注且单一用途 - 使用适当的错误处理 - 实现输入验证 - 添加全面的测试 - 清晰地记录所有参数

远程工具： - 实施适当的身份验证 - 使用断路器提高系统弹性 - 为瞬态故障添加重试逻辑 - 监控性能和错误 - 提供清晰的部署文档

通用规则： - 遵循命名规范 - 使用具有描述性的参数名称 - 提供清晰的错误信息 - 包括使用示例 - 使用真实数据进行测试

故障排除

常见问题：

本地工具： - 工具未找到：检查注册和导入 - 参数错误：验证 JSON 模式 - 执行失败：检查 BaseTool 继承 - 导入错误：验证模块结构

远程工具： - 连接错误：检查服务器URL和网络 - 身份验证失败：验证凭据 - 超时问题：检查服务器性能 - 发现问题：验证MCP服务器状态

常规： - 配置错误：检查 JSON 语法 - 权限问题：验证文件访问权限 - 版本冲突：检查依赖项 - 性能问题：分析并优化

资源

下一步

准备好深入探索了吗？请选择您的重点：

小技巧

参考优先：了解工具类型的架构和差异将帮助您更好地决定针对特定需求采用哪种方法。