J'utilise Claude Code presque tous les jours, et j'ai vite compris qu'une bonne partie du confort d'utilisation s...
Créer votre premier agent IA : le guide pas à pas
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.
Articles qui pourraient vous intéresser
Claude Duet : l'agent IA proactif d'Anthropic qui veut épauler les pros face à Muse de Meta
Depuis la rentrée, les géants de l'IA ne parlent plus que d'agents. Meta a ouvert le bal avec Muse début septembre, OpenAI a suivi avec ses Dots, et Anthropic a abattu sa carte le mercredi 21 oc...
Claude Code s'ouvre aux mods pour se personnaliser
Le 1er octobre 2026, une semaine après la sortie des sessions cloud de leur phase d'aperçu, Anthropic a ajouté à
Trier une boîte de réception qui déborde, retrouver la facture d'un fournisseur reçue il y a trois mois, préparer une réponse à un fil de discussion de quinze messages : ce sont des tâches ...
Gérer ses e-mails Thunderbird avec une IA grâce au protocole MCP : le tutoriel complet
Claude Cowork passe dans le cloud : ce qui change vraiment pour vos fichiers, vos tâches et vos données
Le 6 octobre 2026, Anthropic a modifié le fonctionnement de Cowork, l'agent de Claude qui mène seul des tâches longues. Pour les a...
Model Context Protocol (MCP) : à quoi ça sert et faut-il s'y mettre ?
Si le sigle MCP vous fait d'abord penser au Master Control Program, l'intelligence tyrannique du film Tron sorti en 1982, rassurez-vous : son homonyme actuel est nettement plus pacifique. ...
ChatGPT Pro ou Claude Max : quel abonnement IA en donne vraiment le plus pour votre argent ?
Je paie deux abonnements IA chaque mois, ChatGPT Plus et Claude Pro, et je me cogne régulièrement à leurs plafonds. Avec Claude, c'est le code qui fait grimper le compteur. Avec ChatGPT, ce sont...
Copilot dans Excel : offres, version gratuite et Python sans programmer
Le petit bouton Copilot qui s'affiche dans le ruban d'Excel donne l'impression qu'il suffit de cliquer pour profiter de l'IA. En pratique, derrière ce bouton se cachent plusieurs produits, plusieu...
Cloudflare Quick Tunnels : partager un projet
Montrer un site en cours de développement à un client, faire tester une application à un collègue ou vérifier un rendu depuis son téléphone : le besoin revient souvent, et la réponse classi...
Zapier, Make ou n8n en 2026 : mon comparatif pour choisir le bon outil d'automatisation
Recopier une adresse d'un formulaire vers un tableur, relancer un client, transformer un devis signé en facture… Ces petites tâches répétitives grignotent des heures chaque semaine, et c'est ...
