Telem:跨 Provider 路由 Agent Web Search,并把每条搜索请求的痕迹完整留痕

当 Agent 自己上网,问题不再是"搜得到",而是"谁来搜" 2026 年的智能体不再只跟大模型对话。它们读网页、抓商品、查法规、比价格,Web Search 已经从"模型的一次函数调用"变成"模型整个工作流的入口"。一旦 Agent 进入真实业务,一个绕不开的问题就出现了:每一次搜索到底走了哪一家搜索服务?花了多少钱?花得值吗?出错了该找谁? 围绕这些需求,硅谷的 Telem AI 给出了一个

当 Agent 自己上网,问题不再是"搜得到",而是"谁来搜"

2026 年的智能体不再只跟大模型对话。它们读网页、抓商品、查法规、比价格,Web Search 已经从"模型的一次函数调用"变成"模型整个工作流的入口"。一旦 Agent 进入真实业务,一个绕不开的问题就出现了:每一次搜索到底走了哪一家搜索服务?花了多少钱?花得值吗?出错了该找谁?

围绕这些需求,硅谷的 Telem AI 给出了一个清晰的工程答案——不是再做一家搜索引擎,而是在 Agent 和搜索引擎之间架一层"路由 + 全量留痕"的中间层。本文基于 Telem 官方文档(telem.ai、docs.telem.ai)与第三方深度评测(aiindigo.com),拆解它怎么把"Agent 上网"这件事做成了可观测、可治理的基础设施。

一、Tele 是什么:Agent 的"网络栈",不是又一家搜索引擎

官方首页的自我介绍只有一句:"Telem AI builds infrastructure for AI agents. Its platform routes agent web searches across multiple providers by cost, latency, and answer quality through one API with automatic failover, and retrieves pages as readable content for models."

也就是说,Telem 把自己定位成 Agent 的"网络栈",三个产品共用一个 API:

• PRD-01 Web Search Router:把 Agent 的搜索请求按成本、延迟、答案质量路由到最优 Provider,Provider 降级时自动 Failover。
• PRD-02 Web Fetch Router:负责把目标 URL 拉下来并清洗成模型能直接读的 Markdown / 文本,负责渲染、重试、提取。
• PRD-03 Observability:在 console.app.telem.ai 里回放每一次搜索和每一次抓取,带质量评分,支持 replay / compare / export。

它的"打法"和 OpenRouter 类似——名字里就有 Router,但 OpenRouter 解决的是"一个大模型 API 调多家 LLM 厂商",Telem 解决的是"一个搜索 API 调多家 Web Search 厂商"。换句话说,你在代码里只 import 一次 Telem,后面要换 Provider、要加 Provider、要查 Provider 干的好不好,都不用动 Agent 的业务逻辑。

二、跨 Provider 路由:为什么这件事必须做

任何做过 Agent 工程化的人都知道,Web Search 不是一个稳定接口。市面上主流的几个搜索 Provider 各有擅长:

• Exa:基于 embedding 的神经检索,适合自然语言长问句、相似语义查询。
• Tavily:面向 Agent / RAG 场景优化,返回结构化结果,常被默认当作"Agent 友好型搜索"。
• Brave:独立关键词索引,响应快、成本低,适合事实查询和精确匹配。

但它们没有谁可以单独扛起全部业务:Exa 在事实召回上有时会缺,Tavily 在量大时延迟飘,Brave 对长尾自然语言召回一般。官方 Quickstart 的样例请求恰好是这种思路的工程化表达:

curl -s -X POST "$TELEM_BASE_URL/v1/search" \
  -H "Authorization: Bearer $TELEM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_input": {"query": "when was the International Space Station launched"},
       "search": {"providers": {"include": ["exa", "brave"]}, "num_results": 5}}'

注意 providers.include 同时点了 Exa 和 Brave——前者走 embedding 语义,后者走独立关键词索引,两种检索范式被一次请求并行覆盖。这就是 Telem 路由层的核心动作:把"用谁搜"的决定,从 Agent 代码里挪出来,放到一个集中的、可以按调用配置的策略层。

几个工程化细节值得展开:

1. include / exclude 双向控制。Config Reference 明确写出:可以传 providers.include 替换整个 Provider 集合,也可以传 providers.exclude 从集合里剔除。当两者都解析时,先做 include,再从结果里 subtract exclude。这意味着你可以一次性声明"这次只用 Tavily 和 Brave",也可以全局排除掉"贵的那家"。

2. provider_overrides 直通原厂参数。这是个被低估的设计——如果你想给 Brave 单独传一个它自家的参数(比如 country),用 provider_overrides 按 Provider 名作为 key 透传即可,Telem 不替你吃掉这些字段。

3. include_raw 拿原始 Payload。需要做归因或自建评测时,可以把每个 Provider 自己返回的原始 JSON 也拿回来,方便对账。

4. 预扣费上限,失败不留痕。Config Reference 的"Request limits"一节写得很清楚:每个请求的形态上限(URL 数、结果数、批量查询数、查询×结果总体积)在"计费之前"就被检查——一个被拒绝的请求不会留下任何调用记录,不会让你"花了钱才发现请求根本不该发"。

三、自动 Failover:Provider 降级时,业务不感知

搜索 Provider 不是银行系统,但生产环境的 Agent 一定会撞到以下场景:

• 某家 Provider 当天突然返回 5xx,大批量超时。
• 某家 Provider 因为账号余额耗尽返 402,需要切走。
• 某家 Provider 的检索质量突然下降(被某些上游数据污染),召回里全是垃圾。

Telem 的处理方式是"双层冗余 + 自动重试",在路由层和 SDK 调用层都体现。官方文档对 Response 的描述是这样的:每次搜索返回的是一个 InteractionResponse,其中 preprocessor_runs 是一个数组——每个 Provider 一次 run,每个 run 都有自己的 status、error、latency_ms 和 output_payload。这意味着:一家 Provider 失败只是这一次 run 的 status 出错,不是整个请求失败。剩下的 Provider 跑完照样能拼出一个完整的结果集。Agent 代码不需要写 try/catch 去"猜哪一家会挂",只要调用 Telem,剩下的路由层兜底。

更进一步,SDK 的集成里有一项细节很关键:增量上下文传输(incremental transmission)。OpenCode、OpenClaw、Pi 等插件和 Python SDK 默认把对话上下文"增量"传给后端——子 Agent 继承的上下文只在第一次传输,后续搜索不再重复上传。客户端在发送前会校验后端是否支持该模式,旧版本或自托管部署不支持就自动回落到全量传输。这对一个长会话里会触发几十次搜索的 Agent 来说,成本和延迟都能被显著压低。环境变量 TELEM_INCREMENTAL=off 是这个行为的"运营回滚阀门",不是日常调优旋钮。

四、Web Fetch Router:把"抓页面"这件脏活打包

Web Search 解决"找到 URL",Web Fetch 解决"读到内容"。这两个在 Agent 工程里经常被混在一起,但实际成本模型完全不同。Telem 把它们做成两个独立 endpoint:POST /v1/search 和 POST /v1/fetch。

Fetch 的设计有几个亮点:

1. 批量 URL,一次调用。传一个 urls 数组,Telem 内部帮你处理渲染、重试、限流。返回的是按 URL 对应的清洗后内容,而不是一坨 HTML。

2. 四档 Tier,显式选档。tier 字段支持 minimalist / default / extended / max 四档,每档携带的信息密度不同——你要的是标题摘要,还是全文+结构化字段,在请求里点一次就好。tiert 越往上,响应越大、单次成本越高,所以 Agent 应该根据"这步要不要喂给 LLM 读"来选档。

3. content_format 二选一。markdown 或 text。前者对长文档更友好(保留结构),后者对短字段抽取更可控。

4. inline_content 决定是否返回正文。默认 true,设 false 只返回元数据,适合只想"确认 URL 还在不在、不需要内容"的探测场景。

5. inline_max_chars 上限 20000。超过会被截断并标记,避免一次调用塞给 LLM 一个超长网页把上下文撑爆。

五、可观测性:每一条搜索请求都留痕

这才是 Telem 最值得展开的部分。它不只是"把搜索路由好",更重要的是"把每次搜索的事实证据留下来"。

从 Response 字段可以看到完整的留痕体系:

• session_id / interaction_id / trajectory_id:三层 ID 体系。一个 Session 包含多次 Interaction,一次 Interaction 可以拆出多个 Trajectory,Trajectory 之间还能父子串联(parent_trajectory_id)。这等于给了你一棵可回放的"Agent 决策树"。
• preprocessor_runs[] + postprocessor_runs[]:每一步都有名字(preprocessor_name)、状态、原始请求 payload、原始响应 payload、延迟毫秒、错误对象。如果某一步出错,直接看 error 字段,不用打日志猜。
• raw_payload:Provider 自家返回的原始 JSON。需要做"我们到底用了哪家 Provider 的哪个字段"的归因时,直接对 raw_payload 抽取即可。
• created_at / completed_at:端到端耗时是可见的,这对调优"哪一类查询慢"至关重要。
• normalized_schema_version:当 Telem 调整返回结构时,你能清楚知道这次的响应是哪个 schema 版,方便做兼容。

Console 侧(app.telem.ai)把这套留痕做成了可视化:登录后能看到每一个项目的"traces / traffic / judged quality metrics",支持 replay(把同一条请求原样重发,看 Provider 当下的行为)、compare(对比两次同 query 的不同 Provider 表现)、export(把 trace 导出来做离线分析)。官方首页那段话总结得很克制——"Traces, traffic, and judged quality metrics across every project — live in the Telem console today"。

对 Agent 团队的实际价值是什么?三个场景:

1. 排障。Agent 给出错误答案,不用再"猜是 Prompt 的问题还是搜索的问题"——打开 trace,看 preprocessor run 里 status 是哪个字段、error 是什么、用了哪家 Provider。
2. 成本治理。每天跑下来,可以看到每个项目在每个 Provider 上的流量分布,贵的 Provider 用多了多少、便宜但慢的 Provider 是不是真的值得。
3. 质量回放。对于"为什么 Agent 这次选了 A 而不选 B"的争议,看 trajectory_id 链路就能定位。

六、商业模型:零平台费,这是它和 OpenRouter 的关键差异

官方 Pricing 页面把这件事写在了最显眼的位置:"Unlike the OpenRouter business model, you pay the upstream provider's per-request rate for every search and fetch Telem routes — routing, tracing, and the observability console add no platform fee on top."

翻译一下:OpenRouter 会按调用量抽一笔平台费,Telem 不抽。你付的钱就是上游 Provider(Exa / Tavily / Brave 等)的原价,Telem 自己赚的不是流量差价,而是 Enterprise 套餐里那些额外的功能——专属路由基础设施、SSO、审计控制、定制集成、7x24 on-call。这是一种更接近"卖工具、卖服务、不卖流量"的 SaaS 逻辑,对用量大但不想被按比例抽成的 Agent 团队非常友好。

注册即送 $20 免费额度,大约等于 4000+ 次查询,不需要信用卡。这降低了试用门槛——你不需要先跟销售谈一轮才能跑通第一条调用。

七、三种接入路径:从"一条 curl"到"原生工具"

官方 Quickstart 文档列了三条路径,清晰展示了 Telem 对不同角色的工程适配:

路径 1:安装到现有 Agent 框架。一行 curl -fsSL https://docs.telem.ai/install.sh | sh。脚本会检测你已经装的框架(Claude Code / Codex / OpenCode / OpenClaw / Pi / MCP-json 等),让你空格勾选要接入哪些,然后通过各自框架原生的安装路径写插件,把 key 写到 ~/.telem/credentials.json(权限 0600)。安装完重启 Agent 框架,搜索和抓取就成了 Agent 的原生工具,并且具备完整的 retrieval metrics + trajectory analytics。

路径 2:不装任何东西,教 Agent 自己调 API。一行 npx skills add https://docs.telem.ai,会给 Agent 安装一个 telem-search 的 skill(SKILL.md),Agent 读完就懂怎么直接调 POST https://router.telem.ai/v1/search。优点是不动框架配置、不留 trajectory;缺点是没有 retrieval metrics。

路径 3:用 Python 或 JavaScript SDK。pip install telem-sdk 或 npm install @telemai/sdk,然后三行代码发起一次搜索。SDK 自动读 TELEM_API_KEY 和 TELEM_BASE_URL 环境变量,fallback 到 ~/.telem/credentials.json。这一路径最干净,适合把 Telem 嵌进自己的 Agent 框架或后台服务里。

官方在三条路径结尾用一张对照表收得很到位——Path 1 给你"Agent 拿到原生搜索 + 抓取工具 + 全链路 trace";Path 2 给你"不装任何东西,但 Agent 学会了直接发 HTTP";Path 3 给你"Python/JS SDK,自己接线"。不同角色挑不同的,而不是只有一条路。

八、Agent Skill 协议:一个 .md 文件就是一整个接入

Telemetry 这件事最让工程团队兴奋的可能是 npx skills add https://docs.telem.ai 这条命令。背后是 Agent Skills 这个新协议——一个 SKILL.md 文件,带 YAML frontmatter,无依赖、无脚本、无安装步骤。Agent 读到它就自动知道"什么情况下应该搜索、什么时候不该搜、请求长什么样、响应怎么解析、warning 怎么处理"。

这里 Telem 做对的几件事:

• 教 Agent "什么时候不搜"。答案已经在模型权重里、在私有语料里、在已知 URL 里——这三种情况明文写在 SKILL.md,要求 Agent 不浪费一次搜索。
• 教 Agent "写什么查询"。Provider 覆盖了两种检索范式,所以 SKILL.md 强调"完整的自然语言句子优于关键词碎片",这不是空话,是经验。
• 教 Agent "怎么读响应"。扁平化合并多 Provider 结果、保留 provider 归属、warning 数组的含义——Agent 自己读得懂。
• 教 Agent "怎么调 fetch"。已经知道 URL 的场景,直接用 POST /v1/fetch,不要先搜索再点链接。

这意味着任何一个遵守 Agent Skills 协议的框架(目前 OpenCode 是其中之一),都可以零成本获得一个"知道怎么用 Telem 搜索"的 Agent,门槛低到只剩一行命令。

九、它适合谁,不适合谁

第三方评测(aiindigo.com)给出了一份值得参考的画像:

适合:

• 需要实时 Web 数据的自主 Agent 团队;
• 优化 RAG 检索阶段准确率和速度的团队;
• 寻找成本可控、可扩展搜索集成的初创公司;
• 需要在复杂 AI 工作流里做可观测和 trace 的工程师。

不适合:

• 创意写作、图像生成、营销文案这类不需要联网的任务——加一层路由只会徒增延迟;
• 需要直接对接数据库或私有知识库的场景——Telem 限定在 Web Search/Fetch,不替代向量库。

几个工程上的"注意点"也值得说:① 仍然依赖上游 Provider 的可用性和价格波动,Telem 解决路由不解决上游稳定性;② 高级分析和策略可能需要学习成本,不是开箱即用;③ 目前没有覆盖 Web Search 之外的其它数据源,生态仍然单一。

十、为什么"留痕"这件事比想象中更重要

回到最初的问题——把每一条搜索请求的痕迹完整留痕,到底解决了什么?

对 Agent 团队来说,Web Search 已经从"调一次 API"升级为"Agent 决策链路的一环"。一个搜索结果的好坏,直接决定下游 Agent 答得好不好。而 Agent 的"思考过程"一旦不可观测,出问题就只能是"重跑一遍,看看是不是就好了",这在生产环境不可接受。

Telem 给出的解法是:把每一次搜索当作一个 first-class 的工程对象,带 ID、带 status、带 Provider 归属、带延迟、带原始 payload。当 Agent 出问题时,你不是在调日志,而是在 console 里拖一根 timeline,看清楚每一步发生了什么。

这是 Agent 走向生产必须补上的一块拼图——和 LLM 侧的 observability(Helicone / Langfuse / Arize)一个道理:模型调用要 trace,搜索调用也要 trace。当 Telem 把这一层补齐,Agent 团队终于可以把"为什么 Agent 这次答错了"的排障时间从几小时压缩到几分钟。

至于它能不能成为 Agent 网络层的"事实标准",取决于后续接入的 Provider 数量、SDK 的成熟度、以及定价能否持续保持"零平台费"的诚意。但至少在 2026 年这个时间点,把"跨 Provider 路由 + 全量留痕 + 零平台费"三件事一起做对,已经值得任何认真做 Agent 落地的团队去试用一次。