toolhunch — LLM Agent 工具搜索引擎：BM25 + Embeddings 候选 + System-1 决策模型选最优

技能简介

toolhunch 解决 LLM Agent 工具爆炸的硬伤：当工具目录超过 40–101 个时，把全部 tool definition 喂给模型会让提示词臃肿、成本飙升、命中率下降，甚至触发 OpenAI 200 函数上限拒绝。toolhunch 把「工具搜索 + 快速决策」拆成两条流水线：先用 BM25 + 嵌入向量召回到 20 个候选，再让 System-1 决策模型（如 TypeSafe Jev、Cloudflare Clef、Strands Decider、rizzo-flow、Laya 或支持 logprobs 的 LLM）选出最合适的一个，并允许说「none」。在 ToolRet 基准（44,453 工具）上，GPT-6 Luna agent 跑全目录可达 80% 命中率，跑 20 候选方案成本降至 $0.18 / 千次。框架无关，可集成到 Pydantic AI / LangChain / 自研 Agent 中。

核心能力

• 混合检索：BM25 关键词 + 嵌入向量语义检索，结果用 reciprocal rank fusion 融合
• 多模型决策：内置 TypeSafe Jev、Cloudflare Clef、Strands Decider、rizzo-flow、Laya 五种 System-1 决策模型，可热切换
• 「none」选项：决策模型可拒绝（catalog 无合适工具），避免幻觉触发错误工具
• 完整 benchmark：基于 ToolRet（ACL 2025 Findings，44,453 工具）的实测数据，含召回率 / 成本 / 延迟三维指标
• 小目录也适用：40–101 工具规模下，全目录与搜索方案命中率持平（80% vs 78%），但搜索可降本 60%
• 大目录解锁：ToolRet 44,453 工具规模下全目录不可行，搜索成为唯一实用方案
• LLM logprobs 集成：支持用 token 概率排序替代独立决策模型
• 框架无关核心：核心库与 Agent 框架解耦，集成层决定如何把工具送达 Agent

安装配置

# 基础安装
pip install toolhunch

# 安装 Pydantic AI 集成（推荐）
pip install toolhunch pydantic-ai

环境变量：TOOLHUNCH_DECIDER（默认 clef，可选 jev / clef-flash / strands-decider / rizzo-flow / laya / llm-logprobs）、OPENAI_API_KEY（用 LLM 决策时必填）、CLEF_API_URL（用 Cloudflare Workers AI 时）。Python 3.12+。

使用步骤

1. 准备工具目录（tool definition 列表，含 name / description / parameters schema）
2. 创建 toolhunch 检索器，绑定决策模型
3. Agent 收到用户请求 → 检索器召回到 20 候选 → 决策模型选出最合适的 1 个
4. 如决策返回「none」，Agent 走 fallback 路径（如直接回答或问用户澄清）
5. 监控决策日志：哪些请求被频繁拒绝、哪些工具被高频误召，按需调整 catalog

适用场景

• MCP 服务器聚合：单 Agent 同时接入多个 MCP 服务器时，工具数可能上百
• 企业内部工具平台：HR Agent / 数据 Agent 接入 50+ 内部 API 时
• RAG + 多工具混合检索：先检索文档再选工具的统一调度
• 多 Agent 协同：不同 Agent 共享工具目录但需差异化召回
• 成本敏感场景：高频调用场景下，搜索可降低 60% input token 成本
• 大工具目录测试：ToolRet 4.4 万工具规模的评估与对比

适用人群

• Agent 框架开发者：解决工具目录膨胀导致的提示词超限问题
• 企业 IT 平台架构师：设计跨部门可复用的工具市场
• Prompt Cache 优化工程师：固定工具列表会破缓存，搜索可保持 cache 命中率
• LLM 应用研究员：研究 System-1 / System-2 决策模型在工具选择上的差异
• AI 产品经理：评估工具检索对成本 / 延迟 / 准确率的影响

工作原理

toolhunch 流水线为 request → 搜索（BM25 + embeddings → RRF）→ 20 候选 → 决策模型 → 1 个工具 / none。搜索阶段使用 BM25 做关键词召回 + 嵌入向量做语义召回，结果用 reciprocal rank fusion 融合排序。决策阶段是 System-1 快速判断（区别于 System-2 慢思考），可选用 TypeSafe Jev（小模型、0.32 s 决策）、Cloudflare Clef（Workers AI，1.43 s）、Strands Decider 2B（本地 0.12 s）或 LLM logprobs。集成层决定如何把工具送达 Agent：可在 20 候选中选最优、也可对全目录做决策（catalog 小时）。ToolRet benchmark 在 44,453 工具上验证：Jev 0.32 s / 决策成本 ~$0.0001，是 production 友好方案。

官方链接

• PyPI：https://pypi.org/project/toolhunch/
• GitHub：https://github.com/dfm88/toolhunch
• Benchmark 文档：https://github.com/dfm88/toolhunch/blob/main/docs/experiments/toolret.md
• ToolRet 论文：https://arxiv.org/abs/2503.01763
• TypeSafe Jev：https://docs.typesafe.ai
• Cloudflare Clef：https://developers.cloudflare.com/workers-ai/models/clef/
• License：MIT