Brave Search OpenClaw

Introduction

Un agent sans accès web travaille avec une mémoire figée du monde. Dès que vous lui demandez une veille produit, une vérification de source ou une recherche d'actualité, cette limite devient bloquante. Ajouter Brave Search à OpenClaw permet de récupérer des résultats frais, structurés et exploitables par vos workflows. Dans ce tutoriel, vous allez voir comment obtenir la clé API, créer un skill Python complet, l'activer dans votre agent et traiter proprement les résultats. Si vous débutez avec l'architecture des outils, commencez par comprendre les skills OpenClaw.

Résumé rapide

1. Créez une clé Brave Search API, avec un tier gratuit de 2 000 requêtes par mois.
2. Développez un skill Python qui appelle https://api.search.brave.com/res/v1/web/search.
3. Retournez une sortie normalisée pour que l'agent puisse raisonner sur les résultats.
4. Déclarez le skill dans votre configuration OpenClaw ou dans votre code d'agent.
5. Ajoutez filtrage, cache et fallback pour éviter bruit, coûts inutiles et erreurs réseau.

Explication

Brave Search est une API de recherche web qui renvoie des résultats organiques, avec titres, URLs, descriptions et quelques métadonnées utiles. Pour un agent OpenClaw, c'est une brique simple mais très puissante : elle apporte des données externes récentes sans dépendre uniquement du corpus d'entraînement du LLM.

Pourquoi Brave plutôt qu'un wrapper fragile type googlesearch-python ? D'abord, l'API est officielle et stable. Ensuite, le coût d'entrée est faible grâce au palier gratuit de 2 000 requêtes mensuelles. Enfin, l'approche est plus privacy-friendly et souvent plus prévisible que des solutions qui simulent un navigateur ou dépendent du scraping de SERP.

Dans OpenClaw, ce type d'intégration fonctionne bien car un skill peut encapsuler trois choses à la fois : l'appel HTTP, la validation d'entrée et la mise en forme de sortie. Vous donnez ainsi au modèle un outil spécialisé, testable isolément, au lieu de lui laisser improviser des requêtes web. Pour voir d'autres patterns proches, consultez aussi ces exemples de skills OpenClaw.

Créer et activer le skill Brave Search

1. Récupérer la clé API Brave

Commencez par créer un compte Brave Search API, puis générez une clé dans votre console. Le point important à retenir est le quota gratuit : 2 000 requêtes par mois. C'est suffisant pour un agent personnel, un prototype de veille ou un workflow éditorial modéré.

Stockez ensuite la clé dans une variable d'environnement :

export BRAVE_SEARCH_API_KEY="votre_cle_api"

Si vous utilisez un fichier .env :

BRAVE_SEARCH_API_KEY=votre_cle_api

2. Écrire le skill Python complet

Le code ci-dessous crée un skill robuste : validation de la requête, gestion du timeout, parsing des résultats et retour structuré.

import os
from typing import Any

import requests
from openclaw.skills import BaseSkill, skill
from openclaw.types import SkillOutput


@skill(
    name="brave_search",
    description=(
        "Recherche des informations récentes sur le web via Brave Search API. "
        "À utiliser pour trouver des sources, des pages d'actualité, des guides ou "
        "des documents publics à partir d'une requête textuelle."
    ),
)
class BraveSearchSkill(BaseSkill):
    API_URL = "https://api.search.brave.com/res/v1/web/search"

    def __init__(self, api_key: str | None = None, timeout: int = 12):
        self.api_key = api_key or os.getenv("BRAVE_SEARCH_API_KEY")
        self.timeout = timeout

    def run(self, input: dict[str, Any]) -> SkillOutput:
        query = (input.get("query") or "").strip()
        count = min(max(int(input.get("count", 5)), 1), 10)
        country = input.get("country", "FR")
        language = input.get("language", "fr")

        if not self.api_key:
            return SkillOutput(success=False, error="BRAVE_SEARCH_API_KEY manquante.")

        if not query:
            return SkillOutput(success=False, error="Le paramètre 'query' est obligatoire.")

        headers = {
            "Accept": "application/json",
            "X-Subscription-Token": self.api_key,
        }
        params = {
            "q": query,
            "count": count,
            "country": country,
            "search_lang": language,
            "safesearch": "moderate",
        }

        try:
            response = requests.get(
                self.API_URL,
                headers=headers,
                params=params,
                timeout=self.timeout,
            )
            response.raise_for_status()
        except requests.RequestException as exc:
            return SkillOutput(success=False, error=f"Erreur Brave Search: {exc}")

        payload = response.json()
        results = []

        for item in payload.get("web", {}).get("results", []):
            results.append(
                {
                    "title": item.get("title", ""),
                    "url": item.get("url", ""),
                    "description": item.get("description", ""),
                    "age": item.get("age"),
                    "language": item.get("language"),
                }
            )

        return SkillOutput(
            success=True,
            data={
                "query": query,
                "result_count": len(results),
                "results": results,
            },
        )

3. Comprendre la réponse JSON

Brave renvoie une structure plus riche que ce dont un agent a besoin. En pratique, il faut souvent extraire seulement quelques champs. Voici un exemple simplifié de payload :

{
  "web": {
    "results": [
      {
        "title": "OpenClaw documentation",
        "url": "https://example.com/openclaw-docs",
        "description": "Guide de configuration des skills OpenClaw.",
        "age": "3 days ago",
        "language": "fr"
      }
    ]
  }
}

Le parsing utile est donc simple : itérer sur payload["web"]["results"], garder les champs pertinents et renvoyer une liste homogène. Cette normalisation est essentielle, car le LLM raisonne mieux sur un format stable que sur une réponse brute d'API.

4. Déclarer le skill dans votre agent OpenClaw

Si vous instanciez vos skills en Python, la configuration minimale ressemble à ceci :

from openclaw import Agent

agent = Agent(
    name="LiveResearchAgent",
    goal="Trouver des sources web récentes et les résumer",
    skills=[BraveSearchSkill()],
    llm="gpt-4o",
    max_steps=8,
)

Vous pouvez ensuite lancer une tâche comme :

result = agent.run(
    task="Recherche les annonces récentes sur les frameworks d'agents IA et résume les 5 sources les plus fiables."
)

Si votre stack sépare les skills et la configuration d'agent, gardez la même logique : le skill doit être explicitement enregistré, avec sa description complète, pour que l'orchestrateur sache quand l'appeler. Si vous voulez enrichir l'agent avec d'autres intégrations HTTP, le guide OpenClaw API skills complète bien ce pattern.

5. Filtrer et préparer les résultats pour l'agent

Un bon skill de recherche ne doit pas tout renvoyer sans tri. Ajoutez au minimum trois règles :

• reformuler la requête avant appel si l'utilisateur est trop vague
• limiter count pour éviter de noyer l'agent
• filtrer les URLs vides ou dupliquées
• conserver un extrait court par résultat
• éventuellement scorer les domaines selon votre contexte métier

La reformulation vaut souvent le coup. Par exemple, au lieu de laisser passer une requête large comme news IA, transformez-la en annonces frameworks agents IA avril 2026 site:github.com OR site:docs.*. Ce n'est pas le rôle du skill lui-même de raisonner longuement, mais il peut accepter des paramètres plus précis comme country, language ou freshness pour aider l'agent à cibler une recherche réellement exploitable.

Autre point utile : séparer clairement la recherche du résumé. Le skill Brave Search doit renvoyer des sources, pas déjà tirer une conclusion. Cette séparation rend les tests plus simples, améliore la réutilisabilité et vous permet de changer de modèle de synthèse sans toucher à la couche recherche.

Exemple de post-traitement :

def clean_results(results: list[dict]) -> list[dict]:
    seen = set()
    cleaned = []

    for item in results:
        url = item.get("url", "").strip()
        if not url or url in seen:
            continue
        seen.add(url)
        cleaned.append(
            {
                "title": item.get("title", "")[:140],
                "url": url,
                "description": item.get("description", "")[:280],
            }
        )
    return cleaned

Ce nettoyage réduit les appels suivants, notamment si vous chaînez ensuite un scraper, un résumeur ou un classifieur. C'est aussi le socle d'un agent de recherche avec OpenClaw, où la recherche n'est qu'une étape d'un pipeline plus complet.

6. Définir quand l'agent doit appeler le skill

Dans OpenClaw, la description du skill influence fortement la décision du modèle. Si votre description est trop vague, l'agent risque soit de ne jamais l'utiliser, soit de l'utiliser pour de mauvaises tâches. Indiquez clairement qu'il sert à trouver des sources web récentes, pas à naviguer dans une page ni à résumer un document entier.

Un pattern simple consiste à ajouter une consigne au niveau de l'agent : utiliser brave_search pour récupérer 3 à 5 sources, puis citer les URLs avant toute synthèse finale. Vous gagnez ainsi en traçabilité, ce qui est crucial pour les workflows de veille, de rédaction ou de benchmark.

• limiter count pour éviter de noyer l'agent
• filtrer les URLs vides ou dupliquées
• conserver un extrait court par résultat

Exemple de post-traitement :

def clean_results(results: list[dict]) -> list[dict]:
    seen = set()
    cleaned = []

    for item in results:
        url = item.get("url", "").strip()
        if not url or url in seen:
            continue
        seen.add(url)
        cleaned.append(
            {
                "title": item.get("title", "")[:140],
                "url": url,
                "description": item.get("description", "")[:280],
            }
        )
    return cleaned

Ce nettoyage réduit les appels suivants, notamment si vous chaînez ensuite un scraper, un résumeur ou un classifieur. C'est aussi le socle d'un agent de recherche avec OpenClaw, où la recherche n'est qu'une étape d'un pipeline plus complet.

Exemple concret

Prenons un cas reproductible : vous voulez un agent qui surveille les nouveautés autour de LangGraph et OpenClaw pour préparer une note de veille hebdomadaire.

1. L'agent appelle brave_search avec la requête LangGraph OpenClaw nouveautés avril 2026.
2. Le skill renvoie 5 à 8 résultats propres, avec titre, URL et description.
3. Une deuxième étape filtre les domaines peu fiables ou hors sujet.
4. Le LLM produit ensuite une synthèse courte à partir des trois meilleures sources.

Exemple d'appel direct du skill :

skill = BraveSearchSkill()
output = skill.run({
    "query": "LangGraph OpenClaw nouveautés avril 2026",
    "count": 5,
    "country": "FR",
    "language": "fr"
})

if output.success:
    for item in output.data["results"]:
        print(item["title"], item["url"])

Résultat attendu : une liste lisible que vous pouvez soit envoyer telle quelle à l'agent, soit enrichir avec un WebScraperSkill ou un module de résumé. En pratique, cette approche est plus fiable qu'un prompt demandant au LLM d'"aller chercher sur le web" sans outil explicite. Le modèle sait exactement quand utiliser le skill, ce qu'il reçoit et comment citer ses sources.

Bonnes pratiques

Commencez simple : un skill, peu de paramètres, une sortie stable. Les erreurs fréquentes viennent surtout d'un excès de complexité trop tôt. Évitez par exemple de renvoyer toute la réponse JSON Brave brute, car cela augmente le bruit et dégrade le raisonnement de l'agent.

Pensez aussi à ces optimisations utiles :

• cache court de 5 à 30 minutes pour les requêtes répétées
• rate limiting côté skill pour ne pas brûler le quota gratuit
• fallback vers une source secondaire si Brave répond en erreur
• scoring simple par domaine ou mot-clé pour améliorer la pertinence
• résumé séparé après recherche, plutôt que dans le même skill

Enfin, comparez honnêtement vos options. serpapi donne souvent plus de moteurs et plus de profondeur, mais coûte plus cher. googlesearch-python peut suffire pour des tests, mais repose sur des mécanismes moins stables. Brave Search offre souvent un bon compromis entre coût, fiabilité et simplicité d'intégration.

Questions fréquentes

Brave Search est-il gratuit avec OpenClaw ?

Oui, Brave Search propose un tier gratuit de 2 000 requêtes par mois. Pour un agent personnel, un POC ou un petit workflow de veille, c'est généralement suffisant. Au-delà, il faut surveiller le volume d'appels et ajouter du cache pour limiter la consommation API.

Quelle différence entre Brave Search et SerpAPI pour OpenClaw ?

Brave Search est souvent plus simple et moins coûteux pour un skill recherche web OpenClaw centré sur les résultats organiques. SerpAPI est plus riche sur certains moteurs et cas SEO avancés, mais ajoute du coût et parfois une complexité inutile pour un agent de recherche généraliste.

Peut-on utiliser Brave Search sans scraper ensuite les pages ?

Oui. Pour certaines tâches, les titres et descriptions suffisent, par exemple classer des sources, détecter une actualité ou proposer une short-list de lectures. Si vous avez besoin de contenu détaillé, ajoutez ensuite un skill de scraping ou d'extraction HTML, pas avant.

Pourquoi mon agent OpenClaw search renvoie des résultats peu pertinents ?

Le problème vient souvent de la requête, pas de l'API. Resserrez les mots-clés, fixez count entre 3 et 8, appliquez un filtrage par domaine et nettoyez les doublons. Un agent recherche web OpenClaw performe mieux avec peu de résultats très propres qu'avec 20 liens médiocres.

Articles liés

Brave Search est une excellente brique de départ dès que votre agent doit travailler sur des informations fraîches. Utilisez-le pour trouver des sources, puis chaînez un scraper, un classifieur ou un résumeur selon votre objectif. La suite logique consiste souvent à passer d'un simple skill à un workflow de veille complet.

• OpenClaw veille IA : use case complet
• Comprendre les skills OpenClaw
• Exemples de skills OpenClaw prêts à adapter
• Créer un agent de recherche avec OpenClaw
• Utiliser des API externes dans vos skills OpenClaw
• Créer un agent IA étape par étape