Qu'est-ce qu'un agent, vraiment ?#

Tout le monde dit « agent ». Presque personne ne parle de la même chose. Voici la définition qui te permet de décider.

Temps de lecture : 12 min | Niveau : Débutant

Ce que tu sauras faire après#

• Distinguer un appel LLM simple, un workflow scripté et un agent autonome.
• Décrire la boucle percevoir → décider → agir → observer avec tes propres mots.
• Nommer les 3 ingrédients obligatoires d'un agent : modèle, outils, boucle.
• Reconnaître, dans tes tâches data, celles qui méritent un agent.
• Répondre à « c'est quoi un agent ? » en réunion sans dire de bêtise.

1. Le problème du mot « agent »#

Le mot est devenu un argument commercial. Il désigne aujourd'hui aussi bien un chatbot un peu malin qu'un système qui refactorise un dépôt entier.

Anthropic pose une frontière nette, et c'est celle que ce cours utilise :

« Workflows are systems where LLMs and tools are orchestrated through predefined code paths. Agents, on the other hand, are systems where LLMs dynamically direct their own processes and tool usage, maintaining control over how they accomplish tasks. »

En français simple :

• Workflow = ton code décide de l'ordre des étapes.
• Agent = le modèle décide de l'ordre des étapes.

C'est tout. Le reste est de la décoration.

2. Les trois niveaux, avec des exemples data#

Niveau 1 — Un appel LLM simple#

Tu envoies un prompt, tu reçois du texte. Fin.

Prompt : "Voici une requête SQL. Explique ce qu'elle fait, en 5 lignes.
SELECT client_id, SUM(montant) FROM commandes
WHERE date_cmd >= '2026-01-01' GROUP BY client_id;"

Une requête, une réponse. Coût connu, latence connue, résultat reproductible (à la température près).

Anthropic le rappelle : « For many applications, optimizing single LLM calls with retrieval and in-context examples is usually enough. » La majorité des besoins s'arrêtent ici.

Niveau 2 — Un workflow scripté#

Tu enchaînes plusieurs appels, mais c'est ton code Python qui tient le plan. Le modèle ne décide jamais de l'étape suivante.

# Workflow : 3 etapes FIXES, ecrites par moi. Le modele ne choisit rien.
schema = lire_schema_postgres("public.commandes")        # etape 1 : code pur
sql = llm(f"Ecris une requete SQL sur ce schema : {schema}\nBesoin : {besoin}")  # etape 2
verdict = llm(f"Cette requete est-elle valide et sure ? {sql}")                  # etape 3
if "OK" in verdict:
    executer(sql)

Anthropic appelle ce patron prompt chaining. Il y en a cinq au total (on les détaille dans le fichier 03) :

Les trois premiers sont des workflows. Les deux derniers commencent à ressembler à des agents, parce que le découpage n'est plus fixé à l'avance.

Niveau 3 — Un agent autonome#

Tu donnes un objectif, pas un plan. Le modèle choisit ses outils, son nombre d'étapes, et s'arrête quand il estime avoir fini.

Objectif : "Le DAG Airflow 'daily_sales' echoue depuis mardi.
Trouve la cause et propose un correctif."

Le modèle va peut-être : lire le code du DAG, puis lister les logs, puis remarquer une date, puis ouvrir un fichier de config, puis lancer une requête de contrôle. Tu ne sais pas d'avance combien d'étapes ni lesquelles. C'est précisément ça, un agent.

La documentation du SDK décrit le même mécanisme :

« Claude continues calling tools and processing results until it produces a response with no tool calls. »

L'agent s'arrête tout seul, quand il n'a plus besoin d'outil.

3. La boucle : percevoir → décider → agir → observer#

C'est le cœur. Un agent n'est pas un gros prompt, c'est une boucle.

        ┌─────────────────────────────────────────────┐
        │                                             │
        v                                             │
  [1] PERCEVOIR      [2] DECIDER        [3] AGIR      │
  lit le contexte -> choisit un outil -> execute      │
  (prompt + outils    ou repond du       l'outil      │
   + historique)      texte final                     │
                                            |         │
                                            v         │
                                     [4] OBSERVER ────┘
                                     le resultat revient
                                     dans le contexte

La documentation officielle du SDK détaille exactement ces étapes :

1. Receive prompt — le modèle reçoit ton message, le prompt système, la définition des outils et l'historique.
2. Evaluate and respond — il répond du texte, demande un ou plusieurs outils, ou les deux.
3. Execute tools — le harnais exécute les outils et collecte les résultats.
4. Repeat — les étapes 2 et 3 recommencent. Un cycle complet = un « turn ».
5. Return result — la boucle s'arrête quand le modèle répond sans demander d'outil.

Le point crucial, et Anthropic insiste dessus :

« During execution, it's crucial for the agents to gain "ground truth" from the environment at each step (such as tool call results or code execution). »

Autrement dit, l'agent ne devine pas : le résultat réel de la commande revient dans son contexte à chaque étape. C'est ce qui le rend utile, et c'est ce qui le sépare d'un modèle qui improvise.

Ce que ça change concrètement#

Un exemple vécu en data engineering :

Tour 1 : Claude appelle Bash -> "pytest tests/test_transform.py"
         Resultat observe : 3 tests echouent, erreur KeyError 'montant_ht'
Tour 2 : Claude appelle Read -> transform.py
         Resultat observe : la colonne s'appelle 'montant_hors_taxe'
Tour 3 : Claude appelle Edit -> corrige le nom de colonne
         Claude appelle Bash -> relance pytest
         Resultat observe : 3 tests passent
Tour 4 : Claude repond du texte, sans outil. La boucle s'arrete.

Aucune de ces étapes n'était écrite d'avance. Le modèle a réagi à ce qu'il a observé.

4. Les 3 ingrédients obligatoires#

Retiens ces trois-là. S'il en manque un, ce n'est pas un agent.

Ingrédient 1 — Un modèle#

Le cerveau. Il lit le contexte et décide. Sans modèle, tu as un script.

Point pratique : le choix du modèle change le comportement. Un modèle plus capable délègue et planifie davantage ; un modèle plus léger va au plus direct et coûte moins cher. La documentation Claude Code permet de fixer le modèle par sous-agent (champ model), ce qui est la principale manette de coût.

Ingrédient 2 — Des outils#

Les mains. Sans outils, le modèle ne peut que produire du texte.

« Without tools, Claude can only respond with text. With tools, Claude can read files, run commands, search code, and interact with external services. » — documentation du SDK

Les outils intégrés de Claude Code, classés par la doc officielle :

Anthropic donne un conseil de conception que je trouve très juste : soigner l'interface agent-ordinateur autant qu'on soigne une interface homme-machine. Concrètement, la description d'un outil doit contenir « example usage, edge cases, input format requirements, and clear boundaries from other tools ».

Ingrédient 3 — Une boucle#

Le moteur. C'est ce qui permet au modèle d'agir puis de corriger le tir. Une seule passe, ce n'est pas un agent.

5. Quand un agent apporte vraiment quelque chose#

Un agent se justifie quand ces conditions sont réunies. Coche mentalement :

• [ ] Tu ne peux pas prédire le nombre d'étapes. Anthropic : idéal pour « open-ended problems where it's difficult or impossible to predict the required number of steps ».
• [ ] Il existe un signal de vérité. Des tests qui passent, une requête qui s'exécute, un linter qui se tait. Sans signal, l'agent tourne à l'aveugle.
• [ ] L'erreur est réversible et peu coûteuse. Un fichier versionné dans Git, oui. Un DELETE en production, non.
• [ ] Le gain dépasse le surcoût. Les agents « trade latency and cost for better task performance ».

Si tu coches les quatre : agent. Si tu en coches deux ou moins : workflow ou simple appel.

Trois cas où l'agent gagne vraiment, côté data#

Trois cas où l'agent perd#

Règle du cours : sur une tâche à fort volume et bien comprise, tu ne veux presque jamais d'agent. Anthropic dit la même chose autrement : « For many applications, optimizing single LLM calls with retrieval and in-context examples is usually enough. »

6. AVANT / APRÈS : demander un agent correctement#

❌ AVANT — un objectif flou#

Debug mon pipeline.

Problèmes : aucun critère d'arrêt, aucun périmètre, aucun signal de vérité. L'agent va explorer au hasard, consommer des tokens et rendre une réponse molle.

✅ APRÈS — un objectif d'agent bien posé#

Objectif : le DAG Airflow `daily_sales` echoue depuis le 2026-09-22.

Perimetre : dossier `dags/daily_sales/` et `logs/daily_sales/` uniquement.
N'ouvre aucun autre repertoire.

Methode : commence par lire le dernier log d'echec, puis remonte vers le code.

Critere d'arret : tu as identifie la ligne exacte qui echoue ET tu proposes
un correctif. Ne modifie aucun fichier, propose un diff.

Format de sortie :
1. Cause racine (2 lignes max)
2. Fichier + numero de ligne
3. Diff propose
4. Comment je verifie que c'est corrige

Pourquoi c'est mieux#

7. Template prêt à copier-coller#

Garde celui-ci sous la main. C'est le squelette de toute demande à un agent.

OBJECTIF
[DECRIS_LE_RESULTAT_ATTENDU_EN_UNE_PHRASE]

CONTEXTE
- Projet : [NOM_DU_PROJET]
- Stack : [PYTHON_3_12 / DBT / AIRFLOW / POSTGRES / ...]
- Fichiers concernes : [CHEMINS_PRECIS]

PERIMETRE
- Tu peux lire : [DOSSIERS_AUTORISES]
- Tu ne dois pas toucher a : [DOSSIERS_INTERDITS]

METHODE SUGGEREE
1. [PREMIERE_ETAPE_QUE_TU_CONSEILLES]
2. [DEUXIEME_ETAPE]
(Tu peux devier si tu trouves mieux, mais dis-le.)

SIGNAL DE VERITE
Considere la tache reussie quand : [TEST_QUI_PASSE / REQUETE_QUI_TOURNE / SORTIE_ATTENDUE]

CONTRAINTES
- [NE_PAS_MODIFIER_X / NE_PAS_APPELER_LA_PROD / MAX_N_FICHIERS_TOUCHES]

FORMAT DE SORTIE
[LISTE_NUMEROTEE / TABLEAU / DIFF / JSON]

À retenir#

• Workflow = mon code décide. Agent = le modèle décide. C'est la seule frontière qui compte.
• Un agent = modèle + outils + boucle. Enlève un élément, ce n'est plus un agent.
• La boucle percevoir → décider → agir → observer fonctionne parce que le résultat réel des outils revient dans le contexte à chaque tour.
• Un agent se justifie quand le nombre d'étapes est imprévisible et qu'il existe un signal de vérité (tests, exécution, linter).
• Pour les tâches à fort volume et bien comprises (classification, extraction), un simple appel LLM suffit presque toujours.
• Un bon objectif d'agent contient toujours : périmètre, méthode suggérée, critère d'arrêt, format de sortie.

Sources#

• Building Effective Agents — Anthropic Engineering
• How the agent loop works — Claude Code Docs
• Agent SDK overview — Claude Code Docs
• Subagents — Claude Code Docs