Spicrawl fonctionne désormais avec OpenAI Agents SDK, LangChain, Codex, Claude Code et plus encore.Voir les intégrations
Aller au contenu

Web scraping avec l’OpenAI Agents SDK

Connectez un agent OpenAI Agents SDK au serveur MCP de Spicrawl. L’agent peut alors lire des pages web en Markdown.

Configurez-le

  1. Installez openai-agents.

  2. Définissez SPICRAWL_API_KEY et OPENAI_API_KEY.

  3. Ouvrez MCPServerStreamableHttp avec l’URL et l’en-tête Authorization dans params.

  4. Utilisez create_static_tool_filter pour limiter les outils que le modèle voit, et transmettez le serveur à votre Agent.

Exemple : lire une page de tarifs

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

Le serveur n’a pas d’OAuth, donc envoyez toujours la clé dans headers. Si vous obtenez une erreur 401, vérifiez que SPICRAWL_API_KEY est défini dans le processus qui exécute l’agent.

Gardez la liste d’outils courte

Les schémas des 25 outils sont envoyés à chaque appel du modèle. Gardez spicrawl_scrape et, pour de nombreuses URL, ajoutez spicrawl_batch_submit, spicrawl_batch_status et spicrawl_batch_results.

Si votre code sait déjà quelle URL récupérer, une fonction ordinaire qui appelle POST /v1/scrape est plus simple. Elle ne coûte aucun jeton de schéma d’outil et se teste plus facilement.

Ce qu’il peut faire

Le serveur donne à l’agent 25 outils spicrawl_*. Chaque appel s’exécute sous votre clé API, avec les mêmes limites et les mêmes crédits qu’un appel direct à l’API.

  • Lire une page : spicrawl_scrape renvoie du Markdown (par défaut), du texte, du HTML, du JSON ou un PDF.
  • Lire plusieurs pages : spicrawl_batch_submit met en file jusqu’à 10 000 URL. Suivez-le avec spicrawl_batch_status et spicrawl_batch_results.
  • Pages derrière une connexion : spicrawl_session_create conserve les cookies et le stockage d’un appel à l’autre.
  • Déboguer un échec : spicrawl_requests_list et spicrawl_request_get.
  • Vérifier l’usage : spicrawl_usage_summary et les autres outils d’utilisation. Ils nécessitent une clé avec le scope read.
  • Rechercher des informations : spicrawl_docs_search et spicrawl_docs_read cherchent et lisent la documentation de Spicrawl.

Un outil, spicrawl_browser_connect_url, est listé mais arrive bientôt. Sur spicrawl_scrape, l’argument de rendu est render, et non le js_render de l’API.

Bon à savoir

  • Pas de crawl. Spicrawl ne suit pas les liens et ne trouve pas de pages. Donnez les URL à l’agent.
  • Crédits par requête. Une récupération simple coûte 1 crédit. Le rendu JavaScript coûte 3. Le rendu navigateur complet coûte 8.
  • Les échecs sont gratuits. Une requête échouée coûte 0 crédit.
  • Le cache fait gagner du temps, pas des crédits. Un résultat en cache coûte autant que la récupération qui l’a stocké.
  • Plafonnez chaque appel. Définissez max_cost, et une requête qui pourrait coûter plus cher est refusée avant d’être exécutée.
  • Bientôt disponible : proxys gérés, mode furtif, navigateur distant et extraction par IA à partir d’un prompt en langage naturel. Aujourd’hui, vous pouvez apporter votre propre proxy.

Questions fréquentes

De quel package ai-je besoin ?

openai-agents. Définissez SPICRAWL_API_KEY et OPENAI_API_KEY avant d’exécuter l’exemple.

Comment limiter les outils que le modèle voit ?

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

Pourquoi ai-je une erreur 401 quand l’agent se connecte ?

L’en-tête est absent ou la clé est incorrecte. Construisez l’en-tête dans le code à partir de SPICRAWL_API_KEY et vérifiez que la variable est définie dans le processus qui exécute l’agent.

Que se passe-t-il quand un appel d’outil échoue ?

L’erreur parvient au modèle comme une erreur d’outil MCP avec le code de l’API. Les appels échoués coûtent 0 crédit.

Combien coûte chaque page ?

Une récupération simple coûte 1 crédit, le rendu JavaScript 3 et le rendu navigateur complet 8. Les requêtes échouées coûtent 0. Un résultat en cache coûte autant que la récupération qui l’a stocké. Demandez à l’agent de définir max_cost sur chaque requête pour qu’il ne dépense jamais plus que prévu.