搜索怎么接厂商:一个工具名,还是每家有每家的工具
模块:运行引擎 · 工具(doc/22 +
tmp/22-网络搜索-切新api)|状态:已落地(2026-10-15 首版,2026-10-18 二稿换接口并改始终落盘)|证据:doc/22-网络搜索.md、internal/runengine/websearch.go
1. 场景与病灶
用户让 tako 查一句今天才能知道的公开事实,并在回答里给出处链接。
链路走到 researcher 就断了:agents/researcher.md 写着「当前没有联网检索能力」,父池里也没有搜索工具。它只能在终稿里写「未能查证」。公开网页上那句话,这次回答里不会出现。
要补的一环很小:researcher 在自己的消息里调用一个普通函数,程序去搜,把标题、链接、摘要写进这次 tool_result。researcher 据此写报告。主线程的上下文里仍然只有这份报告,不出现搜索原文。
真正难的不是「发一个 HTTP」,而是一个工具名怎么覆盖多家厂商:tako 的模型可以按租户、按子代理换成不同的 ref(deepseek/deepseek-flash、tencent-token-plan/deepseek-v4-flash……)。搜索如果不能跟着这次对话实际打到的厂商走,换个模型搜索就坏。
2. 候选与代价
| 候选 | 做法 | 好处 | 代价 |
|---|---|---|---|
| A 厂商工具类型挂在聊天请求上 | 请求 tools 里写 {"type":"web_search"},厂商服务器自己搜 |
零本地实现 | DeepSeek 的 Responses API 文档把这个类型标成忽略:请求能发出去、搜索不发生、模型仍可能用记忆回答。而且 tako 的验收要看 name=web_search 的帧——厂商在服务器里搜完写进回复时,这对帧不会出现 |
B 一律打 Moonshot POST /v1/tools/search(doc/17 §5 原建议) |
不论聊天模型是谁,都打同一家按次接口 | 与当轮模型无关,换 ref 不会把搜索弄丢 | 把搜索绑死在一家身上;后来的决定是各家模型自己的搜索都放进同一个工具,不先绑死 |
| C 两个工具名让模型挑 | searchfree_search 和「DeepSeek 搜索」都注册 |
听起来灵活 | 两个名字都在时,模型会两个都调,或者挑听起来更强的那个;对方忽略内置搜索时,它还会用记忆写一份看起来查过的报告 |
| D 单一工具名 + 内部按厂商选实现(选定) | 工具名只有 web_search、参数只有 query;各家的搜索是函数内部的一行实现 |
模型看不见「厂商差异」,不会挑错;换 ref 时搜索跟着走 | 各家实现要分别手打验证;每次加一家要加一个函数 |
选 D。判断键是这次对话实际打到的厂商 id——生效 ref 里斜线前面那一段。
3. 厂商 id 从哪来(不要读 ADK 内部状态)
工具执行时要知道「谁在调用」。父池这一份函数主代理和 researcher 共用;researcher 的规格若写了 model:,两边的 ref 不同。用装配时写死的主 ref 会搜错端点。
候选:读 eino 的 react state AgentName。不能用——它对主代理的值是 "yktako" 而不是空字符串(空串 = 主代理只是帧事件层的约定),且那是 compose 图执行期的内部结构,eino 只为准出兼容性导出,工具读了就是焊死在别人的内部表示上。
改法是一个只干一件事的小 middleware:BeforeAgent 返回 context.WithValue(ctx, key, 名字)——eino 把这个 ctx 流进该 agent 的整张图执行,所以它触发的工具调用都读得到。主代理挂写 "" 的,子代理在装配处挂写规格名的。
工具执行时读标记:
- 标记缺失 → 不猜主 ref,Go error「
web_search 不知道当前模型」。猜主 ref 的后果是子代理换了模型仍去打主模型的搜索端点,失败了还像是那一家的搜索坏了。 - 标记在 → 用本 run 已放在 ctx 里的
agentModelTable按名取生效 ref,严格读(不走查不到回落 root 的退路——回落只会在表坏时把子代理的搜索静默打去主模型厂商)。
4. DeepSeek 那一行:两次翻转
| 版本 | 做法 | 为什么被换 |
|---|---|---|
| 一稿(2026-10-15) | Anthropic 兼容端点 + 服务端 web_search_20250305 + 模型按 citations 写 JSON 摘要 |
活体发现 10/10 全是「无摘要」:DeepSeek 的兼容层把 citations 标记为 Ignored,原始响应里连该键都没有。同日用户拍「先 fix 现在的」「不是换哦」——在现有 Messages 路上让模型搜完只回 [{"url","summary"}] JSON |
| 二稿(2026-10-18 晚) | 直打 POST https://api.deepseek.com/v1/tools/search,不经过模型 |
用户翻案「换成 DeepSeek 新 search api」——同日「不是换哦」裁定作废。新接口每条自带 summary(页面原文抽取),实测 0.43s(旧路 5.15s)、$0.75/千次、5 QPS。旧 Messages 路删除不兼容 |
关键差别:摘要从「模型转述」(依赖模型行为和 citations)换成「页面原文自带」——不依赖任何模型行为,快 10 倍,代价是摘要可读性从均匀成段的「读书笔记」变成极差 38 倍的「复印片段」(65–2492 字)。
请求细节:{"query":"<query>","need_content":false};只取 title/url/summary;无 url 的项丢掉、url 去重;results 空或去重后无 url → 这次搜索失败,走兜底。60 秒上限只兜「ctx 没被取消但厂商不回」;run ctx 取消时 HTTP 自动一起停。
5. 结果放哪:结果全文落盘,只回一段描述
| 候选 | 做法 | 好处 | 代价 |
|---|---|---|---|
| A 结果内联进 tool_result | 把 10 条标题+摘要全文返回 | 一次调用就够 | 一次搜索几千 token 灌进上下文;摘要越长越糟 |
| B 超上限才落盘(一稿) | 字节上限内内联,超了才写文件 | 小结果不走盘 | 模型看到两种形状;记忆/折叠链要处理两套 |
| C 始终落盘 + 只回描述(选定,2026-10-18) | 全文写 <workspace>/.tako/search/<runId>_<n>.md,工具返回条数、路径、token 数 |
形状恒定;上下文零负担;8192/800 的上限不再需要 | 模型要多一步 read_file 才能看内容 |
选 C。file_effect 从 none 改成 write——文件名是程序命名的、一次一写、永不覆盖,与 search_history 截断落盘同性质(提取程序只扫调用参数,参数里只有 query 没有 path,不靠猜 query 字符串记账)。
描述段每个成分都有用途:条数让模型判断有没有命中;token 数给「读不读」提供代价感(数字来自引擎折叠链的同一份 TokenCounter,两本账不打架;counter 为 nil 时不报,宁缺不发明「字节÷4」);路径指到落盘文件。
落盘写失败或旁路调用没有 noteBox 时,降级为「结果仅本次可见(未能写入文件)」——模型必须知道内容去哪了。
6. 同族小裁定
| 小问题 | 裁定 | 代价 / 备注 |
|---|---|---|
| 工具名 | 只有 web_search,参数只有必填 query |
不加第二个名字;以后加一家只是表里加一个函数 |
| 查询上限 | 超 128 字截到 128,不报错 | 接口收 1–128 字、超了整次 400;检索词截断无信息损失争议,报错只会白烧一次兜底 |
| 空查询 | 不发 HTTP,Go error「查询是空的」 | 由 wrapToolErrors 包成「错误:」开头 |
| 兜底 searchfree | 没有厂商实现 / 密钥缺失 / 厂商失败时打 https://searchfree.site/api/search |
它是脚手架;转正不在本篇。查询原文会发到这个站点,站点不稳定(2026-10-18 探针 RemoteDisconnected) |
| 两处都失败 | Go error 串联两句原因,模型看见「错误:」,run 仍 complete | 不把半截响应当结果 |
| 失败原因写法 | 只有 HTTP 状态或一句短错误 | 不贴响应正文、不贴密钥 |
| 结果为空 | 成功但去重后一条链接都没有 = 失败 | 不把空结果交给模型 |
| researcher 怎么拿到它 | 进父池;researcher 用 exclude_tools(只排 bash)继承,有效名单含 web_search |
TestShippedAgentSpecToolGuards 金样钉住——有人把 web_search 写进排除项,go test 就红 |
| 要不要再包成子代理 | 不包 | 包成子代理的话主线程收到的是搜索器写的综述,综述把标题和链接吞掉,帧上的 name 也不再是 web_search |
fetch_url |
本篇不做 | 抓整页是折叠之前最容易撑满窗口的动作 |
| 不接的厂商 | Moonshot、智谱、Brave、Tavily、Google | 以后加一家:表里加函数,先用那家密钥手打一次,响应里要有 http;打不通的不登记 |
7. 证据
方案:doc/22-网络搜索.md §2(三种接法对照)§3(工具契约 + 始终落盘装配)§4(按厂商选择 + ctx 标记)§5(deepseek 行,2026-10-18 晚整节重写)§6(searchfree 兜底)§7(researcher 规格)§8(不做清单)。
台账:tmp/22-网络搜索/(首版)、tmp/22-网络搜索-切新api/(二稿)。旧 Messages 路的台账 tmp/22-网络搜索-摘要修复/ 已于 2026-10-21 清理。
代码符号:
| 位置 | 是什么 |
|---|---|
internal/runengine/websearch.go:29 |
callerNameKey:ctx 标记键 |
internal/runengine/websearch.go:43 |
callerStampMiddleware:BeforeAgent 写调用方名字 |
internal/runengine/websearch.go:54 |
webSearchDesc:工具 schema 说明 |
internal/runengine/websearch.go:67 |
newWebSearchTool |
internal/runengine/websearch.go:73 |
webSearchFn:按厂商选实现 + 兜底链 |
internal/runengine/websearch.go:151 |
deepseekSearch:直打 /v1/tools/search |
internal/runengine/websearch.go:193 |
searchfreeSearch:兜底 |
internal/runengine/websearch.go:264 |
renderSearchFile:落盘文件格式 |
internal/runengine/websearch.go:281 |
describeSearchResult:描述段 |
复核命令:
cd yk-tako-eino
grep -n "tools/search\|searchfree.site\|callerStampMiddleware" internal/runengine/websearch.go
grep -n "web_search" internal/runengine/agents_test.go
grep -n "web_search" agents/researcher.md活体验收(2026-10-15 首版,2026-10-18 二稿):A1 手打两家端点(DeepSeek web_search_tool_result 10 条含 http);二稿手打 /v1/tools/search count=10 0.43 秒返回 10 条、每条带 snippet/summary;同 query 摘要 619–796 字节、terminal complete。
8. 现状
- 仍有效:单一工具名 + 厂商 id 选择;ctx 标记而非 ADK 内部状态;deepseek 直打按次接口;始终落盘 + 描述段;searchfree 兜底;researcher 继承。
- 已翻转:一稿的「Messages + 服务端 web_search + 模型写 JSON 摘要」整条删除(2026-10-18 晚);「超上限才落盘」被「始终落盘」取代;8192 与 800 字上限对
web_search作废。 - 已知缺陷:searchfree 兜底仍是脚手架、未转正;2026-10-18 探针该站不可用。
- 同族问题:researcher 的工具边界 → 子代理规格与工具边界;落盘文件怎么被记住 → 折叠线用什么数;会话内原文检索 → 历史查找用什么索引。