Accéder au contenu principal

Un auto-entrepreneur passionné à votre service,

Pour votre projet de site internet et vos dépannages informatiques

Créer votre premier agent IA : le guide pas à pas

Publié le 1 Septembre 2026, dernière mise à jour le 2 Septembre 2026

Dans l'article précédent, j'ai décrit la boucle qui distingue un agent d'un chatbot : rassembler, agir, vérifier, recommencer. Reste à la voir tourner.

Ce guide est découpé en trois niveaux. Le niveau 0 ne demande pas d'écrire une ligne de code, et si vous vous arrêtez là vous aurez déjà compris l'essentiel. Le niveau 1 refait la même chose en une quinzaine de lignes de Python. Le niveau 2 s'adresse à ceux qui veulent brancher l'agent sur leurs propres outils.

Le projet fil rouge

On va traiter un problème que tout le monde rencontre en refonte de site : les redirections.

Vous avez une liste des anciennes URL et une liste des nouvelles. Il faut produire un fichier de redirections qui associe correctement les unes aux autres, sans se tromper, et surtout sans laisser d'URL de destination qui tombe en 404.

Ce choix n'est pas innocent. La tâche contient les trois gestes de la boucle, et la vérification y est particulièrement nette : une URL répond 200 ou elle ne répond pas. L'agent ne peut pas se raconter d'histoires. Vous allez le voir se tromper, s'en apercevoir tout seul, et corriger.

Préparez un dossier avec deux fichiers texte, une URL par ligne :

mon-agent/
  anciennes-urls.txt
  nouvelles-urls.txt

Une vingtaine de lignes suffisent pour l'exercice.

Ce qu'il faut avant de commencer

Deux choses à savoir avant d'ouvrir quoi que ce soit, parce qu'elles surprennent souvent.

Pour le niveau 0, Claude Code demande un compte payant : Pro, Max, Team, Enterprise ou un compte Console. Le plan gratuit de Claude.ai n'y donne pas accès.

Pour les niveaux 1 et 2, il vous faut une clé API, et la facturation se fait à l'usage. Pas de forfait, pas d'abonnement : vous payez ce que la boucle consomme. Un exercice comme celui-ci coûte quelques dizaines de centimes, mais un agent mal cadré qui part en vrille peut coûter beaucoup plus. C'est pour ça qu'on va poser un plafond dès le premier script.

Côté technique, il faut Python 3.10 ou plus récent, ou Node.js 18 ou plus récent. Rien d'autre : les deux paquets embarquent le moteur, vous n'avez pas à installer Claude Code séparément pour utiliser le SDK.

Niveau 0 : voir la boucle sans écrire de code

Deux façons d'y arriver.

Sans terminal

Téléchargez l'application de bureau Claude, disponible pour macOS, Windows et Linux, et ouvrez l'onglet Code. Vous pointez votre dossier de travail, vous tapez votre consigne dans une zone de texte, et vous regardez. C'est la voie la plus simple si la ligne de commande vous rebute.

Avec le terminal

L'installateur natif est la méthode recommandée aujourd'hui.

Sur macOS, Linux ou WSL :

curl -fsSL https://claude.ai/install.sh | bash

Sur Windows, dans PowerShell :

irm https://claude.ai/install.ps1 | iex

L'installation par npm existe toujours, mais ce n'est plus la voie conseillée pour un premier setup. Une fois l'installation terminée, contrôlez que tout est en place :

claude --version

Si la commande n'est pas trouvée, ouvrez un nouveau terminal avant de chercher plus loin, puis lancez claude doctor qui affiche un diagnostic complet.

Placez-vous ensuite dans votre dossier et démarrez la session :

cd mon-agent
claude

La consigne

Collez ceci :

Lis anciennes-urls.txt et nouvelles-urls.txt.
Associe chaque ancienne URL à la nouvelle qui lui correspond le mieux et
écris le résultat dans redirections.txt, une paire par ligne.
Ensuite, teste chaque URL de destination avec curl.
Si l'une d'elles ne répond pas 200, corrige la correspondance et reteste.
Ne t'arrête que quand toutes les destinations répondent 200.

Regardez ce qui défile. Il lit les deux fichiers, il écrit le fichier de sortie, il lance curl une URL après l'autre, il tombe sur une destination en 404, il retourne dans le fichier, il change la ligne, il relance le test. C'est la boucle de l'article précédent, en vrai, sous vos yeux.

Vous verrez aussi apparaître des demandes de permission avant certaines actions. C'est normal, on y revient plus bas.

Une remarque sur la formulation de la consigne. Les trois dernières lignes ne sont pas du remplissage : elles donnent le critère d'arrêt. Sans elles, l'agent écrit son fichier, le trouve satisfaisant, et rend la main. Avec elles, il ne peut pas sortir de la boucle tant que le monde réel ne lui a pas donné raison.

Niveau 1 : la même chose en Python

Même tâche, mais cette fois pilotée par un script que vous pourrez déclencher automatiquement.

Installation

Sur macOS ou Linux :

python3 -m venv .venv
source .venv/bin/activate
pip install claude-agent-sdk

Sur Windows, dans PowerShell :

py -m venv .venv
.venv\Scripts\Activate.ps1
pip install claude-agent-sdk

Si PowerShell refuse d'exécuter le script d'activation, lancez d'abord Set-ExecutionPolicy -Scope Process RemoteSigned.

La clé API

Récupérez une clé dans la console Anthropic, puis exposez-la dans le terminal d'où vous lancerez le script.

macOS ou Linux :

export ANTHROPIC_API_KEY=votre-cle

Windows :

$env:ANTHROPIC_API_KEY = "votre-cle"

Attention à un piège classique : le SDK ne lit pas tout seul un fichier .env. Si vous rangez votre clé là-dedans, il faut la charger vous-même, avec python-dotenv par exemple.

Le script

Créez agent.py :

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage

CONSIGNE = """
Lis anciennes-urls.txt et nouvelles-urls.txt.
Associe chaque ancienne URL a la nouvelle qui lui correspond le mieux et
ecris le resultat dans redirections.txt, une paire par ligne.
Ensuite, teste chaque URL de destination avec curl.
Si l'une d'elles ne repond pas 200, corrige la correspondance et reteste.
Ne t'arrete que quand toutes les destinations repondent 200.
"""

async def main():
    options = ClaudeAgentOptions(
        system_prompt=(
            "Tu prepares des redirections pour une refonte de site. "
            "Tu ne conclus jamais sans avoir teste ton resultat."
        ),
        allowed_tools=["Read", "Write", "Edit", "Bash"],
        permission_mode="acceptEdits",
        max_turns=40,
        max_budget_usd=1.0,
    )

    async for message in query(prompt=CONSIGNE, options=options):
        if isinstance(message, AssistantMessage):
            for bloc in message.content:
                if hasattr(bloc, "text"):
                    print(bloc.text)
                elif hasattr(bloc, "name"):
                    print(f"[outil] {bloc.name}")
        elif isinstance(message, ResultMessage):
            print(f"Fin : {message.subtype}")
            if message.total_cost_usd is not None:
                print(f"Cout : {message.total_cost_usd:.4f} $")

asyncio.run(main())

Lancez-le :

python agent.py

Vous obtenez le même comportement qu'au niveau 0, avec le coût total affiché à la fin.

Ce que font les options

system_prompt fixe le rôle et les règles du jeu. C'est ici qu'on impose « ne conclus pas sans avoir testé ». Sans cette phrase, l'agent sort de la boucle beaucoup trop tôt.

allowed_tools mérite une explication, parce que beaucoup de tutoriels se trompent dessus. Cette liste ne restreint pas l'agent : elle pré-approuve. Les outils listés s'exécutent sans demander votre accord, les autres restent accessibles mais passent par une demande de permission. Pour retirer vraiment un outil, il faut l'exclure autrement, j'y reviens dans la section garde-fous.

permission_mode règle le curseur entre autonomie et contrôle. Le mode acceptEdits utilisé ici accepte les modifications de fichiers et les commandes courantes de manipulation de fichiers, mais laisse les autres commandes passer par les règles normales.

max_turns et max_budget_usd sont vos deux ceintures de sécurité. La première coupe après un nombre de tours, la seconde après un montant dépensé. Sur un agent lancé sans surveillance, le budget est de loin la plus utile des deux, parce que c'est celle qui parle à votre banquier. Quand un plafond est atteint, la session se termine avec un message d'erreur explicite plutôt qu'un résultat.

Le moment le plus instructif : enlevez la vérification

Faites l'expérience. Retirez "Bash" de la liste des outils, et supprimez les trois dernières lignes de la consigne. Relancez.

L'agent produit un fichier de redirections en quelques secondes. Il a l'air parfait. Les lignes sont bien formées, les correspondances sont plausibles. Et un certain nombre d'entre elles pointent vers des URL qui n'existent pas, parce que rien ni personne n'est allé vérifier.

Remettez maintenant l'outil et les trois lignes de consigne. Cette fois la session est plus longue, plus bavarde, et le fichier final est juste. Vous voyez même l'agent revenir sur ses propres erreurs après un test raté.

C'est toute la différence entre une démo et quelque chose qu'on met en production. La qualité ne vient pas du modèle, elle vient du fait qu'il a un moyen de savoir qu'il s'est trompé.

Niveau 2 : donner de vrais bras à l'agent

Jusqu'ici on s'est contenté des outils intégrés : lecture, écriture, édition, commandes shell. C'est déjà énorme, parce qu'avec un accès au shell, l'agent peut écrire un script pour n'importe quel besoin ponctuel et l'exécuter. Un seul outil général vaut souvent mieux que quinze outils spécialisés.

Mais vous pouvez aussi exposer vos propres fonctions.

Un outil sur mesure

Ici, un outil qui teste une URL proprement plutôt que de passer par curl :

from typing import Any
import httpx
from claude_agent_sdk import tool, create_sdk_mcp_server

@tool("verifier_url", "Verifie le code HTTP renvoye par une URL", {"url": str})
async def verifier_url(args: dict[str, Any]) -> dict[str, Any]:
    async with httpx.AsyncClient(follow_redirects=True) as client:
        reponse = await client.get(args["url"])
    return {
        "content": [
            {"type": "text", "text": f"{args['url']} : {reponse.status_code}"}
        ]
    }

serveur = create_sdk_mcp_server(
    name="redirections",
    version="1.0.0",
    tools=[verifier_url],
)

Le décorateur prend quatre choses : un nom, une description, le schéma des arguments attendus, et la fonction elle-même. La description compte plus qu'on ne croit, puisque c'est en la lisant que l'agent décide s'il doit appeler l'outil.

Pour brancher ce serveur sur la session :

options = ClaudeAgentOptions(
    mcp_servers={"redirections": serveur},
    allowed_tools=["Read", "Write", "mcp__redirections__verifier_url"],
    max_turns=40,
    max_budget_usd=1.0,
)

Notez la convention de nommage : mcp__ suivi du nom du serveur, puis du nom de l'outil. C'est sous ce nom complet que l'outil doit apparaître dans la liste des outils pré-approuvés.

Brancher ce qui existe déjà

Vous n'êtes pas obligé de tout écrire. Le même mécanisme permet de connecter des serveurs MCP existants : votre instance n8n, une base Notion, une boîte mail, un navigateur. Chacun ajoute un jeu d'actions prêtes à l'emploi, et vos connecteurs habituels deviennent le contexte de l'agent.

Un principe à garder en tête : peu d'outils, plutôt généraux, valent mieux que quarante fonctions rigides. Chaque définition d'outil occupe de la place dans la fenêtre de contexte, et un agent noyé sous les choix travaille moins bien qu'un agent qui a le shell et trois connecteurs bien choisis.

Les garde-fous, avant de le lâcher

Un agent autonome va vite. Il peut donc aller vite dans le mur, et il faut cadrer ça avant la mise en production plutôt qu'après.

Le mode de permission

Le curseur principal. Les modes disponibles aujourd'hui :

  • default : les outils non couverts par une règle d'autorisation passent par votre fonction de validation. Sans fonction de validation, la réponse est non.
  • acceptEdits : accepte les modifications de fichiers et les commandes de manipulation de fichiers courantes, le reste suit les règles normales.
  • plan : l'agent explore et propose un plan sans modifier vos fichiers. Pratique pour cadrer une grosse tâche avant de la lancer.
  • dontAsk : ne demande jamais rien. Ce qui est explicitement autorisé s'exécute, tout le reste est refusé.
  • auto : un classifieur décide d'approuver ou de refuser à votre place.
  • bypassPermissions : tout passe, sans question. À réserver strictement aux environnements isolés, conteneur ou intégration continue.

Retirer vraiment un outil

Comme dit plus haut, la liste des outils autorisés pré-approuve mais n'interdit rien. Pour qu'un outil ne soit pas utilisable du tout, deux moyens : ne pas l'inclure dans la liste des outils exposés, ou le nommer dans la liste des outils interdits. Dans les deux cas il disparaît du champ de vision de l'agent, qui n'essaiera même pas.

Il existe aussi des règles ciblées, du type Bash(rm *), qui laissent l'outil disponible mais bloquent uniquement les commandes correspondantes. Un agent qui n'a que la lecture ne pourra jamais rien casser : c'est la sécurité par le périmètre, et c'est la plus simple à mettre en place.

Les hooks

Pour aller plus loin, vous pouvez faire exécuter votre propre code à des moments précis de la boucle : avant qu'un outil s'exécute, après qu'il a rendu son résultat, quand l'agent termine, ou avant une compaction du contexte. Le cas typique, c'est de bloquer une commande dangereuse ou d'exiger une validation humaine sur tout ce qui touche à l'irréversible, comme une suppression, un envoi ou un paiement.

La checklist avant de mettre en service

  • L'agent peut aller chercher son contexte lui-même, plutôt que de tout recevoir dans le prompt.
  • Il a peu d'outils, mais des outils qui font vraiment quelque chose.
  • Il existe un moyen de vérifier le résultat, et ce moyen vient du monde réel, pas de l'avis de l'agent sur lui-même.
  • La consigne dit clairement à quoi ressemble une tâche terminée.
  • Un plafond de tours et un plafond de budget sont posés.
  • Le mode de permission correspond au risque réel, et rien d'irréversible ne passe sans contrôle.

Si les six points sont cochés, vous pouvez le laisser tourner.

Par où continuer

Le meilleur exercice suivant, c'est de reprendre une tâche que vous faites à la main chaque semaine et de vous demander trois choses : où l'agent irait chercher l'information, quelle action il devrait exécuter, et surtout comment il saurait qu'il a réussi. Si vous butez sur la troisième question, c'est là que se trouve le vrai travail. Le reste, la boucle s'en charge.