Créer agent OpenClaw

Introduction

Vous avez déjà installé OpenClaw et vous voulez passer du concept à un agent réellement exploitable. Dans ce tutoriel, vous allez construire un petit agent Python capable de rechercher une information, puis de produire un résumé propre à partir du résultat.

L'objectif n'est pas de créer un simple hello world, mais une base solide que vous pourrez réutiliser dans vos propres projets. Si vous avez besoin des fondamentaux avant de coder, commencez par Créer un agent IA : guide complet, puis revenez ici pour assembler votre premier agent OpenClaw.

Ce que vous allez construire

• un agent Python simple et testable
• deux skills complémentaires
• une logique d'orchestration minimale mais réaliste
• une checklist pour valider que l'agent fonctionne vraiment

Résumé rapide

1. Installez OpenClaw et préparez un projet Python propre.
2. Définissez un agent avec un rôle clair, des consignes et deux skills.
3. Créez un skill de recherche et un skill de résumé avec des entrées simples.
4. Branchez les skills à l'agent pour qu'il choisisse quand les appeler.
5. Testez avec des prompts concrets, vérifiez les logs et corrigez les cas d'erreur.

En bref

Pour créer un agent OpenClaw utile, commencez petit. Un agent avec un objectif précis et deux skills bien définis vous apprendra déjà l'essentiel sans complexifier inutilement votre architecture.

Explication

Créer un agent OpenClaw consiste à assembler trois briques.

1. Un agent avec un objectif précis et des règles de décision.
2. Des skills que l'agent peut appeler quand une réponse textuelle ne suffit pas.
3. Une orchestration qui relie le modèle, le contexte et les outils disponibles.

Dans OpenClaw, un bon agent ne cherche pas à tout faire. Il sait quand répondre directement, quand lancer un outil, et quand enchaîner plusieurs actions. C'est ce qui le distingue d'un simple prompt.

Pour un premier projet, le plus efficace est de viser un cas simple mais réaliste, par exemple un agent qui cherche des informations sur un sujet puis les synthétise. Cette structure vous apprend déjà l'essentiel, notamment la séparation entre logique métier, définition des skills et configuration de l'agent.

C'est aussi la meilleure manière de comprendre les skills OpenClaw sans tomber dans une architecture trop complexe. Une fois cette base maîtrisée, vous pourrez aller vers des agents avec mémoire, validation ou exécution multi-étapes, notamment après avoir consolidé votre configuration OpenClaw.

Développement principal

Avant de commencer, vérifiez que votre environnement fonctionne déjà. Si ce n'est pas le cas, suivez d'abord Installer OpenClaw. Côté Python, partez sur un environnement virtuel propre.

1. Préparer l'arborescence du projet

Voici une structure simple, lisible et suffisante pour un premier agent OpenClaw.

mon-agent-openclaw/
├── .env
├── requirements.txt
├── main.py
├── config.py
├── agent/
│   └── research_agent.py
└── skills/
    ├── search_skill.py
    └── summarize_skill.py

Le but de cette arborescence est d'éviter de mélanger la configuration, l'agent et les outils. Même sur un petit projet, cette séparation vous fera gagner du temps au moment du débogage.

2. Installer les dépendances

python -m venv .venv
source .venv/bin/activate
pip install openclaw python-dotenv requests
pip freeze > requirements.txt

Dans votre fichier .env, ajoutez au minimum la clé du fournisseur de modèle utilisé par votre setup OpenClaw.

OPENAI_API_KEY=sk-...
MODEL_NAME=gpt-4o-mini

Puis créez config.py.

import os
from dotenv import load_dotenv

load_dotenv()

MODEL_NAME = os.getenv("MODEL_NAME", "gpt-4o-mini")
OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")

3. Définir le rôle de l'agent

Votre agent doit avoir une mission très claire. Ici, il doit répondre à une demande de recherche courte, utiliser un outil si nécessaire, puis restituer une synthèse exploitable.

Créez agent/research_agent.py.

from config import MODEL_NAME
from skills.search_skill import search_web
from skills.summarize_skill import summarize_text

SYSTEM_PROMPT = """
Tu es un agent de recherche et de synthèse.
Tu réponds brièvement quand la question est simple.
Si l'utilisateur demande des informations factuelles récentes, utilise le skill de recherche.
Si tu récupères un texte long, utilise ensuite le skill de résumé.
Tu cites clairement ce que tu as trouvé et tu évites d'inventer.
"""

class ResearchAgent:
    def __init__(self):
        self.name = "research-agent"
        self.model = MODEL_NAME
        self.system_prompt = SYSTEM_PROMPT
        self.skills = {
            "search_web": search_web,
            "summarize_text": summarize_text,
        }

À ce stade, vous ne créez pas encore toute la boucle d'exécution. Vous posez simplement le cadre. C'est souvent la partie la plus négligée, alors qu'elle détermine largement la qualité des appels de skills.

4. Créer le premier skill, la recherche

Le premier skill doit faire une chose simple, avec une entrée et une sortie prévisibles. Pour un premier agent OpenClaw Python, évitez les outils trop abstraits.

Créez skills/search_skill.py.

import requests


def search_web(query: str) -> dict:
    """Retourne un résultat de recherche simplifié."""
    response = requests.get(
        "https://api.duckduckgo.com/",
        params={"q": query, "format": "json", "no_html": 1},
        timeout=15,
    )
    response.raise_for_status()
    data = response.json()

    return {
        "query": query,
        "abstract": data.get("Abstract", ""),
        "source": data.get("AbstractSource", ""),
        "url": data.get("AbstractURL", ""),
        "related_topics": [
            topic.get("Text")
            for topic in data.get("RelatedTopics", [])[:3]
            if isinstance(topic, dict) and topic.get("Text")
        ],
    }

Pourquoi ce format est utile ? Parce qu'il force le skill à renvoyer des champs stables. L'agent peut alors raisonner sur une structure claire au lieu d'un bloc de texte difficile à exploiter.

5. Créer le deuxième skill, le résumé

Créez skills/summarize_skill.py.

def summarize_text(text: str, max_bullets: int = 5) -> dict:
    """Produit un résumé simple à partir d'un texte."""
    sentences = [s.strip() for s in text.split(".") if s.strip()]
    bullets = sentences[:max_bullets]

    return {
        "summary": bullets,
        "count": len(bullets),
    }

Ce deuxième skill est volontairement simple. Dans un projet réel, vous pourrez remplacer cette logique par un appel modèle plus robuste, mais pour apprendre à construire un agent OpenClaw, mieux vaut commencer avec une fonction testable localement.

6. Orchestrer les skills dans le flux principal

Créez maintenant main.py.

from agent.research_agent import ResearchAgent


def run_agent(user_request: str) -> str:
    agent = ResearchAgent()

    if "recherche" in user_request.lower() or "cherche" in user_request.lower():
        search_result = agent.skills["search_web"](user_request)

        raw_text_parts = []
        if search_result.get("abstract"):
            raw_text_parts.append(search_result["abstract"])
        raw_text_parts.extend(search_result.get("related_topics", []))

        combined_text = ". ".join(raw_text_parts).strip()
        if combined_text:
            summary = agent.skills["summarize_text"](combined_text)
            bullets = "\n".join([f"- {item}" for item in summary["summary"]])
            return (
                f"Résultats pour : {search_result['query']}\n"
                f"Source : {search_result.get('source') or 'non précisée'}\n"
                f"URL : {search_result.get('url') or 'non disponible'}\n\n"
                f"Résumé :\n{bullets}"
            )

        return "La recherche n'a pas renvoyé assez d'informations pour produire un résumé."

    return "Je peux répondre directement, ou lancer une recherche si vous me le demandez."


if __name__ == "__main__":
    prompt = "cherche des informations sur OpenClaw"
    result = run_agent(prompt)
    print(result)

Cette version simplifiée illustre la boucle centrale d'un agent, analyser la requête, décider d'utiliser un skill, récupérer un résultat, puis déclencher un second skill si la sortie le justifie. C'est exactement la logique à comprendre avant de passer à un agent plus avancé ou à des cas comme les exemples de skills avancés.

7. Tester le comportement de l'agent

Lancez le script.

python main.py

Résultat attendu, sous une forme proche de celle-ci.

Résultats pour : cherche des informations sur OpenClaw
Source : ...
URL : ...

Résumé :
- OpenClaw est ...
- ...

Faites ensuite trois tests ciblés.

1. Question simple : l'agent doit répondre sans outil.
2. Question de recherche : il doit appeler search_web.
3. Résultat long : il doit enchaîner search_web puis summarize_text.

8. Vérifier que l'agent fonctionne vraiment

Utilisez cette checklist de validation finale.

• le projet démarre sans erreur d'import
• la variable d'environnement du modèle est chargée
• chaque skill peut être appelé seul dans un test Python
• la requête de recherche renvoie une structure JSON stable
• le résumé final est lisible et exploitable
• l'agent ne lance pas une recherche inutile sur une demande triviale

Checkpoint avant d'aller plus loin

Si votre agent passe cette checklist, vous avez déjà une base propre pour ajouter d'autres skills, brancher une mémoire ou complexifier l'orchestration.

Si votre premier agent fonctionne, passez à l'étape suivante avec les exemples de skills avancés pour étendre ses capacités.

Exemple concret

Prenons un cas simple et reproductible. Vous voulez un agent qui aide une petite équipe contenu à faire une veille rapide sur un framework avant de rédiger une note interne. La demande utilisateur est : cherche des informations sur LangGraph et résume les points clés.

L'agent commence par détecter l'intention de recherche grâce aux mots présents dans la requête. Il appelle alors search_web("cherche des informations sur LangGraph et résume les points clés"). Le skill renvoie un dictionnaire avec un résumé principal, une source et quelques sujets liés. Le flux principal concatène ces champs en un texte unique, puis transmet ce texte à summarize_text.

Vous obtenez alors une sortie compacte sous forme de puces. Dans un usage réel, ce résultat peut servir de base à un comparatif, à une note de cadrage ou à une tâche d'automatisation plus large. Le point important est que chaque étape reste inspectable. Si la recherche échoue, vous savez que le problème vient du skill réseau. Si le résumé est médiocre, vous savez que le problème vient du traitement de texte, pas de l'architecture globale.

Pour aller plus loin, vous pouvez stocker chaque exécution dans un fichier log, ajouter un score de confiance, ou brancher ensuite un troisième skill chargé de reformater la réponse en Markdown.

Bonnes pratiques

Commencez toujours par un agent étroitement défini. Un agent trop vague appelle mal ses outils, répète des actions inutiles et devient difficile à tester.

Gardez aussi ces règles en tête.

• imposez des entrées et sorties stables à chaque skill
• évitez de lier trop tôt votre agent à des API complexes
• testez chaque skill séparément avant de tester l'agent complet
• ajoutez rapidement des logs d'exécution et une validation des paramètres
• prévoyez une stratégie de repli quand un skill échoue

Pour un premier agent OpenClaw, une logique locale simple vaut mieux qu'une intégration fragile. Vous isolerez beaucoup plus vite les erreurs d'import, de format ou de timeout.

Questions fréquentes

Comment créer un agent OpenClaw quand on débute en Python ?

Commencez avec un seul agent, un objectif précis et deux skills maximum. Cette approche suffit pour comprendre la structure d'un agent OpenClaw Python sans vous perdre dans une orchestration trop large. Une fois le flux stable, vous pourrez ajouter mémoire, routage avancé ou validations.

Quel est le meilleur premier projet pour un tutoriel agent OpenClaw ?

Un agent de recherche et de résumé est un excellent point de départ. Il combine une requête utilisateur, un appel outil, puis une transformation du résultat. Cela vous apprend la logique centrale sans dépendre d'un domaine métier trop spécifique.

Faut-il plusieurs skills pour construire un agent OpenClaw utile ?

Pas forcément, mais deux skills complémentaires montrent mieux comment l'agent décide d'agir. Avec un skill de recherche et un skill de résumé, vous voyez déjà comment enchaîner des outils, contrôler les sorties et éviter qu'un agent réponde au hasard.

Comment savoir si mon premier agent OpenClaw fonctionne correctement ?

Vérifiez quatre points : les imports passent, les variables d'environnement sont chargées, chaque skill fonctionne seul, et l'agent choisit correctement entre réponse directe et appel outil. Si l'un de ces points échoue, corrigez-le avant d'ajouter de nouvelles capacités.

Articles liés

Créer un agent OpenClaw devient beaucoup plus simple quand vous séparez clairement le rôle de l'agent, les skills et la logique d'orchestration. Pour la suite, concentrez-vous soit sur la qualité des skills, soit sur le déploiement et la configuration selon votre niveau actuel.

• Créer un agent IA : guide complet
• Installer OpenClaw pas à pas
• Comprendre les skills OpenClaw
• Exemples de skills avancés pour OpenClaw
• Configurer OpenClaw proprement en production