# Browser Sandbox > Un Browser Sandbox sécurisé où les agents peuvent interagir avec le web. import LaunchCURL from "/snippets/fr/v2/browser/launch/curl.mdx"; import LaunchJS from "/snippets/fr/v2/browser/launch/js.mdx"; import LaunchOutput from "/snippets/fr/v2/browser/launch/output.mdx"; import ExecuteCURL from "/snippets/fr/v2/browser/execute/curl.mdx"; import ExecuteCURLBash from "/snippets/fr/v2/browser/execute/curl-bash.mdx"; import ExecuteJS from "/snippets/fr/v2/browser/execute/js.mdx"; import ExecuteOutput from "/snippets/fr/v2/browser/execute/output.mdx"; import CloseCURL from "/snippets/fr/v2/browser/close/curl.mdx"; import CloseJS from "/snippets/fr/v2/browser/close/js.mdx"; import ListCURL from "/snippets/fr/v2/browser/list/curl.mdx"; import ListJS from "/snippets/fr/v2/browser/list/js.mdx"; import ListOutput from "/snippets/fr/v2/browser/list/output.mdx"; import QuickstartCURL from "/snippets/fr/v2/browser/quickstart/curl.mdx"; import QuickstartJS from "/snippets/fr/v2/browser/quickstart/js.mdx"; import PlaywrightJS from "/snippets/fr/v2/browser/playwright/js.mdx"; import PlaywrightPython from "/snippets/fr/v2/browser/playwright/python.mdx"; import QuickstartCLI from "/snippets/fr/v2/browser/quickstart/cli.mdx"; import LaunchCLI from "/snippets/fr/v2/browser/launch/cli.mdx"; import ExecuteCLI from "/snippets/fr/v2/browser/execute/cli.mdx"; import ListCLI from "/snippets/fr/v2/browser/list/cli.mdx"; import CloseCLI from "/snippets/fr/v2/browser/close/cli.mdx"; import QuickstartPython from "/snippets/fr/v2/browser/quickstart/python.mdx"; import PersistentCURL from "/snippets/fr/v2/browser/persistent/curl.mdx"; import PersistentJS from "/snippets/fr/v2/browser/persistent/js.mdx"; import PersistentPython from "/snippets/fr/v2/browser/persistent/python.mdx"; import PersistentCLI from "/snippets/fr/v2/browser/persistent/cli.mdx"; import LaunchPython from "/snippets/fr/v2/browser/launch/python.mdx"; import ExecutePython from "/snippets/fr/v2/browser/execute/python.mdx"; import ListPython from "/snippets/fr/v2/browser/list/python.mdx"; import ClosePython from "/snippets/fr/v2/browser/close/python.mdx"; Pour les workflows d’agents, utilisez [Interact](/fr/features/interact). Interact est le parcours CLI/MCP pris en charge et peut être piloté avec des prompts ou du code après un scrape ; MCP permet aussi d’ouvrir directement depuis une URL. | Surface | À utiliser pour | Point d’entrée | Surface agent | | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | | Browser Sandbox | Sessions de navigateur autonomes pour les utilisateurs de l’API et des SDKs qui ont besoin d’un bac à sable, d’une URL CDP, d’une vue en direct ou d’une gestion persistante du cycle de vie des sessions | `POST /v2/interact` | API et SDKs ; la commande CLI de navigateur masquée est héritée | | Interact | Agir sur une page scrapée ; MCP peut aussi ouvrir directement depuis une URL via le mode URL `firecrawl_interact` | `POST /v2/scrape/{scrapeId}/interact`, CLI `interact` après scrape, ou MCP `firecrawl_interact` | Recommandé pour les workflows d’agents CLI/MCP | Firecrawl Browser Sandbox offre aux utilisateurs de l’API et des SDKs un environnement de navigateur sécurisé où les agents peuvent interagir avec le web. Remplissez des formulaires, cliquez sur des boutons, authentifiez-vous, et plus encore. Aucune configuration locale, aucune installation de Chromium, aucun problème de compatibilité de driver. Agent browser et Playwright sont préinstallés. Disponible via l’[API](/fr/api-reference/endpoint/browser-create), le [SDK Node](/fr/sdks/node#browser), le [SDK Python](/fr/sdks/python#browser) et le [Vercel AI SDK](/fr/developer-guides/llm-sdks-and-frameworks/vercel-ai-sdk). La commande CLI masquée `firecrawl browser` est héritée ; les workflows d’agents CLI et MCP doivent utiliser scrape + interact à la place. Pour ajouter la prise en charge d’Interact à un agent de codage IA (Claude Code, Codex, Open Code, Cursor, etc.), installez la compétence Firecrawl : ```bash npx -y firecrawl-cli@latest init --all --browser ``` Chaque session s’exécute dans un bac à sable isolé, jetable ou persistant, qui passe à l’échelle sans avoir à gérer d’infrastructure.
## Démarrage rapide
Créez une session, exécutez du code, puis fermez-la : * **Aucune installation de driver requise** — Pas de binaire Chromium, pas de `playwright install`, pas de problèmes de compatibilité de driver * **Python, JavaScript & Bash** — Envoyez du code via l'API, la CLI ou le SDK et récupérez les résultats. Les trois langages s'exécutent à distance dans la sandbox * **agent-browser** — CLI préinstallée avec plus de 60 commandes. Les agents d'IA écrivent de simples commandes bash au lieu de code Playwright * **Playwright préinstallé** — Playwright est déjà disponible dans la sandbox. Les agents peuvent écrire du code Playwright s’ils le préfèrent. * **Accès CDP** — Connectez votre propre instance Playwright via WebSocket lorsque vous avez besoin d’un contrôle total * **Vue en direct** — Suivez les sessions en temps réel via une URL de flux intégrable * **Vue en direct interactive** — Permettez aux utilisateurs d’interagir directement avec le navigateur via un flux en direct interactif intégrable
## Lancer une session
Retourne un ID de session, une URL CDP et une URL de visualisation en direct.
## Exécuter le code
Exécutez du code Python, JavaScript ou bash dans votre session. Output est renvoyé via `stdout` ; pour Node.js, la valeur de la dernière expression est également disponible dans `result`.
### Gestion des téléchargements de fichiers
Les fichiers téléchargés au cours d'une session peuvent être capturés et renvoyés en base64. Utilisez l'API de téléchargement de Playwright via le point de terminaison `execute` : ```python Python import base64 async with page.expect_download() as download_info: await page.click('a#download-link') # Cliquez sur l'élément qui déclenche le téléchargement download = download_info.value path = await download.path() # Facultatif : enregistrer le fichier à un emplacement connu # await download.save_as('/tmp/myfile.pdf') # Lire le contenu du fichier et l'afficher en base64 with open(path, "rb") as f: content = base64.b64encode(f.read()).decode() print(content) ``` ```javascript Node // Récupérer l'URL de téléchargement à partir de l'élément de lien const href = await page.getAttribute('a#download-link', 'href'); // Récupérer le fichier dans le contexte du navigateur et le convertir en base64 const b64 = await page.evaluate(async (url) => { const resp = await fetch(url); const blob = await resp.blob(); return new Promise((resolve) => { const reader = new FileReader(); reader.onloadend = () => resolve(reader.result.split(',')[1]); reader.readAsDataURL(blob); }); }, href); process.stdout.write(b64); ``` Le système de fichiers du bac à sable est éphémère : les fichiers téléchargés sont perdus à la fin de la session. Pour les conserver, lisez leur contenu pendant la session et enregistrez-le dans votre propre espace de stockage. Les profils persistants conservent l'état du navigateur (cookies, localStorage), mais pas les fichiers sur le disque.
## agent-browser (Mode Bash)
[agent-browser](https://github.com/vercel-labs/agent-browser) est une CLI de navigateur headless préinstallée dans chaque sandbox. Au lieu d'écrire du code Playwright, les agents envoient de simples commandes Bash. La CLI injecte automatiquement `--cdp` pour permettre à agent-browser de se connecter à votre session active. Les exemples de CLI `firecrawl browser` ci-dessous concernent les sessions Browser Sandbox héritées. Pour les workflows d'agents en CLI/MCP, privilégiez `firecrawl interact` ou l'outil MCP `firecrawl_interact`.
### Raccourci
La méthode la plus rapide pour utiliser `browser`. Le raccourci et `execute` envoient tous les deux des commandes à `agent-browser` automatiquement. Le raccourci se contente d’omettre `execute` et de lancer automatiquement une session si nécessaire : ```bash firecrawl browser "open https://example.com" firecrawl browser "snapshot" firecrawl browser "click @e5" ```
### CLI
La forme explicite utilise `execute`. Les commandes sont envoyées automatiquement à `agent-browser` : vous n'avez pas besoin de saisir `agent-browser` ni d'utiliser `--bash` : ```bash Navigation & capture firecrawl browser execute "open https://example.com" firecrawl browser execute "snapshot" ``` ```bash Interaction firecrawl browser execute "click @e5" firecrawl browser execute "fill @e3 'search query'" firecrawl browser execute "scrape" ```
### API & SDK
Utilisez `language: "bash"` pour exécuter des commandes agent-browser via l'API ou les SDK : ```bash cURL curl -X POST "https://api.firecrawl.dev/v2/interact/YOUR_SESSION_ID/execute" \ -H "Authorization: Bearer $FIRECRAWL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "code": "agent-browser snapshot", "language": "bash" }' ``` ```javascript Node const result = await app.browserExecute(sessionId, { code: "agent-browser snapshot", language: "bash", }); ``` ```python Python result = app.browser_execute( session_id, code="agent-browser snapshot", language="bash", ) ```
## Gestion des sessions
### Sessions persistantes
Par défaut, chaque session de navigateur démarre dans un état vierge. Avec `profile`, vous pouvez enregistrer et réutiliser l’état du navigateur entre les sessions. C’est utile pour rester connecté et conserver les préférences. Pour enregistrer ou sélectionner un profil, utilisez le paramètre `profile` lors de la création d’une session. | Paramètre | Valeur par défaut | Description | |-----------|-------------------|-------------| | `name` | — | Un nom pour le profil persistant. Les sessions portant le même nom partagent le stockage. | | `saveChanges` | `true` | Lorsque `true`, l’état du navigateur est enregistré dans le profil à la clôture. Définissez `false` pour charger les données existantes sans écrire — utile lorsque vous avez besoin de plusieurs lecteurs simultanés. | Une seule session peut enregistrer dans un profil à la fois. Si une autre session enregistre déjà, vous recevrez une erreur `409`. Vous pouvez quand même ouvrir le même profil avec `saveChanges: false`, ou réessayer plus tard. L’état de la session du navigateur n’est enregistré qu’une fois la session close. Nous vous recommandons donc de clore la session du navigateur lorsque vous avez terminé afin qu’elle puisse être réutilisée. Une fois une session close, son ID de session n’est plus valide — vous ne pouvez pas le réutiliser. Créez plutôt une nouvelle session avec le même nom de profil et utilisez le nouvel ID de session renvoyé dans la réponse. Pour l’enregistrer et la clore :
### Lister les sessions
### Configuration du TTL
Les sessions ont deux paramètres de TTL : | Paramètre | Valeur par défaut | Description | |-----------|-------------------|-------------| | `ttl` | 600s (10 min) | Durée de vie maximale de la session (30-3600s) | | `activityTtl` | 300s (5 min) | Fermeture automatique après inactivité (10-3600s) |
### Clore une session
## Vue en direct
Chaque session renvoie un `liveViewUrl` dans la réponse, que vous pouvez intégrer pour observer le navigateur en temps réel. Pratique pour le débogage, les démonstrations ou la création d’interfaces utilisateur pilotées par le navigateur. ```json Response { "success": true, "id": "550e8400-e29b-41d4-a716-446655440000", "cdpUrl": "wss://browser.firecrawl.dev/cdp/550e8400...?token=abc123...", "liveViewUrl": "https://liveview.firecrawl.dev/...", "interactiveLiveViewUrl": "https://liveview.firecrawl.dev/...", "expiresAt": "2025-01-15T10:40:00Z" } ``` ```html