注册指南
655 字约 2 分钟
2025-02-04
本文提供详细的工具注册决策指南。
决策树
开始:我需要开发一个新工具
│
▼
┌─────────────────────────────────────┐
│ 问题1: 需要维护长连接或持久状态吗? │
│ │
│ - TCP/WebSocket 长连接 │
│ - 进程句柄 │
│ - VM/容器实例 │
│ - 数据库连接池 │
│ - 浏览器 Session │
└─────────────────────────────────────┘
│ │
是 否
│ │
▼ ▼
┌──────────────┐ ┌─────────────────────────┐
│ Backend 类 │ │ 问题2: 需要预加载资源吗? │
│ │ │ │
│ 继续下一步... │ │ - ML 模型 │
└──────────────┘ │ - 向量索引 │
│ │ - 大型配置文件 │
│ └─────────────────────────┘
│ │ │
│ 是 否
│ │ │
│ ▼ ▼
│ ┌──────────────┐ ┌──────────────────┐
│ │ Backend 类 │ │ @register_api_tool │
│ │ (共享资源型) │ │ (轻量级工具) │
│ └──────────────┘ └──────────────────┘
│
▼
┌───────────────────────────────────┐
│ 问题3: 资源是全局共享还是用户独立? │
└───────────────────────────────────┘
│ │
全局共享 用户独立
│ │
▼ ▼
┌─────────────────┐ ┌─────────────────┐
│ 实现 warmup() │ │ 实现 initialize()│
│ shutdown() │ │ cleanup() │
│ │ │ │
│ 例: RAG、模型 │ │ 例: VM、Bash │
└─────────────────┘ └─────────────────┘
│ │
└──────┬───────┘
▼
┌─────────────────────────────────────┐
│ 问题4: 是否同时需要两种资源? │
│ │
│ 例: 浏览器(共享进程 + 独立页面) │
└─────────────────────────────────────┘
│ │
是 否
│ │
▼ ▼
┌─────────────────┐ ┌─────────────────┐
│ 混合后端 │ │ 完成! │
│ 实现全部四个方法 │ │ │
└─────────────────┘ └─────────────────┘边界情况指南
| 场景 | 推荐选择 | 原因 |
|---|---|---|
| 需要鉴权的复杂 API Client | APITool | 鉴权是无状态的 |
| 带连接池的 API Client | Backend (warmup) | 连接池需要生命周期管理 |
| 需要 Session Cookie 的 API | Backend (initialize) | Session 状态跨请求维护 |
| 简单的 HTTP API 调用 | APITool | 请求-响应模式 |
| 需要重试逻辑的 API | APITool | 重试是无状态操作 |
| 需要限流/熔断的 API | Backend (warmup) | 限流器需要全局状态 |
实现方式对照表
| 类型 | 基类 | Session | 生命周期方法 | 工具命名 | 示例 |
|---|---|---|---|---|---|
| 轻量级 API 工具 | 无 | ❌ | 无 | action | WebSearch |
| 共享资源后端 | Backend | ❌ | warmup(), shutdown() | resource:action | RAG |
| Session 资源后端 | Backend | ✅ | initialize(), cleanup() | resource:action | VM |
| 混合后端 | Backend | ✅ | 全部四个 | resource:action | Browser |
常见问题
Q: 什么时候用 APITool?
当你的工具:
- 调用外部 HTTP API
- 不需要保持状态
- 不需要预加载资源
- 每次调用相互独立
Q: 什么时候用 Backend?
当你的工具:
- 需要预加载模型或资源
- 需要维护长连接
- 需要为每个用户分配独立资源
- 需要管理资源生命周期
Q: 什么时候实现 warmup()?
当你需要:
- 加载 ML 模型
- 建立连接池
- 初始化全局缓存
- 启动后台进程
Q: 什么时候实现 initialize()?
当你需要:
- 为每个用户分配独立资源
- 维护用户级别的状态
- 隔离用户之间的操作
CI/CD 验证
建议在 CI/CD 中验证配置:
python -m sandbox validate --config configs/profiles/production.json --strict验证内容:
| 检查项 | 说明 |
|---|---|
backend_class 路径 | 验证类路径可导入 |
| @tool 装饰器 | 验证工具方法存在 |
| API 工具注册 | 验证 config_key 匹配 |
| 配置完整性 | 验证必需配置项 |