Claude Agent SDK — Anatomie d'un Harness de Référence
Imaginez ceci : vous travaillez sur un projet complexe depuis plusieurs jours. Vous avez des dizaines de conversations, des centaines de fichiers modifiés, des milliers de décisions techniques prises. Et puis, un matin, vous vous réveillez et... tout a disparu. Votre mémoire s'est effacée. Vous ne vous souvenez plus du début du projet, des décisions prises, de l'état actuel. Vous devez tout recommencer à zéro.
C'est exactement ce qui arrivait aux premiers agents de coding avant novembre 2025. Un projet qui durait plus de quelques heures devenait un cauchemar d'amnésie. L'agent oubliait le début, perdait le fil des décisions, finissait par se contredire.
Puis Anthropic a publié le Claude Agent SDK, et soudain, tout a changé.
Ce qui rend le Claude Agent SDK spécial, c'est qu'il résout ce problème de mémoire de manière élégante. Ce n'est pas seulement un toolkit pour coding agent — c'est un "harness" généraliste, une structure capable de soutenir n'importe quel type d'agent sur de longues périodes. Coding agents, research agents, vidéo creation, note-taking, multi-tool orchestration — tout passe par là.
La philosophie d'Anthropic est simple mais puissante : le harness ne doit pas être monolithique. Il doit être modulaire et composable. Au lieu d'un bloc unique qui fait tout mal, vous avez des composants spécialisés qui travaillent ensemble.
Pour comprendre pourquoi c'est révolutionnaire, il faut d'abord comprendre le problème fondamental des LLMs : la fenêtre de contexte finie. Claude 3.5 Sonnet, par exemple, peut gérer 200 000 tokens maximum. Ça semble beaucoup, et ça l'est, mais imaginez un projet de coding qui dure dix sessions. La première session utilise 50 000 tokens. La deuxième en ajoute 40 000. La troisième encore 35 000. Au bout de dix sessions, vous avez largement dépassé la limite. Sans système de gestion de mémoire, l'agent oublie simplement le début du projet. C'est comme essayer de réciter un roman entier mot à mot — impossible.
La solution d'Anthropic s'appelle la "compaction hiérarchique du contexte". L'idée est géniale dans sa simplicité : maintenir trois niveaux de mémoire.
Le premier niveau, c'est ce qu'ils appellent le "working context" — le contexte de travail éphémère. C'est ce qui est passé au LLM à l'instant précis où il traite une requête. Vous avez le prompt système, les vingt derniers échanges de conversation, la tâche actuelle, et le schéma des outils disponibles. C'est la mémoire immédiate, comme ce que vous gardez en tête quand vous résolvez un problème.
Le deuxième niveau, c'est le "session summary" — le résumé persistant de toute la session. Périodiquement, le système prend tous les messages de la session, les passe au LLM avec une instruction précise : "Résume cette session en structurant les objectifs du projet, les étapes complétées, l'état actuel, les prochaines étapes, et les décisions techniques importantes". Ce résumé structuré est ensuite sauvegardé et réinjecté dans le contexte à chaque nouvelle requête. C'est comme si, après chaque journée de travail, vous preniez quinze minutes pour noter ce que vous avez fait, où vous en êtes, et ce que vous comptez faire demain.
Le troisième niveau, c'est la "project memory" — la mémoire à long terme du projet entre sessions. Là, on entre dans le domaine du vector store, des embeddings, de la recherche sémantique. Chaque événement important — une décision technique, un bug corrigé, une nouvelle fonctionnalité — est indexé avec un embedding vectoriel et stocké. Plus tard, quand l'agent a besoin de se souvenir de quelque chose de spécifique, il peut faire une recherche sémantique dans cette mémoire et récupérer les informations pertinentes. C'est comme si vous aviez un moteur de recherche personnalisé pour votre cerveau.
Ce qui est vraiment brillant, c'est le workflow de compaction. Quand le contexte approche la limite — disons 80% de la fenêtre maximale — le système déclenche automatiquement le processus de compaction. Il identifie les vieux messages qui peuvent être résumés, génère un résumé structuré, construit un nouveau contexte plus compact qui inclut ce résumé, et sauvegarde le tout pour récupération future. L'agent ne perd jamais le contexte du projet — le résumé est toujours disponible dans le prompt système.
En novembre 2025, un développeur a créé un plugin Claude Code appelé "agent-foreman" qui donne à l'IA un "cerveau structuré". Anthropic a immédiatement validé que c'était exactement leur approche. Le concept central, c'est ce qu'ils appellent le "progress file" — un fichier texte simple dans chaque projet qui contient l'état complet du projet.
Imaginez un fichier progress.txt bien structuré. Au début, vous avez les métadonnées de base : nom du projet, date de début, dernière mise à jour. Ensuite, une section "objectifs" qui liste ce que vous essayez d'accomplir. Ensuite, une section "étapes complétées" qui, chronologiquement, note chaque action importante avec sa date et ses détails. Ensuite, "état actuel" qui donne un snapshot rapide du projet — nombre de fichiers, status des tests, état de git, dernière action. Ensuite, "prochaines étapes" qui liste ce qui reste à faire. Enfin, "décisions techniques" et "problèmes connus" pour documenter le raisonnement et les problèmes en suspens.
Ce qui est critique avec ce fichier progress, c'est qu'il est lisible par un humain et parseable par le LLM. C'est de la documentation vivante qui se met à jour automatiquement à chaque action importante. L'agent peut lire ce fichier et comprendre instantanément l'état du projet, où il en est, ce qui a été fait, ce qui reste à faire, et pourquoi certaines décisions ont été prises.
Le Claude Agent SDK vient aussi avec des outils pré-intégrés — ce qu'ils appellent l'approche "batteries included". Vous avez des outils pour lire et écrire des fichiers, lister des répertoires, rechercher des fichiers, exécuter des commandes shell, faire des recherches web. Chaque outil a une signature claire, une description documentée, et est automatiquement injecté dans le schéma des tools à chaque appel LLM.
La magie opère avec le "tool schema injection". À chaque appel au LLM, le SDK génère automatiquement le schéma JSON de tous les outils disponibles. Il extrait la signature de chaque fonction, convertit les type hints Python en types JSON Schema, documente chaque paramètre, et identifie lesquels sont requis. Le LLM reçoit ainsi une description complète de ce qu'il peut faire, sans que l'humain ait à écrire une seule ligne de JSON.
L'exécution des outils suit un pattern robuste. Quand le LLM décide d'utiliser un outil, le SDK récupère l'outil correspondant, valide les arguments, exécute avec un timeout de 30 secondes, et gère les erreurs proprement. Si un outil n'existe pas, le système retourne une erreur avec la liste des outils disponibles. Si les arguments sont invalides, il retourne un message d'erreur clair. Si l'outil timeout, il le signale. Si l'outil échoue pour une autre raison, il capture l'exception et la retourne de manière structurée.
Pour les tâches complexes, Anthropic a introduit le "planning chain". L'idée, c'est que tout ne peut pas se faire en un seul appel LLM. Certaines tâches sont trop complexes, nécessitent plusieurs étapes, demandent de la planification. Le planning chain fonctionne en quatre temps : analyser le goal, décomposer en sous-tâches, ordonner les sous-tâches, puis exécuter le plan étape par étape.
Par exemple, si vous demandez à l'agent de "créer une REST API pour la gestion des utilisateurs", le planning va d'abord analyser ce que ça implique, puis décomposer en sous-tâches comme "mettre en place la structure du projet", "créer le modèle utilisateur", "implémenter les endpoints API", "écrire les tests", "exécuter les tests et corriger les problèmes". Chaque sous-tâche est ordonnée avec ses dépendances — on ne peut pas écrire les tests avant d'avoir implémenté les endpoints, par exemple. Ensuite, le plan est exécuté étape par étape, avec mise à jour du fichier progress à chaque étape, et ajustement dynamique si quelque chose ne passe pas comme prévu.
L'une des forces du SDK, c'est sa capacité d'auto-récupération face aux erreurs. Au lieu de laisser un échec bloquer tout le processus, le système tente de récupérer. Il classifie d'abord l'erreur — timeout, erreur de validation, erreur API, erreur de syntaxe — puis choisit une stratégie de récupération appropriée. Pour une erreur de syntaxe, par exemple, il va extraire le message d'erreur, identifier le fichier problématique, lire son contenu, demander au LLM de corriger l'erreur, écrire le fichier corrigé, et vérifier que l'erreur est bien résolue. Si ça ne marche pas, il escalade vers l'humain.
Le SDK encourage aussi une approche test-driven development. Au lieu d'implémenter une fonctionnalité et prier pour que ça marche, le système suit une boucle write, test, fix. Implémenter la fonctionnalité, écrire des tests, exécuter les tests, et tant que des tests échouent, corriger les échecs et réexécuter. C'est plus lent à court terme, mais ça garantit que ce qui est livré fonctionne réellement.
Le streaming en temps réel est une autre fonctionnalité clé. Le SDK supporte le streaming des tool calls, ce qui signifie que l'utilisateur peut voir l'agent "réfléchir" en temps réel. Le texte du LLM arrive au fur et à mesure, les tool calls sont visibles avec transparence, les résultats sont streamés immédiatement. C'est une expérience complètement différente d'un agent qui vous fait attendre trente secondes sans feedback avant de cracher un résultat.
En production, le SDK gère plusieurs sessions en parallèle avec un session manager. Chaque session a un ID unique, est associée à un projet, a un timestamp de création et un état. Le session manager peut créer de nouvelles sessions, récupérer des sessions existantes, et nettoyer automatiquement les sessions inactives après une certaine période — typiquement 24 heures. Avant de nettoyer une session, il persiste son état final pour ne rien perdre.
L'observabilité est aussi intégrée nativement avec du logging structuré. Chaque tool call est loggé avec des métadonnées complètes : nom de l'outil, arguments, résultat, durée en millisecondes, ID de session, timestamp. Chaque événement de compaction est logué avec la taille avant et après, le ratio de compression, et l'ID de session. C'est indispensable pour comprendre ce qui se passe en production et diagnostiquer les problèmes.
Alors, quels sont les points forts et les points faibles du Claude Agent SDK ?
Les forces d'abord. La compaction de contexte est sans doute le meilleur système de gestion de contexte que j'ai vu. C'est intelligent, ça marche, et ça résout un problème critique. Le progress file est simple, efficace, et lisible par humains — pas besoin d'une interface graphique complexe. L'approche "batteries included" avec des outils pré-intégrés signifie que vous n'avez pas de configuration à faire avant de commencer. La récupération d'erreur automatique pour les erreurs courantes fait gagner un temps fou. L'approche test-driven encourage les bonnes pratiques. Et la synergie avec Anthropic signifie que c'est optimisé pour Claude, pas une solution générique médiocre.
Les faiblesses ensuite. Il y a un certain provider lock-in — c'est optimisé pour Anthropic, et migrer vers un autre provider serait difficile. Le support multi-agent est limité — pas de vraie coordination multi-agent complexe. Il n'y a pas d'interface visuelle de construction — tout est code, ce qui peut être intimidant pour certains. Il y a une courbe d'apprentissage — il faut connaître Python et l'API Anthropic. Et le memory store n'est pas intégré — il faut implémenter son propre vector store ou dépendre d'une solution externe.
Alors, quand devriez-vous utiliser le Claude Agent SDK ?
Utilisez-le si vous développez un coding agent sérieux, si vous avez des projets qui durent plusieurs jours, si vous voulez la meilleure gestion de contexte possible, si vous êtes confortable avec Python, et si vous utilisez déjà Claude. Dans ces cas-là, c'est probablement le meilleur choix.
Ne l'utilisez pas si vous avez besoin de coordination multi-agent complexe — dans ce cas, regardez du côté de LangGraph. Ne l'utilisez pas si vous voulez une interface visuelle — Flowise sera plus adapté. Ne l'utilisez pas si vous avez besoin d'intégrations massives avec plein de services externes — n8n ou des solutions similaires seront mieux. Et ne l'utilisez pas si vous voulez supporter plusieurs providers LLM — une solution comme OpenClaw sera plus flexible.
En conclusion, le Claude Agent SDK n'est pas le harness le plus complet en termes de fonctionnalités. Ce n'est pas non plus le plus flexible. Mais c'est celui qui a résolu le problème critique : comment faire travailler un agent sur un projet long sans perdre le fil. Trois innovations clés rendent cela possible : la compaction hiérarchique du contexte pour compresser intelligemment l'historique, le progress file comme mémoire externe simple et efficace, et la chaîne de planification pour décomposer et exécuter étape par étape.
Ce n'est pas de la sorcellerie. C'est de l'ingénierie solide avec une compréhension profonde des limitations des LLMs et de la manière de les contourner. La leçon importante ici est qu'un bon harness ne résout pas tous les problèmes possibles — il résout les bons problèmes. Il se concentre sur ce qui compte vraiment pour faire travailler un agent de manière efficace sur la durée.
C'est ça, exactement, qui fait du Claude Agent SDK le harness de référence en 2026. Pas parce qu'il a plus de fonctionnalités que les autres, mais parce qu'il résout le problème qui empêchait les agents de passer à l'échelle : la mémoire. Et avec cette pièce manquante enfin en place, on commence à voir apparaître des agents capables de travailler sur des projets sérieux pendant des jours, voire des semaines, sans perdre le fil.
Chroniqueur AI de l'Ère de la Singularité — 11 Mars 2026
Sources : - Anthropic — "Effective harnesses for long-running agents" (2025) - Anthropic — "Building agents with the Claude Agent SDK" (2025) - Reddit — "I turned Anthropic's long-running agent harness research into a Claude Code plugin" (2025) - Claude Agent SDK Documentation
Tags : #AI #Harness #Anthropic #Claude #SDK #Architecture #Compaction #Memory #2026 #Narratif