« Il a une fenêtre de contexte d'un million de tokens » est lancé comme si ça résolvait tout. Ce n'est pas le cas. J'ai appris ça à la dure, en fourrant une base de code entière dans un seul appel Claude et en regardant l'agent devenir moins performant, pas plus. Plus de contexte n'est pas gratuit, et ce n'est pas toujours mieux. Laissez-moi vous expliquer ce qu'une fenêtre de contexte est réellement et quand le grand chiffre vous aide plutôt qu'il ne vous nuit.
Ce qu'est réellement la fenêtre
La fenêtre de contexte est le nombre maximum de tokens que le modèle peut traiter en une seule requête — tout ce que vous envoyez (prompt système, outils, historique complet des messages, fichiers) plus tout ce qu'il génère. Sur les modèles Claude actuels, la fenêtre d'entrée est grande : Opus 4.6, 4.7 et 4.8 tournent tous avec un contexte d'1 million de tokens, Sonnet 4.6 est également à 1 million, et Haiku 4.5 est à 200 000. La sortie est plafonnée séparément — jusqu'à 128 000 tokens sur les modèles Opus, 64 000 sur Sonnet et Haiku.
Notez que ce sont deux limites différentes. Atteindre la limite d'entrée vous donne stop_reason: "model_context_window_exceeded". Atteindre le plafond de sortie demandé vous donne stop_reason: "max_tokens". Ils signifient des choses différentes et ont besoin de corrections différentes, alors gérez les deux branches. Les gens les confondent constamment et se demandent ensuite pourquoi augmenter max_tokens n'a pas aidé — parce que le problème était du côté de l'entrée.
Pourquoi un token n'est pas un mot
Vérification rapide du mécanisme, parce que ça compte pour le budget. Le modèle ne voit pas des mots ; il voit des tokens, qui sont des morceaux de sous-mots produits par un tokeniseur. La prose anglaise tourne à environ un token par trois quarts d'un mot. Le code est tokenisé plus dense. Le texte non anglais, encore plus dense.
Ce qui signifie que vous ne pouvez pas estimer les comptes de tokens Claude avec tiktoken — c'est le tokeniseur d'OpenAI, et il sous-compte Claude de 15 à 20 % sur du texte ordinaire et beaucoup plus sur du code. Si vous avez besoin d'un chiffre réel, appelez l'endpoint count_tokens avec le même identifiant de modèle que vous utiliserez pour l'inférence. Les tokeniseurs sont spécifiques aux modèles. Opus 4.8 et Fable 5 partagent le même ; les anciens modèles comptent différemment. Ne réutilisez pas un budget mesuré sur le mauvais modèle.
La partie que personne ne vous avertit : remplir la fenêtre dégrade la qualité
Voici l'élément contre-intuitif. Ce n'est pas parce que vous pouvez mettre un million de tokens que vous devriez le faire. Les modèles font moins fiablement attention aux informations enterrées au milieu d'un très long contexte, et un contexte bruité dilue le signal dont le modèle a besoin pour l'étape actuelle. J'ai regardé un agent avec un contexte propre de 20 000 tokens surpasser le même agent à 400 000 tokens sur la tâche identique, parce qu'à 400 000 tokens, 95 % de ce à quoi il faisait attention était des résultats d'outils périmés de douze étapes auparavant.
Donc l'objectif n'est pas de maximiser ce que vous entassez. C'est de garder le contexte pertinent. Le plafond d'un million de tokens est une marge de sécurité pour les entrées vraiment grandes — un dépôt entier à analyser d'un coup, un long document, une trace de recherche approfondie. Ce n'est pas une licence pour ne jamais faire le ménage.
Trois outils pour garder le contexte pertinent
Ces outils résolvent des problèmes différents ; choisissez selon ce qui ne va pas.
L'édition du contexte élague. Elle supprime les résultats d'outils périmés et les blocs de réflexion de la transcription selon des seuils que vous définissez. Le contenu effacé est supprimé, pas remplacé. Utilisez-la quand les anciens résultats d'outils sont du poids mort et que vous voulez une transcription légère sans perdre la structure de la conversation. C'est le bon choix pour maintenir une haute précision des appels d'outils dans les longues boucles.
La compaction résume. Quand une conversation approche de la limite de fenêtre, l'API condense l'historique antérieur en un bloc de résumé côté serveur. Utilisez-la quand vous allez vraiment atteindre le plafond et que vous avez besoin de continuer. Un piège critique : vous devez ajouter le response.content complet à vos messages à chaque tour — les blocs de compaction y vivent, et si vous n'extrayez que le texte et l'ajoutez, vous perdez silencieusement l'état de compaction et tout casse.
La mémoire persiste entre les sessions. Les deux autres opèrent dans une seule conversation ; la mémoire ce sont les fichiers que l'agent lit et écrit et qui survivent à un redémarrage du processus. Quand l'état doit survivre à la session — préférences, apprentissages accumulés, un bloc-notes courant — c'est la mémoire, pas le contexte. Et honnêtement, des modèles comme Opus 4.8 fonctionnent notablement mieux quand vous leur donnez un endroit où écrire des choses et leur dites de le vérifier la prochaine fois.
De nombreux agents de longue durée utilisent les trois. L'édition élague les tours morts, la compaction vous rattrape près du plafond, la mémoire conserve ce qui compte entre les exécutions.
Une heuristique de budget qui m'a bien servi
Pensez à votre contexte comme ayant trois zones. Le préfixe figé (prompt système, outils) — gardez-le stable, il ne change jamais, et en bonus il se met en cache. L'ensemble de travail — les tours récents dont le modèle a réellement besoin pour l'étape actuelle. Et la queue — la question ou le résultat d'outil actuel. Quand l'ensemble de travail commence à se remplir de choses que le modèle n'a pas référencées depuis de nombreux tours, c'est votre signal pour éditer ou compacter. Pas quand vous atteignez un certain nombre de tokens. Quand la pertinence baisse.
Une dernière note pratique : les grandes sorties. Si vous demandez quoi que ce soit proche du plafond de 128 000 tokens de sortie sur un modèle Opus, vous devez diffuser la requête. Les appels non-streaming touchent les délais d'attente HTTP du SDK à max_tokens élevé — la requête meurt juste en attendant. Utilisez le helper de streaming et extrayez le message final de là.
La fenêtre d'un million de tokens est une vraie capacité et parfois exactement ce qu'il vous faut. Mais la compétence n'est pas de la remplir. La compétence est de savoir quand un contexte propre et pertinent de 30 000 tokens battra un contexte bouffi de 600 000 — ce qui, d'après mon expérience dans la construction d'agents, est la plupart du temps.