Spicrawl 现已支持 OpenAI Agents SDK、LangChain、Codex、Claude Code 等。查看集成
跳到内容

OpenAI Agents SDK 网页抓取

将 OpenAI Agents SDK 智能体连接到 Spicrawl MCP 服务器。之后智能体就可以将网页读取为 Markdown。

设置它

  1. 安装 openai-agents。

  2. 设置 SPICRAWL_API_KEY 和 OPENAI_API_KEY。

  3. 用 URL 以及 params 中的 Authorization 请求头打开 MCPServerStreamableHttp。

  4. 使用 create_static_tool_filter 限制模型能看到的工具,并把服务器传给你的 Agent。

示例:读取定价页面

openai_agents_example.py
import asyncio
import os

from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp, create_static_tool_filter


async def main() -> None:
    async with MCPServerStreamableHttp(
        name="spicrawl",
        params={
            "url": "https://mcp.spicrawl.com/mcp",
            "headers": {"Authorization": f"Bearer {os.environ['SPICRAWL_API_KEY']}"},
        },
        cache_tools_list=True,
        tool_filter=create_static_tool_filter(
            allowed_tool_names=["spicrawl_scrape", "spicrawl_batch_submit"]
        ),
    ) as server:
        agent = Agent(
            name="Page reader",
            instructions="Use the Spicrawl tools to read web pages.",
            mcp_servers=[server],
        )
        result = await Runner.run(
            agent,
            "Read https://example.com/pricing as markdown and list the plans.",
        )
        print(result.final_output)


asyncio.run(main())

服务器没有 OAuth,因此请始终在 headers 中发送 key。如果收到 401,请检查运行智能体的进程中是否设置了 SPICRAWL_API_KEY。

保持工具列表简短

每次模型调用都会发送全部 25 个工具的 schema。请保留 spicrawl_scrape,URL 较多时再添加 spicrawl_batch_submit、spicrawl_batch_status 和 spicrawl_batch_results。

如果你的代码已经知道要获取哪个 URL,调用 POST /v1/scrape 的普通函数会更简单。它不占用工具 schema 的 token,也更容易测试。

它能做什么

该服务器为智能体提供 25 个 spicrawl_* 工具。每次调用都在你的 API key 下运行,限制和积分与直接调用 API 相同。

  • 读取一个页面: spicrawl_scrape 返回 Markdown(默认)、文本、HTML、JSON 或 PDF。
  • 读取多个页面: spicrawl_batch_submit 最多可排入 10,000 个 URL。之后用 spicrawl_batch_status 和 spicrawl_batch_results 跟进。
  • 登录后的页面: spicrawl_session_create 会在多次调用之间保留 cookie 和存储。
  • 调试失败: spicrawl_requests_list 和 spicrawl_request_get。
  • 查看用量: spicrawl_usage_summary 及其他用量工具。这些工具需要具有 read 权限范围的 key。
  • 查资料: spicrawl_docs_search 和 spicrawl_docs_read 用于搜索和阅读 Spicrawl 文档。

有一个工具 spicrawl_browser_connect_url 已列出但即将推出。在 spicrawl_scrape 上,渲染参数是 render,而不是 API 的 js_render。

须知

  • 不支持爬取。 Spicrawl 不会跟随链接或查找页面。请把 URL 交给智能体。
  • 每次请求的积分。 普通抓取 1 积分。JavaScript 渲染 3。完整浏览器渲染 8。
  • 失败免费。 失败的请求费用为 0 积分。
  • 缓存节省的是时间,而不是积分。 缓存命中的费用与存储它的那次获取相同。
  • 为每次调用设置上限。 设置 max_cost 后,可能超出预算的请求会在运行前被拒绝。
  • 即将推出: 托管代理、隐身模式、远程浏览器,以及基于自然语言提示词的 AI 提取。目前你可以自带代理。

常见问题

我需要哪个包?

openai-agents。运行示例之前,请设置 SPICRAWL_API_KEY 和 OPENAI_API_KEY。

如何限制模型能看到的工具?

Pass tool_filter=create_static_tool_filter(allowed_tool_names=[...]). The example keeps spicrawl_scrape and spicrawl_batch_submit.

智能体连接时为什么会收到 401?

请求头缺失或 key 有误。请在代码中根据 SPICRAWL_API_KEY 构建请求头,并检查该变量已在运行智能体的进程中设置。

工具调用失败时会发生什么?

该错误会以 MCP 工具错误的形式连同 API 的错误码一起传给模型。失败的调用费用为 0 积分。

每个页面要多少钱?

普通抓取 1 积分,JavaScript 渲染 3,完整浏览器渲染 8。失败的请求为 0。缓存命中的费用与存入该缓存的那次抓取相同。让智能体在每次请求上设置 max_cost,这样花费就不会超出你的预期。