Comment Utiliser l'API Cloud du Navigateur

Ce tutoriel vous expliquera tout ce que vous devez savoir pour exploiter la puissance de l'automatisation de navigateur basée sur l'IA. Que vous cherchiez à automatiser l'extraction de données, à tester vos applications web ou à créer des outils de surveillance sophistiqués, ce guide vous fournira les connaissances et les exemples pour commencer.

Qu'est-ce que Browser Use Cloud ?

Browser Use Cloud est une plateforme puissante qui vous permet de créer et de gérer des agents d'automatisation de navigateur intelligents de manière programmatique. Imaginez avoir une flotte d'assistants virtuels capables de naviguer sur le web, d'interagir avec des sites web et d'effectuer des tâches complexes en votre nom.

Au cœur de la plateforme se trouve le concept de "tâche". Une tâche est un ensemble d'instructions que vous fournissez à un agent en langage naturel. Par exemple, vous pourriez donner à un agent une tâche comme : "Allez sur hacker-news.com, trouvez les 5 meilleurs articles, et enregistrez leurs titres et URL dans un fichier." L'agent utilisera alors un grand modèle linguistique (LLM) pour comprendre et exécuter ces instructions dans un environnement de navigateur réel.

L'une des fonctionnalités les plus intéressantes de Browser Use Cloud est la boucle de rétroaction en temps réel. Chaque tâche que vous créez est associée à une live_url. Cette URL fournit un aperçu interactif en direct de ce que fait l'agent. Vous pouvez regarder l'agent naviguer en temps réel et même prendre le contrôle si nécessaire. Cela rend le débogage et la surveillance incroyablement intuitifs.

Obtenir Votre Clé API

Avant de pouvoir commencer à créer des agents, vous aurez besoin d'une clé API. La clé API authentifie vos requêtes et les lie à votre compte.

<Note> Pour obtenir votre clé API, vous devez avoir un abonnement actif à Browser Use Cloud. Vous pouvez gérer votre abonnement et obtenir votre clé API depuis la page de facturation : cloud.browser-use.com/billing. </Note>

Une fois que vous avez votre clé API, assurez-vous de la garder en sécurité. Traitez-la comme un mot de passe et ne l'exposez jamais dans du code côté client ni ne la commitez dans le contrôle de version. Il est préférable de la stocker dans une variable d'environnement sécurisée.

export BROWSER_USE_API_KEY="your_api_key_here"

Comprendre le Modèle de Tarification

L'API Browser Use Cloud a un modèle de tarification simple, basé sur la consommation. Cela garantit que vous ne payez que ce que vous utilisez, ce qui le rend rentable pour les projets de petite et de grande envergure. La tarification se compose de deux parties principales :

1. Coût d'Initialisation de Tâche : Un forfait de 0,01 $ est facturé pour chaque tâche que vous démarrez. Cela couvre le coût de mise en place de l'environnement de navigateur pour votre agent.
2. Coût par Étape de Tâche : C'est le coût pour chaque action ou "étape" que l'agent effectue. Le coût par étape dépend du LLM que vous choisissez pour alimenter votre agent.

Tarification des Étapes LLM

Différents LLM ont des capacités et des prix différents. Vous pouvez choisir le modèle qui correspond le mieux à vos besoins en termes de performances et de coût. Voici une répartition du coût par étape pour chaque modèle disponible :

Exemple de Calcul de Coût

Imaginons que vous souhaitiez automatiser une tâche impliquant de vous connecter à un site web, de naviguer vers une page spécifique et d'extraire certaines données. Vous estimez que cela prendra environ 15 étapes. Si vous choisissez d'utiliser le puissant modèle GPT-4o, le coût total serait calculé comme suit :

• Initialisation de Tâche : 0,01 $
• Étapes de Tâche : 15 étapes × 0,03 $/étape = 0,45 $
• Coût Total : 0,01 $ + 0,45 $ = 0,46 $

Cette tarification transparente vous permet de prévoir et de contrôler vos coûts efficacement.

Créer Votre Premier Agent : Un Exemple "Bonjour, Monde !"

Maintenant, passons à la partie passionnante ! Créons votre premier agent d'automatisation de navigateur. Nous allons commencer par une tâche très simple : aller sur Google et rechercher "Browser Use".

Nous utiliserons curl pour effectuer une requête POST vers le point de terminaison /api/v1/run-task. C'est le point de terminaison principal pour créer de nouvelles tâches.

curl -X POST <https://api.browser-use.com/api/v1/run-task> \\\\
  -H "Authorization: Bearer $BROWSER_USE_API_KEY" \\\\
  -H "Content-Type: application/json" \\\\
  -d '{
    "task": "Go to google.com and search for Browser Use"
  }'

Décortiquons cette commande :

• curl -X POST ... : Nous envoyons une requête HTTP POST à l'URL spécifiée.
• H "Authorization: Bearer $BROWSER_USE_API_KEY" : C'est l'en-tête d'authentification. Il inclut votre clé API. Nous utilisons la variable d'environnement que nous avons définie précédemment.
• H "Content-Type: application/json" : Cet en-tête indique à l'API que nous envoyons des données au format JSON.
• d '{ "task": "..." }' : C'est le corps de notre requête. Le champ task contient les instructions en langage naturel pour notre agent.

Comprendre la Réponse de l'API

Lorsque vous envoyez cette requête, l'API répondra avec un objet JSON contenant des informations sur la tâche nouvellement créée. Voici un exemple de ce à quoi pourrait ressembler cette réponse :

{
  "task_id": "ts_2a9b4e7c-1d0f-4g8h-9i1j-k2l3m4n5o6p7",
  "status": "running",
  "live_url": "<https://previews.browser-use.com/ts_2a9b4e7c-1d0f-4g8h-9i1j-k2l3m4n5o6p7>"
}

• task_id : C'est un identifiant unique pour votre tâche. Vous utiliserez cet ID pour gérer la tâche ultérieurement (par exemple, pour la mettre en pause, la reprendre ou l'arrêter).
• status : Indique l'état actuel de la tâche. Il sera running (en cours d'exécution) initialement.
• live_url : C'est l'URL de l'aperçu en direct. Copiez et collez cette URL dans votre navigateur pour voir votre agent en action !

Aperçus Interactifs en Direct

La live_url est l'une des fonctionnalités les plus puissantes de Browser Use Cloud. Ce n'est pas seulement un flux vidéo en lecture seule ; c'est une session entièrement interactive.

Vous pouvez intégrer la live_url directement dans vos propres applications en utilisant un iframe. Cela vous permet de construire des tableaux de bord personnalisés et des outils de surveillance qui incluent une vue en temps réel de vos agents.

Voici un simple extrait HTML pour intégrer l'aperçu en direct :

<!DOCTYPE html>
<html>
<head>
  <title>Agent Live Preview</title>
  <style>
    body, html { margin: 0; padding: 0; height: 100%; overflow: hidden; }
    iframe { width: 100%; height: 100%; border: none; }
  </style>
</head>
<body>
  <iframe src="YOUR_LIVE_URL_HERE"></iframe>
</body>
</html>

Remplacez YOUR_LIVE_URL_HERE par la live_url de la réponse de l'API. Lorsque vous ouvrez ce fichier HTML dans un navigateur, vous verrez l'écran de l'agent. Vous pouvez cliquer, taper et faire défiler comme si vous naviguiez sur votre propre ordinateur. C'est incroyablement utile pour :

• Débogage : Si un agent reste bloqué, vous pouvez immédiatement voir pourquoi et ce qui est affiché sur son écran.
• Intervention Manuelle : Si une tâche nécessite une étape difficile à automatiser (comme résoudre un CAPTCHA complexe), vous pouvez prendre le relais, effectuer l'étape manuellement, puis laisser l'agent reprendre son travail.
• Démonstrations : C'est un excellent moyen de montrer aux parties prenantes ce que fait votre automatisation.

Gérer le Cycle de Vie de la Tâche

Une fois qu'une tâche est en cours d'exécution, vous avez un contrôle total sur son cycle de vie. Vous pouvez mettre en pause, reprendre et arrêter les tâches à l'aide de l'API. Vous aurez besoin du task_id pour toutes les opérations de gestion.

Mettre en Pause et Reprendre une Tâche

Il existe de nombreuses raisons pour lesquelles vous pourriez vouloir mettre une tâche en pause. Peut-être avez-vous besoin d'inspecter manuellement la page web, ou peut-être voulez-vous attendre qu'un événement externe se produise avant de continuer.

Pour mettre une tâche en pause, envoyez une requête POST au point de terminaison /api/v1/pause-task :

curl -X POST <https://api.browser-use.com/api/v1/pause-task> \\\\
  -H "Authorization: Bearer $BROWSER_USE_API_KEY" \\\\
  -H "Content-Type: application/json" \\\\
  -d '{
    "task_id": "YOUR_TASK_ID_HERE"
  }'

L'agent terminera son étape actuelle, puis entrera dans un état paused (en pause).

Pour reprendre la tâche, envoyez une requête POST au point de terminaison /api/v1/resume-task :

curl -X POST <https://api.browser-use.com/api/v1/resume-task> \\\\
  -H "Authorization: Bearer $BROWSER_USE_API_KEY" \\\\
  -H "Content-Type: application/json" \\\\
  -d '{
    "task_id": "YOUR_TASK_ID_HERE"
  }'

L'agent reprendra exactement là où il s'était arrêté.

Arrêter une Tâche

Si vous souhaitez terminer définitivement une tâche, vous pouvez utiliser le point de terminaison /api/v1/stop-task. C'est utile si la tâche est terminée, a échoué ou n'est plus nécessaire.

curl -X POST <https://api.browser-use.com/api/v1/stop-task> \\\\
  -H "Authorization: Bearer $BROWSER_USE_API_KEY" \\\\
  -H "Content-Type: application/json" \\\\
  -d '{
    "task_id": "YOUR_TASK_ID_HERE"
  }'

<Note> Une fois qu'une tâche est arrêtée, elle ne peut pas être reprise. L'environnement de navigateur est détruit et toutes les ressources associées sont nettoyées. </Note>

Création de Tâches Avancées

L'exemple "Bonjour, Monde !" n'était qu'un début. Le point de terminaison run-task prend en charge plus qu'une simple chaîne task. Vous pouvez personnaliser le comportement de votre agent en fournissant des paramètres supplémentaires.

Choisir un LLM

Comme nous l'avons vu dans la section sur la tarification, vous pouvez choisir parmi plusieurs LLM différents pour alimenter votre agent. Vous pouvez spécifier le modèle dans la requête run-task en utilisant le paramètre model.

Par exemple, pour utiliser le modèle Claude 3.7 Sonnet, vous feriez la requête suivante :

curl -X POST <https://api.browser-use.com/api/v1/run-task> \\\\
  -H "Authorization: Bearer $BROWSER_USE_API_KEY" \\\\
  -H "Content-Type: application/json" \\\\
  -d '{
    "task": "Go to reddit.com/r/programming and find the top post of the day.",
    "model": "claude-3.7-sonnet-20250219"
  }'

Si vous ne spécifiez pas de modèle, l'API utilisera un modèle par défaut, qui est généralement une option rentable et performante comme GPT-4o mini.

Construire Votre Propre Client

Bien que curl soit excellent pour des tests simples, vous voudrez probablement intégrer l'API Browser Use Cloud dans vos applications en utilisant une bibliothèque cliente appropriée. La meilleure façon de le faire est d'utiliser notre spécification OpenAPI pour générer un client typé.

La spécification OpenAPI est une manière standardisée de décrire les API REST. Vous pouvez trouver notre spécification ici : http://api.browser-use.com/openapi.json.

Génération de Client Python

Pour les développeurs Python, nous recommandons openapi-python-client. Il génère un client moderne, orienté asynchrone, avec des annotations de type complètes.

Tout d'abord, installez l'outil de génération :

# We recommend using pipx to keep your global environment clean
pipx install openapi-python-client --include-deps

Maintenant, générez le client :

openapi-python-client generate --url <http://api.browser-use.com/openapi.json>

Cela créera un nouveau répertoire contenant votre package client Python. Vous pouvez l'installer en utilisant pip :

pip install .

Vous pouvez maintenant utiliser le client dans votre code Python :

import asyncio
from browser_use_api import Client
from browser_use_api.models import RunTaskRequest

async def main():
    client = Client(base_url="<https://api.browser-use.com/api/v1>")
    request = RunTaskRequest(task="Go to ycombinator.com and list the top 3 companies.")

    response = await client.run_task.api_v1_run_task_post(
        client=client,
        json_body=request,
        headers={"Authorization": f"Bearer {YOUR_API_KEY}"}
    )

    if response:
        print(f"Task created with ID: {response.task_id}")
        print(f"Live URL: {response.live_url}")

if __name__ == "__main__":
    asyncio.run(main())

Génération de Client TypeScript/JavaScript

Pour les projets frontend ou Node.js, openapi-typescript est un excellent outil pour générer des définitions de type TypeScript à partir de la spécification OpenAPI.

Tout d'abord, installez le générateur en tant que dépendance de développement :

npm install -D openapi-typescript

Ensuite, exécutez le générateur :

npx openapi-typescript <http://api.browser-use.com/openapi.json> -o src/browser-use-api.ts

Cela créera un seul fichier, src/browser-use-api.ts, contenant toutes les définitions de type pour l'API. Vous pourrez ensuite utiliser ces types avec votre client HTTP préféré, comme fetch ou axios, pour effectuer des requêtes typées.

Voici un exemple utilisant fetch dans un projet TypeScript :

import { paths } from './src/browser-use-api';

const API_URL = "<https://api.browser-use.com/api/v1>";

type RunTaskRequest = paths["/run-task"]["post"]["requestBody"]["content"]["application/json"];
type RunTaskResponse = paths["/run-task"]["post"]["responses"]["200"]["content"]["application/json"];

async function createTask(task: string, apiKey: string): Promise<RunTaskResponse> {
  const body: RunTaskRequest = { task };

  const response = await fetch(`${API_URL}/run-task`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${apiKey}`,
    },
    body: JSON.stringify(body),
  });

  if (!response.ok) {
    throw new Error(`API request failed with status ${response.status}`);
  }

  return response.json() as Promise<RunTaskResponse>;
}

async function run() {
  const apiKey = process.env.BROWSER_USE_API_KEY;
  if (!apiKey) {
    throw new Error("API key not found in environment variables.");
  }

  try {
    const result = await createTask("Find the current weather in New York City.", apiKey);
    console.log("Task created:", result);
  } catch (error) {
    console.error("Failed to create task:", error);
  }
}

run();