O Spicrawl agora funciona com OpenAI Agents SDK, LangChain, Codex, Claude Code e mais.Ver integrações
Pular para o conteúdo

Web scraping com o OpenAI Agents SDK

Conecte um agente do OpenAI Agents SDK ao servidor MCP do Spicrawl. O agente passa a ler páginas web como Markdown.

Configure

  1. Instale openai-agents.

  2. Defina SPICRAWL_API_KEY e OPENAI_API_KEY.

  3. Abra MCPServerStreamableHttp com a URL e o cabeçalho Authorization em params.

  4. Use create_static_tool_filter para limitar quais ferramentas o modelo enxerga e passe o servidor para o seu Agent.

Exemplo: ler uma página de preços

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

O servidor não tem OAuth, então sempre envie a chave em headers. Se você receber um 401, confira se SPICRAWL_API_KEY está definido no processo que roda o agente.

Mantenha a lista de ferramentas curta

Os schemas das 25 ferramentas são enviados a cada chamada ao modelo. Mantenha spicrawl_scrape e, para muitas URLs, adicione spicrawl_batch_submit, spicrawl_batch_status e spicrawl_batch_results.

Se o seu código já sabe qual URL buscar, uma função simples que chama POST /v1/scrape é mais simples. Ela não gasta tokens de schema de ferramentas e é mais fácil de testar.

O que ele pode fazer

O servidor dá ao agente 25 ferramentas spicrawl_*. Cada chamada roda sob a sua chave de API, com os mesmos limites e créditos de uma chamada direta à API.

  • Ler uma página: spicrawl_scrape retorna Markdown (o padrão), texto, HTML, JSON ou PDF.
  • Ler várias páginas: spicrawl_batch_submit enfileira até 10.000 URLs. Acompanhe com spicrawl_batch_status e spicrawl_batch_results.
  • Páginas atrás de um login: spicrawl_session_create mantém cookies e armazenamento entre as chamadas.
  • Depure uma falha: spicrawl_requests_list e spicrawl_request_get.
  • Verifique o uso: spicrawl_usage_summary e as outras ferramentas de uso. Elas exigem uma chave com o escopo read.
  • Pesquise coisas: spicrawl_docs_search e spicrawl_docs_read pesquisam e leem a documentação do Spicrawl.

Uma ferramenta, spicrawl_browser_connect_url, está listada mas chega em breve. Em spicrawl_scrape, o argumento de renderização é render, não o js_render da API.

Bom saber

  • Sem crawl. O Spicrawl não segue links nem encontra páginas. Dê as URLs ao agente.
  • Créditos por requisição. Um fetch simples custa 1 crédito. A renderização JavaScript custa 3. A renderização em navegador completo custa 8.
  • Falhas são grátis. Uma requisição que falha custa 0 crédito.
  • O cache economiza tempo, não créditos. Um acerto de cache custa o mesmo que a busca que o guardou.
  • Limite cada chamada. Defina max_cost e uma requisição que poderia custar mais é recusada antes de rodar.
  • Em breve: proxies gerenciados, modo stealth, um navegador remoto e extração com IA a partir de um prompt em linguagem natural. Hoje você pode usar seu próprio proxy.

Perguntas frequentes

De qual pacote eu preciso?

openai-agents. Defina SPICRAWL_API_KEY e OPENAI_API_KEY antes de rodar o exemplo.

Como limito quais ferramentas o modelo enxerga?

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

Por que recebo um 401 quando o agente se conecta?

O cabeçalho está ausente ou a chave está errada. Monte o cabeçalho no código a partir de SPICRAWL_API_KEY e confira se a variável está definida no processo que roda o agente.

O que acontece quando uma chamada de ferramenta falha?

O erro chega ao modelo como um erro de ferramenta MCP com o código da API. Chamadas com falha custam 0 crédito.

Quanto custa cada página?

Um fetch simples custa 1 crédito, a renderização JavaScript 3 e a renderização em navegador completo 8. Requisições com falha custam 0. Um acerto de cache custa o mesmo que o fetch que o armazenou. Peça ao agente para definir max_cost em cada requisição, para que ele nunca gaste mais do que você espera.