Au-delà du vibe codingFaire passer les agents IA à l'échelle avec un retrieval infrastructure-first

La plupart des développeurs arrivent à faire scraper une page unique par un agent IA avec un prompt bien formulé. Demandez à Claude de récupérer le prix depuis cette URL, collez un lien, et vous obtenez généralement quelque chose d'exploitable en un seul tour.

Ce fonctionnement se casse vite dès que vous dépassez le stade du prototype, car au moment où vous passez d'une page à dix mille, vous cessez de vous battre contre les prompts pour vous battre contre l'infrastructure. Les mêmes défaillances reviennent sans cesse dans les tests de retrieval à grande échelle :

• Des agents qui consomment des pages CAPTCHA comme s'il s'agissait de vrai contenu.
• Des payloads HTML de 200 KB qui font exploser la consommation de tokens.
• Des retries qui multiplient les coûts d'inférence.
• Des refontes de frontend qui cassent silencieusement la logique d'extraction.
• Les mêmes URL crawlées encore et encore.

La plupart des défaillances d'agents IA sont des défaillances d'infrastructure déguisées en problèmes de prompting. Ce guide ne parle pas de meilleurs prompts. Il parle de construire la couche entre le web en direct et votre modèle : du retrieval Markdown normalisé via le Crawlbase Web MCP Server, des circuit breakers qui rejettent les réponses empoisonnées avant l'inférence, et Cloud Storage comme mémoire durable des agents. Chaque exemple ci-dessous a son équivalent exécutable dans le dépôt compagnon.

Pourquoi les agents IA cassent à grande échelle

Les agents IA échouent à grande échelle parce que le web public est bruyant, instable et coûteux à traiter directement pour un modèle de langage. Une page web moderne n'est pas seulement du contenu. Ce sont des bundles JavaScript, des payloads d'hydratation, des scripts d'analytics, des arbres DOM dupliqués, des bandeaux de cookies et de l'état de framework. Une page de tarifs qui paraît simple peut renvoyer bien plus de 200 KB de HTML brut avant toute normalisation, et l'essentiel n'a rien à voir avec ce dont l'agent a réellement besoin.

Beaucoup de pipelines d'agents déversent encore cette réponse entière directement dans la fenêtre de contexte, ce qui crée deux problèmes d'infrastructure distincts.

La taxe sur les tokens est le coût de transporter un markup frontend inutile à travers l'inférence. Chaque octet de retrieval superflu se convertit tôt ou tard en coût de tokens, en latence, en surcoût de retries et en pression mémoire. L'effondrement du contexte est la défaillance de raisonnement qui suit : le modèle perd sa focalisation sémantique parce qu'il est occupé à traiter du markup plutôt que du sens.

En pratique, cela produit des défaillances qui paraissent presque comiques isolément et coûteuses en cumulé. Des agents extraient des prix depuis des carrousels de recommandations, résument des bandeaux de cookies comme s'il s'agissait du contenu de la page, prennent du JSON d'hydratation pour des données produit, ou traitent une interstitielle CAPTCHA comme une réponse valide.

Pourquoi le Markdown surpasse le HTML brut

Le Markdown réduit la consommation de tokens et améliore la fiabilité de l'extraction parce qu'il supprime le bruit frontend tout en préservant la structure sémantique. Le HTML brut transporte des payloads JavaScript, des classes CSS, du markup de navigation, des scripts de tracking et des artefacts de framework dont le modèle n'a pas besoin. Le Markdown conserve ce dont le raisonnement dépend réellement : titres, paragraphes, listes, tableaux et liens.

La réduction exacte varie selon les sites, mais la direction reste constante : un ordre de grandeur de payload en moins pour la même information. Cela se traduit par des coûts de tokens plus bas, une inférence plus rapide, une extraction plus propre et un raisonnement plus stable, le tout grâce à un meilleur rapport signal/bruit dans la fenêtre de contexte.

C'est pourquoi le Web MCP Server expose un retrieval normalisé via crawl_markdown, le mécanisme même qui se cache derrière format=md dans la Crawling API. Avec la normalisation gérée en amont, le prompt peut rester court et précis :

Use crawl_markdown on https://example.com/pricing and return only:
plan names, monthly prices, and currency.
Do not paste raw HTML.
If the crawl fails, report the tool error.

Le principe sous-jacent : un modèle ne devrait jamais consommer directement des réponses arbitraires venues d'internet. Il devrait consommer des représentations sémantiques normalisées.

Ce qu'est le data plane de l'agent

Le data plane de l'agent est la couche d'infrastructure entre internet et le LLM. La plupart des équipes concentrent leur attention sur les prompts, les modèles et les frameworks d'agents, mais en production le goulot d'étranglement principal est presque toujours la fiabilité du retrieval. Le data plane prend en charge le retrieval, la validation, la normalisation, la persistance et la gouvernance du contexte, et il fait tout cela avant qu'un seul octet n'atteigne la couche de raisonnement.

Sans cette couche, les agents travaillent directement sur des pages web en direct et instables. La démo est superbe et la dégradation est rapide.

À mesure que les systèmes d'IA montent en charge, le point de blocage se déplace du prompting vers la fiabilité du retrieval, la gestion de la mémoire, l'efficacité du contexte et l'état déterministe. C'est exactement pour cela que la normalisation Markdown, la validation du retrieval et le stockage persistant cessent d'être des optimisations pour devenir de l'architecture.

Circuit breakers : valider avant l'inférence

Un circuit breaker empêche le retrieval empoisonné d'entrer dans la fenêtre de contexte, et en scraping de production cela compte plus qu'il n'y paraît, car un mauvais retrieval est généralement pire qu'un retrieval manquant. Une donnée manquante s'annonce d'elle-même. Une mauvaise donnée est résumée, stockée, puis sert de base à des décisions.

Le module circuit_breaker.py du dépôt compagnon implémente une validation fail-closed en amont de la couche de raisonnement :

def evaluate(
    result: CrawlResult,
    *,
    max_body_chars: int = DEFAULT_MAX_BODY_CHARS,
    expect_markdown: bool = True,
) -> CircuitDecision:

    if result.http_status != 200:
        return CircuitDecision(False, f"HTTP status {result.http_status}")

    if result.cb_status and result.cb_status != "200":
        return CircuitDecision(
            False,
            f"Crawlbase cb_status={result.cb_status}"
        )

    if not result.body.strip():
        return CircuitDecision(False, "empty body")

    if expect_markdown and not result.content_type.startswith("text/markdown"):
        return CircuitDecision(
            False,
            f"expected markdown, got {result.content_type}"
        )

    if len(result.body) > max_body_chars:
        return CircuitDecision(
            False,
            f"body exceeds {max_body_chars} chars"
        )

    return CircuitDecision(True, "ok")

Cette fonction est un pare-feu entre le web public et la fenêtre de contexte. Plutôt que de faire confiance à chaque réponse, elle vérifie le statut de transport, le cb_status Crawlbase, les corps vides, le type de contenu et la taille du payload avant que quoi que ce soit n'atteigne le modèle. À noter : cb_status est le nom actuel de l'en-tête de statut Crawlbase ; du code et des tutoriels plus anciens peuvent encore l'appeler pc_status.

C'est important parce que les systèmes anti-bot échouent rarement bruyamment. Une requête peut réussir au niveau transport tout en servant une page CAPTCHA, un document d'accès refusé, une interstitielle de challenge ou une coquille d'hydratation vide. Les modèles raisonneront avec assurance sur tout cela, à moins que la couche de retrieval ne les rejette d'abord.

Sans circuit breaker, la chaîne de défaillance en production est prévisible :

1. Le site cible renvoie une page CAPTCHA.
2. L'agent traite ce HTML comme du vrai contenu.
3. Les pipelines d'extraction stockent des données empoisonnées.
4. Les systèmes de surveillance signalent des changements qui n'ont jamais eu lieu.
5. Les boucles de retry multiplient à la fois les coûts de tokens et de crawl.

Un seul mauvais retrieval peut empoisonner tout un workflow multi-agents, et c'est pourquoi la validation doit se placer avant l'inférence et non après. La version exécutable se trouve dans l'implémentation du circuit breaker.

Pourquoi le stockage vaut mieux que le recrawl

Les agents en production devraient interroger leur mémoire avant d'interroger internet. La plupart des tutoriels d'agents traitent le web comme s'il était sans état ; les vrais systèmes ne peuvent pas se le permettre. Recrawler les mêmes URL en boucle augmente la dépense en tokens, déstabilise le retrieval, produit des sorties incohérentes et ajoute un surcoût de crawl qui n'apporte rien.

C'est là que Crawlbase Cloud Storage gagne sa place dans l'architecture. Le pipeline d'ingestion stocke des snapshots Markdown normalisés avec store=true au lieu de retraiter des pages en direct à chaque exécution :

params = {
    "token": token,
    "url": url,
    "format": "md",
    "md_readability": "true",
    "store": "true",
}

Le résultat est un workflow de retrieval basé sur le rid, où les agents s'échangent des références plutôt que des payloads complets. Au lieu de faire passer de gros documents dans le modèle à chaque étape, le système persiste le Markdown normalisé, les métadonnées de retrieval, les références rid et les estimations de tokens, puis récupère par référence via storage_get quand une étape a réellement besoin du contenu.

Il y a un deuxième bénéfice facile à manquer : le déterminisme. Le web en direct est non déterministe, entre les refontes de frontend, les tests A/B, la personnalisation et le churn ordinaire du DOM. Les snapshots adossés au stockage vous donnent une entrée figée sur laquelle raisonner, ce qui fait toute la différence entre un pipeline que vous pouvez déboguer et un pipeline que vous pouvez seulement observer.

Le workflow complet se trouve dans le script d'ingestion storage-first du dépôt compagnon.

Détecter les changements sans tout retraiter

Le stockage persistant rend la détection de changement radicalement moins coûteuse, parce que le système compare des snapshots normalisés au lieu de refaire passer des pages entières dans le modèle. Le script change_detection.py du dépôt compagnon compare le Markdown stocké à un nouveau crawl normalisé, et la comparaison est volontairement ennuyeuse :

prev_hash = hashlib.sha256(previous.encode("utf-8")).hexdigest()
curr_hash = hashlib.sha256(current.encode("utf-8")).hexdigest()

Si les deux hachages correspondent, le script signale UNCHANGED et s'arrête. Aucune passe de résumé ne s'exécute, aucune inférence en aval n'a lieu, et aucun token n'est dépensé. C'est tout l'intérêt du pattern : l'étape de raisonnement la moins chère est celle que vous n'exécutez jamais. La version exécutable est l'implémentation de la détection de changement.

Le dépôt compagnon du data plane

Le dépôt compagnon montre ces patterns fonctionnant ensemble dans un même pipeline de retrieval. Au lieu d'envoyer des pages web brutes dans le modèle, le workflow valide les réponses avant l'inférence, convertit les pages en Markdown normalisé, stocke des snapshots pour un retrieval ultérieur, et compare de façon déterministe le contenu stocké au contenu en direct. Trois modules le portent :

• circuit_breaker.py pour la validation fail-closed du retrieval.
• ingest.py pour l'ingestion Markdown storage-first.
• change_detection.py pour la comparaison de snapshots et les workflows de surveillance.

L'important, ce ne sont pas les scripts. C'est la forme : un lot d'URL entre, le circuit breaker rejette ce qui ne devrait jamais atteindre un modèle, les survivants sont normalisés en Markdown puis stockés, et l'agent lit ensuite de petites tranches par référence plutôt que de recrawler. Les agents devraient raisonner sur du retrieval validé, normalisé et persistant, pas sur des réponses arbitraires venues d'internet.

Connecter le Web MCP Server à Claude

Le Web MCP Server se branche directement sur Claude Desktop ou Claude Code. La documentation IA et MCP et le guide d'intégration Claude détaillent l'installation, les workflows Cloud Storage et les outils de retrieval. La configuration Claude Desktop est courte :

{
  "mcpServers": {
    "crawlbase": {
      "type": "stdio",
      "command": "npx",
      "args": ["@crawlbase/mcp@latest"],
      "env": {
        "CRAWLBASE_TOKEN": "YOUR_TOKEN",
        "CRAWLBASE_JS_TOKEN": "YOUR_JS_TOKEN"
      }
    }
  }
}

Après le redémarrage de Claude, les outils de retrieval deviennent disponibles dans l'environnement du modèle : crawl_markdown pour les récupérations normalisées, ainsi que storage_get, storage_list et storage_bulk_get pour relire ce que vous avez déjà crawlé. Les mêmes patterns d'infrastructure fonctionnent alors de façon interactive dans Claude ou de façon opérationnelle via des pipelines Python, ce qui est tout l'intérêt de les placer dans le data plane plutôt que dans un prompt.

Des patterns de production qui passent à l'échelle

Une poignée de règles sépare les systèmes de retrieval qui survivent à la production de ceux qui se contentent de bien démontrer.

Faites du Markdown le format par défaut

Traitez le HTML brut comme le repli, pas comme le format de raisonnement par défaut. La plupart des pages transportent bien plus de bruit frontend que de contenu, et ce bruit ajoute du coût en tokens sans améliorer la qualité de l'extraction. Le Markdown conserve la sémantique et jette l'encombrement, ce qui rend le raisonnement plus rapide, moins cher et plus stable.

Échouez en mode fermé

Un mauvais retrieval est pire qu'un retrieval manquant. Une page CAPTCHA, un blocage silencieux ou un rendu cassé peuvent renvoyer un HTTP 200 tout en injectant du poison dans le modèle. Rejetez le retrieval suspect à la frontière au lieu d'espérer que le modèle s'en aperçoive.

Interrogez la mémoire d'abord

Vérifiez le stockage avant de recrawler. Récupérer les mêmes pages en boucle génère de la dépense en tokens, des sorties instables et un surcoût de crawl dupliqué. Les snapshots persistants permettent aux agents de raisonner sur une entrée figée plutôt que mouvante.

Imposez des budgets de contexte

Les fenêtres de contexte sont une ressource d'infrastructure avec un prix. Les gros payloads augmentent ensemble le coût, la latence et l'instabilité du raisonnement : plafonnez donc la taille du payload avant que le contenu n'entre dans la fenêtre, pas après l'arrivée de la facture.

Séparez le retrieval du raisonnement

La validation et la normalisation ont leur place en amont du modèle. Découper le pipeline en retrieval, validation, normalization, persistence et reasoning vous donne une isolation nette des défaillances, des sorties plus stables et un système que vous pouvez réellement déboguer à grande échelle.

Ce qui passe vraiment à l'échelle

Le vibe coding suffit à faire fonctionner un agent sur une page. Le difficile commence quand le même workflow doit tourner sur des milliers de pages, en continu, sans supervision. À ce moment-là, la question n'est plus comment prompter le modèle, mais comment cesser de lui donner du retrieval bruyant, instable ou coûteux.

Les systèmes fiables convergent en général vers le même jeu de choix : du Markdown plutôt que du HTML brut, du stockage plutôt que du crawling sans état, des circuit breakers plutôt que des retries aveugles, des snapshots déterministes plutôt que de la navigation en direct, et de la validation avant l'inférence. À mesure que les agents montent en charge, ils se comportent moins comme des chatbots et davantage comme des systèmes distribués, et le goulot d'étranglement se déplace vers la fiabilité du retrieval, l'architecture mémoire, la normalisation, la persistance et la gouvernance des tokens.

Si vous construisez dans cette direction, nos guides sur les workflows d'agents IA avec le Web MCP Server et sur la construction d'un jeu de données de recherche IA montrent le même data plane appliqué à des tâches concrètes. La prochaine génération de systèmes d'IA ne se définira pas seulement par de meilleurs prompts. Elle se définira par une meilleure infrastructure de retrieval.

Questions fréquentes

Pourquoi les agents IA échouent-ils quand ils scrapent un grand nombre de pages ?

Les petites démos fonctionnent parce que le modèle compense discrètement un retrieval bruyant. À des volumes de crawl plus élevés, les agents se mettent à consommer des payloads HTML surdimensionnés, des pages CAPTCHA, du markup frontend dupliqué et des réponses en direct instables, ce qui produit un effondrement du contexte, des coûts de tokens gonflés et une extraction incohérente. La défaillance est dans le data plane, pas dans le prompt.

Pourquoi le Markdown est-il meilleur que le HTML pour les agents IA ?

Le Markdown préserve la structure sémantique tout en supprimant l'essentiel du bruit frontend, ce qui réduit la consommation de tokens, la pollution du contexte, la latence d'inférence et l'instabilité de l'extraction. La même page qui coûte 50K+ tokens en HTML brut tient généralement dans quelques milliers de tokens en Markdown, avec un meilleur rapport signal/bruit dans la fenêtre de contexte.

Qu'est-ce qu'un circuit breaker dans une infrastructure IA ?

C'est une barrière de validation qui s'exécute avant que le contenu n'atteigne le LLM. Elle rejette les erreurs HTTP, les valeurs de cb_status différentes de 200, les corps vides, les types de contenu inattendus et les payloads surdimensionnés, pour qu'un retrieval empoisonné ne devienne jamais une entrée de raisonnement. La politique est le fail closed : quand une réponse semble anormale, on la jette plutôt que de la résumer.

Pourquoi les agents devraient-ils utiliser le stockage plutôt que recrawler les pages ?

Le stockage persistant vous apporte un retrieval déterministe, la comparaison historique, des workflows rejouables, un coût de crawl plus bas et une consommation de tokens réduite. Les agents s'échangent des références rid plutôt que des documents complets et ne récupèrent le contenu que lorsqu'une étape en a besoin. Les agents en production devraient interroger leur mémoire avant d'interroger internet.

Qu'est-ce que le data plane de l'agent ?

Le data plane de l'agent est la couche d'infrastructure entre internet et le LLM. Il gère le retrieval, la validation, la normalisation, la persistance et la gouvernance du contexte, et il devient d'autant plus important qu'un système d'IA dépasse le stade du prototype.

NZ

Neil Zamora

Architecte senior · Crawlbase

Architecte senior chez Crawlbase, axé sur les systèmes derrière le crawling à grande échelle : rotation de proxys, résilience anti-bot et les API qui masquent cette complexité.

IK

Ian Kalvin

Ingénieur support technique · Crawlbase

Ingénieur support technique chez Crawlbase, il écrit depuis la première ligne de ce qui casse réellement en production, sur les configurations de scraping et de proxys.