Spicrawl nay hoạt động với OpenAI Agents SDK, LangChain, Codex, Claude Code và nhiều hơn nữa.Xem các tích hợp
Chuyển đến nội dung

Web scraping với OpenAI Agents SDK

Kết nối một agent OpenAI Agents SDK với MCP server của Spicrawl. Agent khi đó có thể đọc trang web dưới dạng Markdown.

Thiết lập

  1. Cài openai-agents.

  2. Đặt SPICRAWL_API_KEY và OPENAI_API_KEY.

  3. Mở MCPServerStreamableHttp với URL và header Authorization trong params.

  4. Dùng create_static_tool_filter để giới hạn những tool model nhìn thấy, và truyền server vào Agent của bạn.

Ví dụ: đọc một trang giá

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())

Server không có OAuth, nên hãy luôn gửi key trong headers. Nếu bạn nhận lỗi 401, hãy kiểm tra SPICRAWL_API_KEY đã được đặt trong tiến trình chạy agent.

Giữ danh sách tool ngắn

Cả 25 schema của tool được gửi trong mỗi lệnh gọi model. Hãy giữ spicrawl_scrape, và với nhiều URL hãy thêm spicrawl_batch_submit, spicrawl_batch_status và spicrawl_batch_results.

Nếu code của bạn đã biết cần fetch URL nào, một hàm thường gọi POST /v1/scrape sẽ đơn giản hơn. Nó không tốn token cho schema của tool và dễ test hơn.

Nó làm được gì

Server cung cấp cho agent 25 tool spicrawl_*. Mỗi lệnh gọi chạy dưới API key của bạn, với cùng giới hạn và credit như một lệnh gọi API trực tiếp.

  • Đọc một trang: spicrawl_scrape trả về Markdown (mặc định), text, HTML, JSON hoặc PDF.
  • Đọc nhiều trang: spicrawl_batch_submit xếp hàng tới 10,000 URL. Sau đó dùng spicrawl_batch_status và spicrawl_batch_results.
  • Trang sau màn hình đăng nhập: spicrawl_session_create giữ cookie và bộ nhớ lưu trữ giữa các lệnh gọi.
  • Gỡ lỗi một sự cố: spicrawl_requests_list và spicrawl_request_get.
  • Kiểm tra mức dùng: spicrawl_usage_summary và các tool về mức dùng khác. Các tool này cần key có scope read.
  • Tra cứu: spicrawl_docs_search và spicrawl_docs_read tìm kiếm và đọc tài liệu Spicrawl.

Có một tool, spicrawl_browser_connect_url, được liệt kê nhưng sắp ra mắt. Trên spicrawl_scrape, đối số render là render, không phải js_render của API.

Nên biết

  • Không crawl. Spicrawl không đi theo liên kết hay tự tìm trang. Hãy đưa các URL cho agent.
  • Credit cho mỗi request. Một lần fetch thường là 1 credit. Render JavaScript là 3. Render bằng trình duyệt đầy đủ là 8.
  • Thất bại là miễn phí. Request thất bại tốn 0 credit.
  • Cache tiết kiệm thời gian, không tiết kiệm credit. Một lần trúng cache tốn bằng lần fetch đã lưu nó.
  • Giới hạn từng lệnh gọi. Đặt max_cost, và một request có thể tốn nhiều hơn sẽ bị từ chối trước khi chạy.
  • Sắp ra mắt: proxy được quản lý, chế độ stealth, trình duyệt từ xa và trích xuất AI từ một prompt bằng ngôn ngữ thường. Hiện tại bạn có thể dùng proxy của riêng mình.

Câu hỏi thường gặp

Tôi cần gói nào?

openai-agents. Đặt SPICRAWL_API_KEY và OPENAI_API_KEY trước khi chạy ví dụ.

Làm sao để giới hạn những tool mà model nhìn thấy?

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

Tại sao tôi nhận được 401 khi agent kết nối?

Header bị thiếu hoặc key sai. Hãy tạo header trong code từ SPICRAWL_API_KEY và kiểm tra biến được đặt trong tiến trình chạy agent.

Điều gì xảy ra khi một lệnh gọi tool thất bại?

Lỗi đến model dưới dạng một lỗi tool MCP kèm mã của API. Lệnh gọi thất bại tốn 0 credit.

Mỗi trang tốn bao nhiêu?

Một lần fetch thường tốn 1 credit, render JavaScript 3 và render bằng trình duyệt đầy đủ 8. Request thất bại tốn 0. Cache hit tốn bằng với lần fetch đã lưu nó. Hãy yêu cầu agent đặt max_cost cho mỗi request để nó không bao giờ tiêu nhiều hơn bạn dự kiến.