本文是 V-77「web_fetch 正文提取加固 + 搜索失败优雅降级」的配套配置手册,与builtin.py中_search_*/apply_search_config互补:代码讲「能做什么」,本文讲「拿到TrueAGT后,怎么把它用得更稳」。 设计定位回顾:联网搜索是工具调用(web_search/web_fetch),不是后台服务——agent 在需要实时信息时按调用付费式触发,不预抓、不轮询、不持久化到向量库(持久化是「知识库」的事,详见《设计方案》(配套设计说明)对应章节)。
本软件的联网搜索走 多引擎回退,默认首选 Bing(HTML 抓取,无需 Key),依次回退 Baidu → DuckDuckGo。当你希望摆脱「频繁超时、HTML 被反爬」时,三条路线任选其一:
| 路线 | 适用场景 | 需要你提供 | 抗反爬 | 成本 |
|---|---|---|---|---|
| A. HTML 抓取(默认) | 内网演示、低频查询、不愿暴露 Key | 无 | 弱(依赖搜索引擎 HTML 端稳定性) | 0 |
| B-1. SerpAPI(Google) | 要 Google 排序结果、要新闻/学术混合 | SerpAPI Key | 强(官方 JSON API) | 按调用计费,约 50 次/$5 起 |
| B-2. Bing Web Search API | 已有 Azure 订阅、企业合规优先 | Azure Bing Key + 终结点可选 | 强(官方 JSON API) | Azure 按量计费(含 1000 次/月 入门额度) |
| C. SearXNG 自托管 | 拒绝所有第三方 API、纯内网、信审要求"数据不出域" | 自建 SearXNG 实例 URL | 中(取决于上游引擎) | 服务器 + 运维 |
⚠️ 最关键的边界:
web_fetch 已能识别并显式提示。下面分「路线选型」「TrueAGT侧配置」「验证」「排错」「安全」五部分讲清。
config.json)搜索配置位于 config.json 的顶层 search 段。修改后重启 web.py 生效(启动期加载,不走热更新;但 web.py 路由 POST /api/search/config 提供运行期热切换,热切换只改内存不落盘,便于临时切换对比)。
{
"search": {
"provider": "bing",
"url": "",
"api_key": ""
}
}
provider 可选 bing(默认)/ baidu / duckduckgo。三者都会自动作为回退链成员(见 §3.5)。url 留空 = 用内置默认地址;非空 = 覆盖 HTML 抓取端点(须保持相同的页面结构,否则解析失败)。api_key。{
"search": {
"provider": "serpapi",
"api_key": "你的 SerpAPI Key(在 https://serpapi.com/ 控制台获取)",
"url": ""
}
}
provider 设为 serpapi 启用 Google JSON API(直连、抗反爬)。api_key 必填。未填时 _search_serpapi 会返回明确 [搜索失败] 未配置 search.api_key。url 留空(SerpAPI 端点固定为 https://serpapi.com/search.json,url 字段不作用于 SerpAPI)。{
"search": {
"provider": "bingapi",
"api_key": "你的 Azure 订阅密钥(Ocp-Apim-Subscription-Key)",
"url": ""
}
}
provider 设为 bingapi 启用 Azure Bing Web Search v7。api_key 必填,作为 Ocp-Apim-Subscription-Key 请求头。https://api.bing.microsoft.com/v7.0/search。如果你创建的是非默认区域资源(如 https://api.bing.microsoft.com/v7.0/search?... 对应 global,或自定义终结点),目前需要在 Azure 控制台用同一终结点——TrueAGT暂未暴露 region 自定义,路线 B-2 在非默认终结点下需要定制实现,可反馈给我们评估。url 留空(同 SerpAPI,url 不作用于 API 类 provider)。{
"search": {
"provider": "searxng",
"url": "https://searxng.example.com",
"api_key": ""
}
}
provider 设为 searxng。url 必填,填自建实例地址(不要带尾斜杠,代码会 rstrip("/") 但写规范更好)。api_key 留空(SearXNG JSON 端点匿名可用,除非你启用了鉴权插件)。TrueAGT搜索失败时会自动回退:
searxng:searxng 失败 → 回退到全部 HTML 引擎。整体受 22 秒总预算约束(_SEARCH_TOTAL_BUDGET),任一引擎期间超时即停,避免一次对话被搜索拖死。
config.json 已在 .gitignore 中,但仍建议通过环境变量注入 Key,便于:
config.json 在多机部署时无需差异化管理。TrueAGT当前不解析${ENV} 占位符(避免引入模板引擎依赖),但 web.py 提供 POST /api/search/config 路由支持运行期写入;亦可写一个启动包装脚本:
# /opt/trueagt/start.sh
export TRUE_AGT_SERPER_KEY="$(cat /run/secrets/serper)"
TrueAGT.exe --config config.json
# 在 config.json 写:
# "api_key": "env:TRUE_AGT_SERPER_KEY"
# 然后在 web.py 启动前自行替换(不属于TrueAGT自带能力)
📌 注:TrueAGT目前对api_key字段是字面字符串,不会展开env:VAR。上面提到的「包装脚本替换」是你需要自写的,TrueAGT没内置该逻辑(属部署层惯例,不进核心代码)。如需内置,请通过官方网站「联系我们」页面反馈,我们评估后决定是否纳入后续版本。
按顺序执行以下三步,10 分钟内可判定配置是否生效。
启动 web.py 时看启动日志是否包含:
[搜索 provider=serpapi, url=, api_key 已配置]
或(默认):
[搜索 provider=bing, url=, api_key 未配置]
如果出现 [搜索 provider=<unknown>,回退到 bing] 说明 provider 字段拼写错——允许值是 bing/baidu/duckduckgo/serpapi/bingapi/searxng(区分大小写)。
# 用登录后拿到的 token 替换 <TOKEN>
TOKEN=$(curl -s -X POST http://127.0.0.1:8765/api/login \
-H 'Content-Type: application/json' \
-d '{"username":"henry","password":"..."}' | jq -r .token)
curl -s -X POST http://127.0.0.1:8765/api/agent \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{"session_id":"verify-search","message":"用 web_search 搜一下「TrueAGT Agent 框架」, 给我 3 条结果","stream":false}'
预期返回中包含 web_search 工具调用记录与一组带链接的结果。
项目内已有 test_webtools.py(12 用例)与 test_websearch.py(13 用例),覆盖回退链与解析逻辑;test_smoke.py §12 段(行号见 提交前检查脚本 注册)覆盖 apply_search_config。提交前跑一遍:
python test_webtools.py # 应输出 12/12 PASS
python test_websearch.py # 应输出 13/13 PASS
请运行项目的提交前检查(默认档全绿方可提交)
[搜索失败] 所有搜索引擎均不可达自上而下排查:
provider=serpapi 但 api_key="",会单独报 [搜索失败] 未配置 search.api_key,进不到「全部不可达」。_http_get 走的不是受限代理。临时验证: # Linux/macOS
curl -v "https://api.bing.microsoft.com/v7.0/search?q=test&count=1" \
-H "Ocp-Apim-Subscription-Key: 你的key"
# Windows (PowerShell)
Invoke-WebRequest -Uri "https://api.bing.microsoft.com/v7.0/search?q=test&count=1" `
-Headers @{"Ocp-Apim-Subscription-Key"="你的key"}
返回 200 = 通;返回 401/403 = Key 错或区域错。
_SEARCH_ENGINE_TIMEOUT(单引擎 8 秒)与 _SEARCH_TOTAL_BUDGET(总 22 秒),但这是代码常量,修改后跑全量测试。[无正文] 该页面未提取到可读正文判定:目标页是 JS 动态渲染页(React/Vue SPA、需要滚动加载、需点击「加载更多」)。
选择:
web_search 结果摘要(搜索结果自带的 snippet 字段是后端渲染好的,不依赖 JS),不抓详情正文。?output=amp 或 ?display=mobile 简化版,纯 HTML。手动加到 URL 再试。[搜索失败] 无法访问 SearXNG 实例逐项排查:
url 填的是根地址,不是 /search。代码拼成 <url>/search?q=...&format=json,所以配置应是 https://searxng.example.com 而非 https://searxng.example.com/search。settings.yml: search:
formats:
- html
- json # ← 必须有这一行,否则只返回 HTML
重启 SearXNG 后用 curl 验证:
curl -s "https://searxng.example.com/search?q=test&format=json" | head -c 200
返回 JSON = 通;返回 HTML = 没开 JSON。
format=json query 参数,并禁用强制 Accept: text/html。SerpAPI 请求失败 / Bing Web Search API 请求失败HTTP 401 = Key 失效或账号欠费(控制台查 https://serpapi.com/account);HTTP 429 = 触发速率限制(默认 100 次/月 额度超了)。HTTP 401 = 终结点区域与 Key 不匹配(最常见——Azure 资源是某个区域,Key 只对该区域生效);HTTP 403 = 终结点被防火墙规则拒绝。config.json 已在 .gitignore 中(不在默认跟踪列表)。但首次 git add 时仍可能误操作——养成习惯:写完 Key 后 git diff config.json 确认无变化。Dashboard → Reset API Key,旧 Key 立刻失效。TrueAGT作为编排框架,搜索内容来自第三方引擎,端侧不能做完整合规判断(详见《合规上线准备》说明)。建议:
web_search 的 query 与返回结果只进对话短期上下文,不进审计链。诚实列出TrueAGT永远不打算内置的能力,以免反复讨论:
为什么:内嵌 Chromium(Playwright/Puppeteer)约 200MB 外部依赖 + 二进制分平台分发,击穿「纯标准库、零三方依赖」红线。设计文档《浏览器接入方案》(配套设计说明)已明确:复用用户本机浏览器,绝不内嵌。
当前能力分档:
BrowserPolicy + 进程树回收,单独的硬约束)实际含义:JS 渲染页的「正文抓取」永远做不到,「搜索结果摘要」永远做得到(因为 search engine 自己的 snippet 字段是后端渲染好的 JSON)。
为什么:SerpAPI / Bing API 已有官方 JSON 端点,TrueAGT用标准库 urllib.request 直接调用,不引入 SDK。原因:
requests,击穿零依赖。为什么:SearXNG 是元搜索引擎(聚合 Google/Bing/DuckDuckGo 等),不是替代品。TrueAGT不替用户选上游——这是部署方的运维决策,TrueAGT只对接 JSON 端点。
V-77 在代码层做了三件事(详见 CHANGELOG-DEV.md):
web_fetch 正文提取加固:三级回退(<article>/<main> 优先 → <div> 块评分 → JS 渲染判定),不再塌成页头片段。web_fetch 空正文给出明确 JS 渲染提示。本文不替代 V-77——V-77 改的是「抓得到 / 报错友好」,本文解决「选了哪个 provider、Key 怎么填、失败怎么查」。两者配合才能把联网搜索从「偶发能用」推到「稳定能用」。
| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
search.provider | enum | 否 | bing | 6 个允许值:bing / baidu / duckduckgo / serpapi / bingapi / searxng。区分大小写。其它值启动期忽略,回退到 bing。 |
search.url | string | 仅 searxng 必填 | "" | SearXNG 实例根地址,不带尾斜杠。其它 provider 留空。 |
search.api_key | string | 仅 serpapi/bingapi 必填 | "" | 对应平台 API Key。SearXNG 一般留空(除非启用了鉴权插件)。 |
builtin.py — 搜索实现细节(_search_* 函数、apply_search_config)test_webtools.py / test_websearch.py — 单元测试