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
Installez
openai-agents.Définissez
SPICRAWL_API_KEYetOPENAI_API_KEY.Ouvrez
MCPServerStreamableHttpavec l’URL et l’en-têteAuthorizationdansparams.Utilisez
create_static_tool_filterpour limiter les outils que le modèle voit, et transmettez le serveur à votreAgent.
Exemple : lire une page de tarifs
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_scraperenvoie du Markdown (par défaut), du texte, du HTML, du JSON ou un PDF. - Lire plusieurs pages :
spicrawl_batch_submitmet en file jusqu’à 10 000 URL. Suivez-le avecspicrawl_batch_statusetspicrawl_batch_results. - Pages derrière une connexion :
spicrawl_session_createconserve les cookies et le stockage d’un appel à l’autre. - Déboguer un échec :
spicrawl_requests_listetspicrawl_request_get. - Vérifier l’usage :
spicrawl_usage_summaryet les autres outils d’utilisation. Ils nécessitent une clé avec le scoperead. - Rechercher des informations :
spicrawl_docs_searchetspicrawl_docs_readcherchent 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.