Agent

Choisir le bon outil. Agent est le bon choix lorsque vous ne connaissez pas les URL ou que vous avez besoin d’une navigation autonome sur le web.

• Pour une URL unique déjà connue, le mode JSON sur /scrape est plus économique et synchrone.
• Comparaison complète : Choisir l’extracteur de données.

Firecrawl /agent est une API révolutionnaire qui recherche, parcourt et collecte des données depuis la plus grande variété de sites web, trouvant des données dans des endroits difficiles d’accès et les mettant au jour d’une manière qu’aucune autre API ne peut égaler. Elle accomplit en quelques minutes ce qui prendrait de nombreuses heures à un humain — une collecte de données de bout en bout, sans scripts ni intervention manuelle. Que vous ayez besoin d’un seul point de données ou de jeux de données complets à grande échelle, Firecrawl /agent s’occupe de récupérer vos données.

Considérez /agent comme une recherche approfondie de données, où qu’elles se trouvent !

Agent s’appuie sur tout ce qui fait la force de /extract et va encore plus loin :

• Aucune URL requise : Décrivez simplement ce dont vous avez besoin via le paramètre prompt. Les URL sont facultatives.
• Recherche web approfondie : Explore et navigue automatiquement en profondeur dans les sites pour trouver vos données
• Fiable et précis : Fonctionne avec un large éventail de requêtes et de cas d'utilisation
• Plus rapide : Traite plusieurs sources en parallèle pour des résultats plus rapides

Le seul paramètre requis est prompt. Décrivez simplement les données que vous souhaitez extraire. Pour une sortie structurée, fournissez un schéma JSON. Les SDK prennent en charge Pydantic (Python) et Zod (Node) pour des définitions de schémas avec typage sûr :

{  "success": true,  "status": "completed",  "data": {    "founders": [      {        "name": "Eric Ciarla",        "role": "Co-founder",        "background": "Previously at Mendable"      },      {        "name": "Nicolas Camara",        "role": "Co-founder",        "background": "Previously at Mendable"      },      {        "name": "Caleb Peffer",        "role": "Co-founder",        "background": "Previously at Mendable"      }    ]  },  "expiresAt": "2024-12-15T00:00:00.000Z",  "creditsUsed": 15}

Vous pouvez éventuellement fournir des URL pour cibler l’agent sur des pages spécifiques :

Les tâches d'agent s'exécutent de manière asynchrone. Lorsque vous soumettez une tâche, vous recevez un ID de tâche que vous pouvez utiliser pour consulter son statut :

• Méthode par défaut : agent() attend la fin de l'exécution et renvoie les résultats finaux
• Démarrer puis interroger : utilisez start_agent (Python) ou startAgent (Node) pour obtenir immédiatement un ID de tâche, puis interrogez avec get_agent_status / getAgentStatus
• Notification push au lieu d'interroger : transmettez un webhook lorsque vous démarrez la tâche afin de recevoir des événements d'agent au fur et à mesure que l'exécution progresse et se termine

{  "success": true,  "status": "processing",  "expiresAt": "2024-12-15T00:00:00.000Z"}

{  "success": true,  "status": "completed",  "data": {    "founders": [      {        "name": "Eric Ciarla",        "role": "Co-founder"      },      {        "name": "Nicolas Camara",        "role": "Co-founder"      },      {        "name": "Caleb Peffer",        "role": "Co-founder"      }    ]  },  "expiresAt": "2024-12-15T00:00:00.000Z",  "creditsUsed": 15}

GET /agent répertorie toutes les exécutions d’agent de votre équipe, de la plus récente à la plus ancienne, y compris celles lancées depuis le playground ou l’API. Chaque entrée contient l’ID de l’exécution, sa date de création, son état, un bref aperçu de la cible et les options avec lesquelles elle a été lancée.

Les résultats sont répartis en pages fixes de 20 exécutions. Lorsque d’autres pages sont disponibles, la réponse inclut une URL next ; transmettez son horodatage before pour récupérer la page suivante. Les méthodes du SDK ne gèrent pas automatiquement la pagination, ce qui vous permet de décider jusqu’où remonter.

Agent ne maintient pas de connexion de streaming ouverte. Il n'y a ni flux d'événements envoyés par le serveur ni WebSocket. Vous pouvez donc suivre une exécution en interrogeant sa trace ou en recevant des webhooks.

Lorsque vous triez vous-même les événements de trace, regroupez-les d'abord par agent.id : producerSequence est monotone pour chaque agent émetteur ; un tri global unique entremêle donc incorrectement les événements d'un orchestrateur et ceux de ses sous-agents. Des événements peuvent également arriver brièvement après l'événement terminal run.finished. Continuez donc à interroger pendant une courte période après celui-ci avant d'afficher l'état final.

Chaque exécution enregistre une trace d’exécution canonique — une suite ordonnée d’événements couvrant les appels d’outils, les résumés de raisonnement, les mises à jour de progression, les sessions de navigateur et les modifications des artefacts de sortie. Récupérez-la pour déboguer une exécution ou alimenter une interface de suivi de progression en temps réel :

Les événements de trace artifact.updated font référence à la sortie de travail de l’agent via snapshotId. Récupérez le contenu complet d’un instantané à l’aide du point de terminaison des instantanés :

Au fil de son exécution, une exécution écrit sa sortie de travail dans des artefacts, que vous pouvez récupérer une fois que vous avez obtenu sa trace. Chaque événement artifact.updated décrit une modification d'un artefact : artifact.kind vaut json, markdown, html, screenshot ou text, artifact.path indique où l'exécution l'a placé et artifact.snapshotId est l'identifiant à utiliser pour récupérer son contenu via GET /agent/{jobId}/snapshots/{snapshotId}. Le point de terminaison des instantanés renvoie ce contenu dans un champ snapshot sous forme de chaîne : pour les artefacts json, cette chaîne est encodée en JSON et doit être décodée ; pour les artefacts markdown, html et text, elle correspond directement au contenu.

Pour récupérer le contenu de page produit par une exécution, récupérez la trace, conservez les événements artifact.updated dont le kind vous intéresse, puis récupérez chaque instantané :

Deux points à connaître avant de vous appuyer sur ces données :

• Les artefacts constituent la sortie de l'exécution, et non une archive page par page. Ce qu'une exécution écrit dans un artefact dépend de la manière dont il traite votre prompt. Considérez donc l'ensemble des artefacts comme ce que cette exécution précise a produit, plutôt que comme un enregistrement garanti de chaque page qu'elle a ouverte.
• Les résultats des outils contiennent le reste. Chaque événement tool_call.finished inclut un champ result contenant ce que l'outil a renvoyé ; c'est là que figure le contenu qui n'a jamais été enregistré dans un artefact.

Vous pouvez partager des exécutions d’agent directement depuis l’Agent Playground. Les liens partagés sont publics — toute personne disposant du lien peut consulter les résultats et l’activité de l’exécution — et vous pouvez révoquer l’accès à tout moment pour désactiver le lien. Les pages partagées ne sont pas indexées par les moteurs de recherche.

Firecrawl Agent utilise Spark 2 — moins coûteux et plus rapide que les précédents modèles Spark 1, pour une précision comparable. Il s’agit du modèle par défaut : chaque exécution utilise spark-2, que vous définissiez ou non le paramètre model.

spark-2 couvre l’ensemble des tâches qui nécessitaient auparavant de choisir entre Mini et Pro, sans compromis entre précision et coût.

Points forts :

• Coût par exécution minimal
• Durée d’exécution la plus courte
• Précision comparable à celle de l’ancien modèle phare Spark 1
• Le seul modèle doté d’un budget de raisonnement : passez effort (low, medium ou high) pour contrôler l’effort de raisonnement

Le paramètre model est facultatif : chaque requête utilise spark-2 :

• Recherche : "Trouver les 5 principales startups d'IA et les montants de leurs financements"
• Analyse concurrentielle : "Comparer les offres tarifaires entre Slack et Microsoft Teams"
• Collecte de données : "Extraire les informations de contact depuis les sites web d'entreprises"
• Synthèse de contenu : "Résumer les derniers articles de blog sur le web scraping"

L’Agent Playground prend en charge le téléversement de fichiers CSV pour le traitement par lots. Votre fichier CSV peut contenir une ou plusieurs colonnes de données d’entrée. Par exemple, une seule colonne de noms d’entreprises, ou plusieurs colonnes comme le nom de l’entreprise, le produit et l’URL du site Web. Chaque ligne représente un élément que l’agent doit traiter.

Téléversez votre fichier CSV, puis ajoutez des colonnes de sortie à l’aide du bouton "+" dans l’en-tête de la grille. Chaque colonne a son propre prompt — cliquez sur l’en-tête d’une colonne pour décrire ce que l’agent doit trouver pour ce champ (p. ex., "Nom du PDG ou du fondateur", "Montant total des financements levés"). Cliquez sur Run, et l’agent traite chaque ligne en parallèle en renseignant les résultats.

Si les tâches d’agent de votre agent échouent ou renvoient des résultats inattendus, utilisez l’API Ask pour un débogage assisté par agent. Décrivez le problème et obtenez une réponse vérifiée, accompagnée de paramètres de correction que vous pouvez appliquer directement :

curl -X POST https://api.firecrawl.dev/v2/support/ask \  -H "Authorization: Bearer fc-YOUR_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "question": "my agent returned incomplete results"  }'

Consultez la documentation Ask pour plus de détails et des exemples d’intégration.

Consultez la Référence de l'API Agent pour plus de détails.

Vous avez des commentaires ou besoin d'aide ? Envoyez un e-mail à help@firecrawl.com.

Firecrawl Agent utilise une facturation dynamique qui s’adapte à la complexité de votre demande d’extraction de données. Vous payez en fonction du travail réellement effectué par Firecrawl Agent, ce qui garantit une tarification équitable, que vous extrayiez des données simples ou des informations structurées complexes provenant de plusieurs sources.

La tarification de l’agent est dynamique et basée sur les crédits pendant la Research Preview :

• Les extractions simples (comme les informations de contact à partir d'une seule page) consomment généralement moins de crédits et coûtent moins cher
• Les tâches de recherche complexes (comme une analyse concurrentielle sur plusieurs domaines) consomment plus de crédits mais reflètent mieux l’effort total requis
• Une transparence totale sur l’utilisation vous montre exactement combien de crédits chaque requête a consommé
• La conversion de crédits convertit automatiquement l'utilisation de crédits par l’agent en crédits pour une facturation simplifiée

Si vous exécutez plusieurs agents en parallèle avec Spark-1 Fast, les coûts sont beaucoup plus prévisibles : 10 crédits par cellule.

Tous les utilisateurs bénéficient de 5 exécutions gratuites par jour, utilisables depuis le playground ou l'API, pour explorer les fonctionnalités d'Agent sans frais.

L'utilisation supplémentaire est facturée en fonction de la consommation de crédits et convertie en crédits.

Agent peut être coûteux, mais il existe plusieurs moyens de réduire les coûts :

• Commencez par des exécutions gratuites : utilisez vos 5 requêtes gratuites quotidiennes pour comprendre la tarification
• Définissez un paramètre maxCredits : limitez vos dépenses en définissant un nombre maximal de crédits que vous êtes prêt à dépenser. Le tableau de bord plafonne cette valeur à 2 500 crédits ; pour définir une limite plus élevée, utilisez directement le paramètre maxCredits via l’API (remarque : les valeurs supérieures à 2 500 sont toujours facturées comme des requêtes payantes)
• Optimisez les prompts : des prompts plus spécifiques utilisent souvent moins de crédits
• Décomposez les tâches volumineuses en exécutions plus petites : une seule exécution d’agent renvoie environ 150-200 lignes de donnée structurée. Pour les tâches d’extraction volumineuses, répartissez-les par catégorie, région ou lot d’URL (3-5 URL par exécution), puis fusionnez les résultats. Cela permet également de maintenir chaque exécution bien en dessous de la limite maxCredits.
• Surveillez votre utilisation : suivez votre consommation via le tableau de bord
• Définissez des attentes claires : des recherches complexes couvrant plusieurs domaines utiliseront plus de crédits que de simples extractions sur une seule page

Essayez Agent dès maintenant sur firecrawl.dev/app/agent pour voir comment l’utilisation des crédits évolue selon vos cas d’usage spécifiques.

Êtes-vous un agent IA qui a besoin d’une clé API Firecrawl ? Consultez firecrawl.dev/agent-onboarding/SKILL.md pour obtenir les instructions d’intégration automatisée.