Spicrawl ora funziona con OpenAI Agents SDK, LangChain, Codex, Claude Code e altri.Vedi le integrazioni
Vai al contenuto

Web scraping con OpenAI Agents SDK

Collega un agente OpenAI Agents SDK al server MCP di Spicrawl. L’agente potrà così leggere le pagine web come Markdown.

Configuralo

  1. Installa openai-agents.

  2. Imposta SPICRAWL_API_KEY e OPENAI_API_KEY.

  3. Apri MCPServerStreamableHttp con l’URL e l’header Authorization in params.

  4. Usa create_static_tool_filter per limitare quali strumenti vede il modello e passa il server al tuo Agent.

Esempio: leggere una pagina dei prezzi

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

Il server non ha OAuth, quindi invia sempre la chiave in headers. Se ricevi un 401, controlla che SPICRAWL_API_KEY sia impostato nel processo che esegue l’agente.

Tieni breve l’elenco dei tool

Tutti i 25 schemi degli strumenti vengono inviati a ogni chiamata al modello. Tieni spicrawl_scrape e, per molti URL, aggiungi spicrawl_batch_submit, spicrawl_batch_status e spicrawl_batch_results.

Se il tuo codice sa già quale URL recuperare, una semplice funzione che chiama POST /v1/scrape è più semplice. Non costa token di schema degli strumenti ed è più facile da testare.

Cosa può fare

Il server offre all’agente 25 strumenti spicrawl_*. Ogni chiamata viene eseguita con la tua chiave API, con gli stessi limiti e crediti di una chiamata diretta all’API.

  • Leggi una pagina: spicrawl_scrape restituisce Markdown (predefinito), testo, HTML, JSON o PDF.
  • Leggi molte pagine: spicrawl_batch_submit mette in coda fino a 10.000 URL. Poi usa spicrawl_batch_status e spicrawl_batch_results.
  • Pagine dietro un login: spicrawl_session_create mantiene cookie e storage tra una chiamata e l’altra.
  • Fai il debug di un errore: spicrawl_requests_list e spicrawl_request_get.
  • Controlla l’utilizzo: spicrawl_usage_summary e gli altri strumenti di utilizzo. Richiedono una chiave con lo scope read.
  • Cerca informazioni: spicrawl_docs_search e spicrawl_docs_read cercano e leggono nella documentazione di Spicrawl.

Uno strumento, spicrawl_browser_connect_url, è elencato ma in arrivo. Su spicrawl_scrape, l’argomento di rendering è render, non js_render come nell’API.

Da sapere

  • Nessun crawling. Spicrawl non segue link né trova pagine. Dai all’agente gli URL.
  • Crediti per richiesta. Un fetch semplice costa 1 credito. Il rendering JavaScript 3. Il rendering con browser completo 8.
  • I fallimenti sono gratuiti. Una richiesta fallita costa 0 crediti.
  • La cache fa risparmiare tempo, non crediti. La cache fa risparmiare tempo, non crediti.
  • Limita ogni chiamata. Imposta max_cost, e una richiesta che potrebbe costare di più viene rifiutata prima di essere eseguita.
  • In arrivo: proxy gestiti, modalità stealth, un browser remoto ed estrazione con AI da un prompt in linguaggio naturale. Oggi puoi usare il tuo proxy.

Domande frequenti

Di quale pacchetto ho bisogno?

openai-agents. Imposta SPICRAWL_API_KEY e OPENAI_API_KEY prima di eseguire l’esempio.

Come limito quali tool vede il modello?

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

Perché ricevo un 401 quando l’agente si collega?

L’header manca o la chiave è sbagliata. Costruisci l’header nel codice da SPICRAWL_API_KEY e verifica che la variabile sia impostata nel processo che esegue l’agente.

Cosa succede quando una chiamata a un tool fallisce?

L’errore arriva al modello come errore di tool MCP con il codice dell’API. Le chiamate fallite costano 0 crediti.

Quanto costa ogni pagina?

Un fetch semplice costa 1 credito, il rendering JavaScript 3 e il rendering con browser completo 8. Le richieste fallite costano 0. Un cache hit costa quanto il fetch che l’ha salvato. Chiedi all’agente di impostare max_cost su ogni richiesta così non spende mai più del previsto.