为什么 Agent 需要一条专门的搜索 API

大模型的知识停在训练截止日。一旦问题涉及"最新"、"今天"、"现在的价格"，模型只能编造。给 Agent 接网，听起来像调用一个搜索框，做起来才发现处处是坑。

直接抓网页为什么行不通

最朴素的做法是让 Agent 拿到 URL 后自己 fetch 整页 HTML。问题立刻出现：

• 上下文爆炸 — 一页 HTML 动辄几百 KB，导航、脚本、广告占掉绝大部分，正文淹没其中。
• 没有排序信号 — 搜索引擎用几百个信号排序结果，自己抓页面拿不到"哪个结果更可信"。
• 反爬与渲染 — 越来越多的站点需要 JS 渲染或有反爬策略，裸 fetch 拿到的只是空壳。
• 成本不可控 — 每次调用烧多少 token、花多少钱，完全无法预估。

一条搜索 API 应该长什么样

给 Agent 用的搜索，和给人用的搜索，需求完全不同。人要的是十条蓝色链接；Agent 要的是可以直接进上下文的结构化证据：

{
  "query": "latest papers on retrieval",
  "results": [
    {
      "title": "Dense Passage Retrieval",
      "url": "https://arxiv.org/abs/2004.04906",
      "content": "DPR shows that dual-encoder retrievers...",
      "score": 0.95
    }
  ],
  "response_time": 0.42
}

关键差异在三点：

1. 正文而不是 HTML — 每条结果带清洗后的摘要或正文，模型直接引用，不用再解析 DOM。
2. 确定性计费 — 一次调用一个价格（basic 1 积分、advanced 2 积分），Agent 框架可以做预算控制。
3. 错误可预期 — 余额不足返回 432，限流返回 429，格式统一为 { "detail": { "error": "..." } }，重试逻辑好写。

Search 与 Extract 的分工

搜索解决"找到哪些页面"，但很多时候你已经知道 URL——比如用户贴了一个链接，或者上一轮搜索给出了候选。这时需要的是定点抽取：把指定 URL 变成干净的 markdown。

WebSearch 把这两件事拆成两个端点：

• POST /api/search — 查询进，排序后的结果列表出
• POST /api/extract — URL 列表进，逐页正文出（失败的 URL 单独列出，不收费）

组合起来就是 Agent 的标准动作：先 search 找候选，再 extract 取正文，最后让模型基于真实来源作答。

下一步

注册即送 1,000 积分，直接在 Playground 里试，或者读快速开始用 curl 跑通第一次调用。