接入 AI Agent

Agent 需要从网上拿两样东西：有哪些内容（搜索结果）和内容讲了什么（网页正文）。SerpHubAPI 一次调用就能同时返回两者，格式可以直接放进 prompt。

两个关键参数

参数	作用
include_content: N（1–5）	抓取前 N 个结果网页，把正文以 Markdown 放在 content[] 中返回。每成功抓取一页 +3 积分；失败的页面免费，并带 error: "fetch_failed"。
format: "markdown"	把整个响应——搜索结果加网页正文——拼成一份 Markdown 文档返回，而不是 JSON。

两者组合：

curl -X POST https://api.serphubapi.com/v1/search \
  -H "X-API-Key: shapi_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"q": "recursive self improvement agents", "include_content": 3, "format": "markdown"}'

返回一段 Markdown 文本：先是结果列表，之后每个网页一个 ## Content: <url> 小节。费用：10 + 3 × 3 = 19 积分（有页面抓取失败则更少）。

RAG 管线用 JSON

如果你自己做切片和向量化，保持 JSON 格式，读取 content[] 即可：

import os, httpx

r = httpx.post(
    "https://api.serphubapi.com/v1/search",
    headers={"X-API-Key": os.environ["SERPHUBAPI_API_KEY"]},
    json={"q": "EU AI Act obligations for general-purpose models", "include_content": 5},
    timeout=60,
)
r.raise_for_status()
data = r.json()

titles = {o["link"]: o["title"] for o in data["results"].get("organic", [])}
docs = [
    {"source": c["link"], "title": titles.get(c["link"], ""), "text": c["markdown"]}
    for c in data.get("content", [])
    if c["markdown"]
]
# -> 切片、向量化、入库；保留 data["meta"]["id"] 以便溯源

建议把 meta.id 和切片一起保存：30 天内都能通过 GET /v1/searches/{id} 准确还原 agent 当时看到的内容。

最小 agent 工具示例（LangChain 风格）

import os
import httpx
from langchain_core.tools import tool

API = "https://api.serphubapi.com"
HEADERS = {"X-API-Key": os.environ["SERPHUBAPI_API_KEY"]}


@tool
def web_search(query: str, read_pages: int = 0) -> str:
    """Search the web. Returns results as Markdown.
    Set read_pages (0-5) to also include the full text of the top pages."""
    r = httpx.post(
        f"{API}/v1/search",
        headers=HEADERS,
        json={"q": query, "include_content": read_pages, "format": "markdown"},
        timeout=60,
    )
    if r.status_code != 200:
        return f"Search failed: {r.json()['error']['code']}"
    return r.text


@tool
def read_page(url: str) -> str:
    """Read a web page and return its main content as Markdown."""
    r = httpx.post(f"{API}/v1/fetch", headers=HEADERS, json={"url": url}, timeout=60)
    if r.status_code != 200:
        return f"Could not read page: {r.json()['error']['code']}"
    return r.json()["markdown"]


tools = [web_search, read_page]
# llm.bind_tools(tools)，或交给你的 agent executor

这两个函数在任何接受 Python 函数作为工具的框架里都能用。如果你的 agent 运行在 MCP 客户端里，直接用 MCP Server 即可，无需写代码。

控制成本与上下文

• 先不带正文。 让 agent 先搜索（10 积分），再对真正需要的一两个链接调用 read_page（每个 3 积分）。如果确定要读前几条结果，再用 include_content，能省一次往返。
• 重复问题用 mode: "cache_first"。 Agent 经常重复同样的查询。cache_first 下一次搜索 5 积分，如果一小时内有人搜过则为 0。
• 调低 num。 价格不变，但结果越少，占用的上下文 token 越少。
• 给每个 agent 的 Key 设上限。 每个 agent 单独一个 Key，并在 /dashboard/keys 设置每日积分上限。
• 空结果免费，可以放心让 agent 尝试很窄的查询。
• 把错误当作工具输出返回。 像上面那样把错误码以文本形式交给模型，它就能换个说法重试或继续下一步，而不是直接崩溃。502 all_upstreams_failed 不收费，可以安全重试。