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 LangChain e Spicrawl

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

Configure

  1. Instale langchain-mcp-adapters e langchain[openai].

  2. Defina SPICRAWL_API_KEY e a chave do seu provedor de modelo (OPENAI_API_KEY aqui).

  3. Crie um MultiServerMCPClient com uma entrada spicrawl. "transport": "streamable_http" e headers configuram a conexão.

  4. Mantenha só as ferramentas de que precisa e monte um agente LangGraph com create_agent.

Exemplo: ler uma página de preços

langchain_example.py
import asyncio
import os

from langchain.agents import create_agent
from langchain_mcp_adapters.client import MultiServerMCPClient


async def main() -> None:
    client = MultiServerMCPClient(
        {
            "spicrawl": {
                "transport": "streamable_http",
                "url": "https://mcp.spicrawl.com/mcp",
                "headers": {"Authorization": f"Bearer {os.environ['SPICRAWL_API_KEY']}"},
            }
        }
    )
    keep = {"spicrawl_scrape", "spicrawl_batch_submit"}
    tools = [t for t in await client.get_tools() if t.name in keep]

    agent = create_agent("openai:gpt-4.1", tools)
    result = await agent.ainvoke(
        {"messages": "Read https://example.com/pricing as markdown and list the plans."}
    )
    print(result["messages"][-1].content)


asyncio.run(main())

Por padrão, cada chamada de ferramenta abre sua própria sessão MCP. Isso funciona bem para spicrawl_scrape, que não tem estado. O servidor não tem OAuth, então sempre envie a chave em headers.

Mantenha a lista de ferramentas curta

Os schemas das 25 ferramentas são enviados a cada chamada ao modelo. Isso aumenta o custo do prompt e pode confundir o 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, talvez você nem precise de MCP. Uma função simples que chama POST /v1/scrape 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 quais pacotes eu preciso?

langchain-mcp-adapters e langchain[openai]. Defina SPICRAWL_API_KEY e OPENAI_API_KEY antes de rodar o exemplo.

Devo dar ao agente as 25 ferramentas?

Em geral, não. Os schemas de todas as ferramentas são enviados a cada chamada do modelo. Mantenha spicrawl_scrape e, para muitas URLs, spicrawl_batch_submit, spicrawl_batch_status e spicrawl_batch_results.

Cada chamada de ferramenta abre uma nova sessão?

Sim, por padrão. Isso não é problema para spicrawl_scrape, que é stateless. Veja o README do adaptador para client.session("spicrawl") se você quiser uma sessão por execução.

Devo usar MCP ou chamar a API diretamente?

Use MCP quando o modelo decide o que buscar. Quando o seu código já sabe a URL, uma função simples que chama POST /v1/scrape é mais simples e não gasta tokens de schema de ferramentas.

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.