Comment créer votre premier agent IA avec Claude : du premier appel API au système autonome

90 % du code chez Anthropic est écrit par des agents Claude. Pas par des ingénieurs qui tapent dans une fenêtre de chat. Par des agents autonomes qui exécutent des boucles, appellent des outils et livrent du code pendant que l'équipe dort.

Suivez ma Substack pour recevoir les dernières pépites IA :

movez.substack.com

Voici la configuration exacte. Étape par étape. Du premier appel API à un agent fonctionnel que vous pouvez lancer sur n'importe quelle tâche.

Cet article couvre :

1 - pourquoi la plupart des « agents » que l'on construit n'en sont pas

2 - les 5 parties essentielles de tout agent qui fonctionne

3 - comment construire chaque partie avec Claude, avec du code

4 - les erreurs qui tuent les agents avant même qu'ils ne soient déployés

Mettez ceci en favori. Chaque bloc de code ci-dessous fonctionne.

01. La plupart des « agents IA » ne sont pas des agents

J'ai construit et cassé plus d'agents que je ne peux en compter. Je les ai regardés brûler des tokens toute la nuit sans rien produire. Je les ai regardés réécrire le même fichier 30 fois. Je les ai regardés réussir leurs propres tests en supprimant le test.

Chaque échec m'a appris la même leçon : le modèle n'est pas le problème. L'architecture autour de lui l'est. Ce guide est tout ce que j'ai appris, compressé dans le chemin le plus court que je puisse vous donner.

Voici ce que la plupart des gens construisent quand ils disent « agent IA » :

1while True:
2    user_input = input("> ")
3    response = call_claude(user_input)
4    print(response)

C'est un chatbot. Il vous attend. Il fait ce que vous dites. Il oublie tout entre les sessions. Quand vous fermez l'onglet, il s'arrête.

Un agent est un système qui travaille vers un objectif sans que vous soyez devant lui. Il découvre ce qui doit être fait, élabore un plan, exécute, vérifie le résultat, et si ce n'est pas fini, il réessaie. Vous définissez la direction. L'agent fait le travail.

« Claude Code est passé de zéro à 400 millions de dollars de revenus en quelques mois. C'était un projet de hackathon. Il utilise toujours uniquement l'API publique. »

Boris Cherny, Responsable de Claude Code

La même API à laquelle vous avez accès en ce moment. Les mêmes modèles. La différence, c'est l'architecture autour du modèle.

02. Les 5 parties d'un véritable agent

Tout agent qui fonctionne – Claude Code, Devin, Codex, ou tout ce que vous construisez vous-même – est assemblé à partir de cinq parties. S'il en manque une, il casse.

03. La couche API

Tout commence ici. Vous appelez Claude, Claude répond. Mais la manière dont vous l'appelez détermine si vous obtenez un chatbot ou un agent.

Trois choses comptent : le prompt système, la sortie structurée, et la température.

Le prompt système n'est pas une salutation. C'est le manuel d'utilisation de votre agent. Chaque règle, contrainte et comportement s'y trouve. Sans lui, Claude devine ce que vous voulez. Avec lui, Claude suit vos spécifications.

1import anthropic
2
3client = anthropic.Anthropic()
4
5response = client.messages.create(
6    model="claude-sonnet-4-6",
7    max_tokens=4096,
8    system="""Vous êtes un agent de revue de code.
9
10Règles :
11- Lisez l'intégralité du diff avant de commenter
12- Signalez uniquement les vrais bugs, pas les préférences de style
13- Si rien ne va, dites "LGTM" et arrêtez-vous
14- Ne suggérez jamais de changement que vous n'avez pas testé mentalement
15- Format de sortie : tableau JSON de {file, line, issue, fix}""",
16    messages=[{"role": "user", "content": diff_content}]
17)

La sortie structurée rend la réponse de votre agent exploitable par une machine. Si Claude renvoie du texte libre, votre code doit le parser. Si Claude renvoie du JSON, votre code peut l'utiliser directement.

1# Forcer la sortie JSON en indiquant à Claude la forme exacte
2system = """Retournez UNIQUEMENT du JSON valide. Pas de markdown. Pas d'explication.
3Schéma :
4{
5  "status": "pass" | "fail",
6  "issues": [{"file": str, "line": int, "issue": str}],
7  "summary": str
8}"""

Température. Mettez-la à 0 pour des agents déterministes. Mettez-la entre 0.3 et 0.5 pour du travail créatif. La valeur par défaut (1.0) ajoute une aléa dont vous n'avez presque jamais besoin dans un agent.

04. Outils

Un modèle sans outils peut raisonner mais ne peut pas agir. Il peut vous dire quel fichier éditer mais ne peut pas l'éditer. Il peut décrire une requête mais ne peut pas l'exécuter.

L'utilisation d'outils par Claude vous permet de définir des fonctions que le modèle peut appeler. Vous décrivez la fonction. Claude décide quand l'appeler. Vous l'exécutez et retournez le résultat. Claude utilise le résultat pour continuer à raisonner.

1tools = [{
2    "name": "run_sql",
3    "description": "Exécute une requête SQL en lecture seule sur la base de données",
4    "input_schema": {
5        "type": "object",
6        "properties": {
7            "query": {
8                "type": "string",
9                "description": "Requête SQL SELECT à exécuter"
10            }
11        },
12        "required": ["query"]
13    }
14},
15{
16    "name": "write_file",
17    "description": "Écrit du contenu dans un fichier sur le disque",
18    "input_schema": {
19        "type": "object",
20        "properties": {
21            "path": {"type": "string"},
22            "content": {"type": "string"}
23        },
24        "required": ["path", "content"]
25    }
26}]

La description de l'outil compte plus que vous ne le pensez. Claude la lit pour décider quand et comment utiliser l'outil. Une description vague entraîne de mauvais appels. Une description précise entraîne des appels exacts.

Commencez avec 3 à 5 outils. Lire un fichier, écrire un fichier, exécuter une commande, rechercher, et un outil spécifique à votre domaine d'utilisation. Cela couvre 90 % des tâches d'un agent.

05. La boucle

C'est la partie qui transforme un script en agent. Sans boucle, votre code appelle Claude une fois et s'arrête. Avec une boucle, votre code appelle Claude, vérifie le résultat, et rappelle jusqu'à ce que le travail soit terminé.

Trois composants :

• Vérificateur. Quelque chose qui vérifie si la sortie est bonne. Une suite de tests, un vérificateur de type, un linter, un deuxième appel à Claude avec des critères stricts. Sans cela, l'agent est d'accord avec lui-même en boucle.
• État. Un enregistrement de ce qui s'est passé. Ce qui a fonctionné, ce qui a échoué, ce qu'il faut essayer ensuite. Sans état, l'agent fait la même erreur à chaque passage.
• Condition d'arrêt. L'objectif est atteint, ou une limite stricte dit « après N essais, arrêtez-vous et rapportez ». Sans cela, la boucle tourne indéfiniment et vide votre compte.

1import json
2from pathlib import Path
3
4def run_agent(task: str, max_attempts: int = 5):
5    state = {"task": task, "attempts": [], "done": False}
6
7    for i in range(max_attempts):
8        # Construire le contexte à partir de l'état
9        context = build_prompt(state)
10
11        # Appeler Claude avec les outils
12        result = call_claude(context, tools)
13
14        # Exécuter les appels d'outils
15        output = execute_tools(result)
16
17        # Vérifier le résultat
18        check = verify(output)
19
20        # Mettre à jour l'état
21        state["attempts"].append({
22            "attempt": i + 1,
23            "action": result.summary,
24            "passed": check.passed,
25            "reason": check.reason
26        })
27
28        if check.passed:
29            state["done"] = True
30            break
31
32    # Sauvegarder l'état pour la prochaine exécution
33    Path("state.json").write_text(json.dumps(state, indent=2))
34    return state

Voici le squelette complet. Chaque agent en production est une variation de ce modèle. Les détails changent. La forme, non.

06. Mémoire

Sans mémoire, chaque session repart de zéro. L'agent redécouvre la structure de votre projet. Réapprend vos conventions. Refait les erreurs commises hier.

Les agents Claude utilisent trois couches de mémoire :

CLAUDE.md est un fichier markdown à la racine de votre projet. Claude Code le lit automatiquement au début de chaque session. Vos règles, votre stack, vos conventions. Écrivez-le une fois, lisez-le pour toujours.

1# CLAUDE.md
2
3## Projet
4API de gestion de tâches. Python 3.12, FastAPI, PostgreSQL.
5
6## Règles
7- Toutes les réponses : schéma {data, error, meta}
8- Tests requis pour chaque nouveau endpoint
9- Messages de commit : type(scope): description
10- Ne jamais utiliser print() pour les logs. Utiliser structlog.
11
12## Problèmes connus
13- Le middleware d'auth attend x-auth-token, pas Authorization
14- La suite de tests prend 45s en complet. Utiliser --filter pour l'itération.

Les compétences capturent des workflows entiers. Pas seulement des prompts – la forme complète : format d'entrée, étapes, format de sortie, règles de validation. La première exécution prend 20 minutes. La relecture prend 30 secondes.

Le fichier d'apprentissages est un journal des erreurs. L'agent y écrit après chaque session. La session suivante le lit. Les erreurs se répètent jusqu'à ce qu'elles soient écrites. Ensuite, elles cessent.

1# learnings.md
2
3- L'API de paiement attend la clé d'idempotence dans l'en-tête, pas dans le corps
4- PostgreSQL NOTIFY nécessite un LISTEN explicite dans le pool de connexions
5- Le limiteur de débit compte par clé, pas par IP. Les tests nécessitent des clés uniques.

07. La porte de vérification

La porte est la partie la plus difficile à construire et la plus facile à sauter. La plupart des gens la sautent. C'est pourquoi la plupart des agents cassent en production.

Une porte de vérification est quelque chose qui vérifie le travail de l'agent sans que l'agent ne se note lui-même. Le modèle qui a écrit le code est trop généreux en évaluant son propre travail. Vous avez besoin d'une seconde vérification.

Trois modèles qui fonctionnent :

1. Tests automatisés. L'agent écrit du code. La suite de tests s'exécute. Si les tests échouent, l'agent reçoit la sortie d'erreur et réessaie. C'est ainsi que Claude Code fonctionne en interne.

1def verify(output):
2    # Exécute la suite de tests
3    result = subprocess.run(
4        ["pytest", "tests/", "-x", "--tb=short"],
5        capture_output=True, text=True
6    )
7    return {
8        "passed": result.returncode == 0,
9        "reason": result.stdout if result.returncode != 0 else "all tests pass"
10    }

2. Vérificateur de type / linter. Exécutez mypy, ruff, ou tsc --noEmit après chaque modification. Attrape des catégories entières de bugs sans écrire un seul test.

3. Deuxième modèle comme relecteur. Utilisez un appel séparé à Claude avec un prompt système strict qui ne cherche que les problèmes. Le rédacteur est rapide et bon marché. Le relecteur est lent et strict. Cette séparation fait l'essentiel de la qualité.

1# Prompt du relecteur - séparé du constructeur
2reviewer_system = """Vous êtes un relecteur de code strict.
3Votre SEUL travail est de trouver des problèmes.
4
5Vérifiez :
6- Le code correspond-il aux spécifications ?
7- Y a-t-il des cas limites non détectés ?
8- Tous les tests testent-ils réellement la bonne chose ?
9
10Si tout est correct, répondez : {"passed": true}
11Si quelque chose ne va pas, répondez : {"passed": false, "issues": [...]}
12
13Ne suggérez PAS d'améliorations. Signalez uniquement les vrais bugs."""

Le rédacteur est rapide et bon marché. Le relecteur est lent et strict. Cette séparation fait l'essentiel de la qualité.

08. Tout assembler

Voici un agent complet qui prend l'URL d'un issue GitHub, lit l'issue, écrit le code, exécute les tests et ouvre une PR. Cinq parties fonctionnant ensemble.

1import anthropic, subprocess, json
2from pathlib import Path
3
4client = anthropic.Anthropic()
5CLAUDE_MD = Path("CLAUDE.md").read_text()
6LEARNINGS = Path("learnings.md").read_text()
7
8SYSTEM = f"""Vous êtes un agent de codage.
9Lisez l'issue. Écrivez le correctif. Exécutez les tests.
10
11Contexte du projet :
12{CLAUDE_MD}
13
14Problèmes connus :
15{LEARNINGS}
16
17Règles :
18- Lisez l'intégralité de la base de code avant de modifier quoi que ce soit
19- Écrivez des tests pour chaque modification
20- Si les tests échouent, corrigez le code, pas les tests
21- Arrêtez-vous quand tous les tests passent"""
22
23TOOLS = [
24    read_file_tool,
25    write_file_tool,
26    run_command_tool,
27    search_codebase_tool,
28]
29
30def run(issue_text, max_attempts=5):
31    messages = [{"role": "user", "content": issue_text}]
32
33    for attempt in range(max_attempts):
34        # Appeler Claude
35        response = client.messages.create(
36            model="claude-sonnet-4-6",
37            max_tokens=8192,
38            system=SYSTEM,
39            tools=TOOLS,
40            messages=messages
41        )
42
43        # Exécuter les appels d'outils
44        messages = handle_tool_use(response, messages)
45
46        # Vérifier : exécuter les tests
47        test_result = subprocess.run(
48            ["pytest", "-x", "--tb=short"],
49            capture_output=True, text=True
50        )
51
52        if test_result.returncode == 0:
53            print(f"Fait en {attempt + 1} tentatives")
54            return True
55
56        # Réinjecter l'échec dans la boucle
57        messages.append({
58            "role": "user",
59            "content": f"Tests échoués :\n{test_result.stdout}\nCorrigez et réessayez."
60        })
61
62    return False

Voilà un agent fonctionnel. Une couche API avec un prompt système et CLAUDE.md. Des outils pour les opérations sur les fichiers. Une boucle avec réessai. De la mémoire grâce à learnings.md. Une porte de vérification via pytest.

Moins de 50 lignes. La même architecture que Claude Code utilise en interne.

09. Les 5 erreurs qui cassent tous les agents

1. Pas de porte de vérification. L'agent note son propre travail. Il écrit du code, dit « ça a l'air bon », et passe à autre chose. Le résultat semble correct et casse en production.
2. Pas de condition d'arrêt. La boucle tourne jusqu'à ce que votre facture API soit de 200 $. Sans limite stricte, l'agent réessaie indéfiniment, réécrivant le même fichier 40 fois. Fixez toujours max_attempts. Toujours.
3. Pas de fichier d'état. Même erreur à la tentative #1 et à la tentative #50. L'agent ne sait pas ce qu'il a déjà essayé. Il propose le même correctif cassé trois fois de suite parce que rien n'enregistre l'échec.
4. Trop d'outils. Vous donnez 20 outils à Claude et il choisit le mauvais. Un modèle avec 5 outils clairs fait de meilleurs choix qu'un modèle avec 20 outils qui se chevauchent. Commencez petit. N'ajoutez des outils que lorsque l'agent rencontre un mur.
5. Prompt système vague. « Sois un bon assistant de codage » donne une sortie générique. « Toutes les réponses doivent être du JSON valide, tests requis pour chaque modification, ne jamais modifier les fichiers en dehors de /src » donne un agent qui se comporte bien.

Conclusion :

Un agent qui fonctionne n'est pas un meilleur prompt. C'est un système : API + outils + boucle + mémoire + porte de vérification. Cinq parties. S'il en manque une, il casse.

La plupart des gens liront ceci, le mettront en favori et continueront à utiliser Claude comme un chatbot. Ils colleront une question à la fois et copieront la réponse dans leur codebase à la main.

Ceux qui construiront la boucle livreront du travail pendant qu'ils dorment. Même modèle. Même API. Même prix. Architecture différente.

Les blocs de code ci-dessus fonctionnent tous. Copiez-les. Exécutez-les. Modifiez-les pour votre cas d'utilisation.

Construisez un agent cette semaine. Pointez-le sur une tâche que vous faites tous les jours. Laissez-le tourner.