Context engineering pour les agents AI : mémoire et outils

Viacheslav Dubrov

2025-10-05 · Mis à jour 2026-08-16 · 18 min · Agents IA

Traduction automatique Cet article a été traduit automatiquement depuis la version originale en anglais.

Le context engineering est le pipeline qui sélectionne ce qu’un modèle voit avant chaque décision : instructions, exemples, connaissances, mémoire, définitions d’outils, observations et garde-fous. Un agent n’agit pas sur tout ce que le système sait. Il agit sur le working set assemblé pour le prochain appel au modèle.

C’est à ce niveau que commencent de nombreux échecs. Une préférence obsolète semble actuelle. Le texte récupéré contient une instruction. Un tool result volumineux masque la précondition qui a échoué. Un résumé conserve la décision, mais perd l’information indiquant quel fichier a été modifié.

Pour les ingénieurs qui construisent ou exploitent des agents AI, des systèmes de retrieval et des applications utilisant des outils, le travail pratique consiste à assembler le plus petit working set suffisant pour chaque décision de l’agent, tout en préservant le périmètre, la provenance et les permissions. Cet article montre comment concevoir un pipeline de contexte par décision, repérer ses frontières de confiance, vérifier que son working set permet d’accomplir la tâche et rendre les échecs inspectables, plutôt que d’accuser un modèle qui ne voit que l’entrée assemblée.

En bref. Traitez le contexte comme un artefact d’exécution typé et porteur de provenance. Sélectionnez-le à chaque étape, appliquez le périmètre du tenant et les permissions avant le retrieval, et séparez les instructions fiables des données non fiables. Budgétez selon l’utilité, validez les actions en dehors du modèle et évaluez les résultats de la tâche, pas uniquement la longueur du contexte.

Le contexte est une entrée de décision, pas une mémoire

La fenêtre de contexte correspond à l’entrée actuelle du modèle, plus les tokens générés. Elle peut contenir des tours de conversation, mais ce n’est pas un système de mémoire durable. La mémoire à long terme, les index documentaires, les bases de données et les artifact stores résident en dehors de la fenêtre. Un pipeline de contexte choisit ce qu’il faut y copier.

La taille de la fenêtre est une limite de capacité, pas une garantie de qualité. Lost in the Middle et RULER montrent que le retrieval et le raisonnement peuvent varier selon la position, la tâche, le modèle et la longueur de la séquence. La leçon opérationnelle n’est pas que les tokens centraux sont toujours ignorés. C’est que l’ajout de tokens qui semblent pertinents peut malgré tout réduire les performances sur la tâche.

Le diagramme présente le résultat qualitatif de l’étude, et non une courbe universelle d’attention. Liu et al. ont testé le question answering multi-document et le retrieval clé-valeur. Ils ont souvent observé de meilleures performances lorsque l’élément pertinent apparaissait près du début ou de la fin. L’ampleur et la forme de l’effet variaient selon les modèles, les tâches et les longueurs de contexte. Testez la position comme variable dans votre propre jeu d’évaluation au lieu de supposer une pénalité fixe au milieu.

Le schéma Pydantic suivant est illustratif et ne correspond pas à une implémentation de repository testée. Il valide uniquement les types de champs et les valeurs littérales. Il n’autorise pas le tenant, ne garantit pas la cohérence de total_input_tokens avec items, ne persiste pas le manifest et n’impose pas le comportement du modèle.

from datetime import datetime
from typing import Literal

from pydantic import BaseModel

class ContextItem(BaseModel):
    item_id: str
    kind: Literal["instruction", "task_state", "evidence", "memory", "tool"]
    source: str
    trust: Literal["trusted", "untrusted"]
    retrieved_at: datetime | None = None
    version: str | None = None
    token_count: int

class ContextManifest(BaseModel):
    request_id: str
    tenant_id: str
    items: list[ContextItem]
    total_input_tokens: int

Le manifest rend un échec reproductible. « Le modèle a halluciné » devient une question testable : quelles preuves, quelle version, quel périmètre de permissions et quel tool schema a-t-il réellement reçus ?

Le cycle d’assemblage

Un pipeline fiable effectue ces opérations dans l’ordre :

1. Résoudre le contexte de requête fiable. Authentifier l’acteur, le tenant, la locale, l’heure et l’état actuel de la tâche en dehors du modèle.
2. Choisir la prochaine décision. Une étape de planification, une recherche de preuves, une sélection d’outil et une réponse finale nécessitent des contextes différents.
3. Effectuer le retrieval dans le périmètre autorisé. Appliquer les filtres d’autorisation et de tenant avant le semantic ranking, et non après l’entrée des documents dans l’ensemble des candidats.
4. Classer et budgéter. Sélectionner les éléments selon leur utilité, leur fraîcheur, leur autorité et leur diversité, dans les limites du budget d’entrée.
5. Assembler avec des frontières de confiance. Conserver la policy dans les canaux d’instructions et citer le contenu récupéré comme des données. Les instructions récupérées ne deviennent pas une policy système.
6. Générer une proposition typée. Le constrained output peut imposer une syntaxe et une structure prises en charge. Il ne peut pas rendre les valeurs correctes.
7. Valider et exécuter. Le code applicatif vérifie l’autorisation, les règles métier, les arguments des outils et les postconditions.
8. Enregistrer la provenance et le résultat. Sauvegarder le manifest, les identifiants des sources sélectionnées, les références aux tool results, le résultat de la validation et le résultat de la tâche.

Le cycle s’applique à chaque décision. Réutiliser un contexte volumineux pour toute une exécution d’agent crée des preuves obsolètes et donne à chaque étape accès à des éléments dont elle n’a pas besoin.

Donnez un rôle unique à chaque source de contexte

Les instructions définissent le comportement durable

Les instructions définissent le rôle, la policy, le contrat de sortie et le comportement d’escalade. Conservez le contenu stable pour améliorer le prefix caching, mais ne figez pas les valeurs qui changent à l’exécution. Un seuil de remboursement doit résider dans un service de policy ou un enregistrement de données versionné, et non être copié indéfiniment dans un prompt.

La hiérarchie des instructions est une frontière de contrôle, pas un sandbox de sécurité. Un modèle peut toujours suivre un texte malveillant présent dans un document récupéré. Délimitez le contenu non fiable, indiquez qu’il s’agit de preuves et non d’instructions, restreignez les outils indépendamment et testez les cas de prompt injection.

Ne transposez pas les noms de rôles d’un fournisseur dans une hiérarchie universelle. L’OpenAI Model Spec définit des niveaux d’autorité pour les instructions de plateforme ou système, de développeur et d’utilisateur. L’Anthropic Messages API utilise un paramètre system de niveau supérieur ainsi que des messages user et assistant. Cette API n’expose pas de rôle developer équivalent. D’autres runtimes font des choix différents. Faites correspondre votre policy aux canaux documentés par le fournisseur, puis appliquez les permissions et les effets de bord dans le code applicatif.

L’état de la tâche consigne les engagements

La prose d’une conversation est une source de vérité médiocre pour les travaux en plusieurs étapes. Conservez explicitement l’objectif, la phase actuelle, les actions terminées, les validations en attente, les références aux artefacts et l’état des tests. Le modèle peut résumer cet état pour la narration. Le code applicatif en détient la version canonique.

Les exemples illustrent les décisions limites

Les exemples few-shot sont utiles lorsqu’ils clarifient une frontière difficile, et non lorsqu’ils répètent simplement le schema. Sélectionnez des exemples correspondant à la décision actuelle et incluant des cas limites à fort impact. Évaluez le retrieval des exemples comme celui des documents : un exemple superficiellement similaire mais incompatible avec la policy peut être pire que l’absence d’exemple.

Les connaissances fournissent les preuves

Le retrieval convient aux faits récents, privés ou citables. Il n’existe pas de top_k, de taille de chunk, de pondération hybride ou de seuil de reranker universellement optimal. Ajustez l’ensemble du chemin sur des questions dont les preuves attendues sont connues.

Un élément de preuve utile comprend :

• la source et un identifiant stable du document
• la version ou la date d’entrée en vigueur
• le périmètre des permissions
• l’extrait cité et son emplacement
• les scores de retrieval et de reranking à des fins de debug

Ne demandez pas au modèle de citer une URL qu’il n’a jamais reçue. N’enregistrez pas des documents privés complets uniquement pour déboguer la sélection.

La mémoire fournit une continuité à périmètre contrôlé

La mémoire est une donnée récupérée qui présente des risques supplémentaires sur son cycle de vie. Dans les métadonnées de conception, suivez le sujet, la provenance, l’objectif, la décision relative au consentement ou à la base légale applicable, la date de création, la policy d’expiration ou de révision et le chemin de suppression. Le droit applicable en matière de protection de la vie privée et le conseil juridique du produit déterminent la base légale d’un produit et de ses données, pas cette checklist.

Les règles fixes telles que « les préférences sont conservées 365 jours » ne constituent pas une policy portable. La rétention dépend du besoin produit, des attentes de l’utilisateur et du droit applicable. Avant de charger une mémoire, vérifiez :

1. Concerne-t-elle bien ce sujet authentifié et ce tenant ?
2. Son objectif est-il pertinent pour cette décision ?
3. Est-elle suffisamment actuelle pour être utilisée ?
4. Sa source fait-elle autorité ou est-elle simplement déduite par le modèle ?

Traitez les mémoires inférées comme des hypothèses. Ne transformez pas silencieusement une réponse du modèle en fait permanent concernant l’utilisateur.

Les contrats d’outils exposent des capacités

Les descriptions d’outils doivent préciser les préconditions, les effets, le périmètre d’autorisation, le schéma d’entrée, le schéma de sortie, l’idempotence et les échecs significatifs. Un tool call valide selon le schema peut tout de même être non autorisé ou dangereux.

Après l’exécution, remplacez la sortie brute verbeuse par une observation typée qui conserve le résultat pertinent pour la décision ainsi qu’une référence vers l’artefact complet :

{
    "tool": "check_api_key_status",
    "status": "revoked",
    "checked_at": "2026-07-15T09:30:00Z",
    "account_id": "A-123",
    "artifact_ref": "toolrun://req-42/step-3"
}

La spécification MCP standardise la manière dont les clients interagissent avec les outils, les ressources et les prompts. Elle n’autorise pas leur utilisation et ne rend pas fiable le contenu renvoyé. Conservez les vérifications de gateway, d’identifiants et de policy en dehors du modèle et de la description du protocole.

Chargez les détails lorsqu’une décision les nécessite

La progressive disclosure est un pattern d’assemblage du contexte : conserver les identifiants et l’état fiable de la tâche disponibles, puis récupérer les détails nécessaires à la décision actuelle. Elle ne garantit pas qu’un budget de tokens donné fonctionnera pour tous les modèles.

Le router doit appliquer l’autorisation et le périmètre du tenant avant le retrieval. Il doit renvoyer les extraits de preuves, les enregistrements mémoire et les tool schemas utiles à la décision actuelle. Le modèle propose ensuite une action. Le code applicatif valide cette proposition avant exécution. Le guide d’Anthropic sur le contexte des outils applique le même principe sélectif aux grands ensembles d’outils. La recherche d’outils conserve leurs définitions en dehors de la fenêtre de contexte jusqu’à ce que le modèle les demande. Mesurez si cette étape de routage supplémentaire améliore la réussite des tâches, la latence et le nombre de tokens par tâche réussie dans votre système.

Comment le contexte se dégrade

Un mauvais contexte n’échoue pas d’une seule manière. Le modèle de dégradation suivant en cinq patterns est ma synthèse pour le debugging, établie à partir des évaluations de long contexte présentées plus haut et des recherches sur la prompt injection :

• Perte liée à la position : la preuve nécessaire est présente, mais le modèle l’utilise de manière incohérente en raison de sa position et de la séquence environnante. Les évaluations de long contexte montrent que l’effet varie selon le modèle et la tâche. Il n’existe pas de plage universelle du « mauvais milieu ».
• Empoisonnement : une mémoire incorrecte, un document obsolète, une instruction malveillante ou une mauvaise observation d’outil entre dans le working set et influence les décisions ultérieures.
• Distraction : les preuves pertinentes sont en concurrence avec des éléments récents ou sémantiquement similaires, mais inutiles pour l’étape actuelle.
• Confusion : des instructions, exemples ou descriptions d’outils qui se chevauchent laissent au modèle plusieurs interprétations plausibles de la tâche.
• Conflit : deux éléments qui semblent faire autorité sont en désaccord sur une valeur, une policy ou l’action suivante, et l’assembleur n’expose ni leurs versions ni leur précédence.

Ces échecs nécessitent des corrections différentes. Un meilleur ranking peut aider contre la distraction, mais ne peut pas corriger une source obsolète. Des délimiteurs peuvent aider à séparer les données des instructions, mais ne peuvent pas autoriser un outil. Une fenêtre de contexte plus grande peut conserver davantage d’éléments contradictoires sans résoudre le conflit.

Lorsqu’une exécution échoue, inspectez le manifest et identifiez d’abord le pattern en cause avant de modifier le prompt ou d’ajouter une étape de retrieval.

Budgétez selon l’utilité, pas selon des quotas par composant

Un budget de contexte réserve d’abord de la place pour la sortie, puis alloue l’entrée à la décision actuelle. Partez de la fenêtre prise en charge par le modèle, soustrayez la sortie maximale et l’overhead du protocole, puis insérez les candidats dans l’espace restant.

Attribuez aux candidats un score fondé sur des caractéristiques que vos évaluations peuvent remettre en cause :

utility = relevance × authority × freshness × scope_match
          − redundancy_penalty − injection_risk

Considérez cette formule comme un point de départ pour la conception. Dans une réponse de policy, l’autorité peut dominer la similarité sémantique. En debugging, un log d’échec récent peut être mieux classé que la documentation générale.

L’ordre compte également. Conservez les instructions fiables et stables au début lorsque les mécanismes de cache du fournisseur bénéficient d’un préfixe partagé. Placez la tâche et la décision actuelles près des preuves auxquelles elles se rapportent. Évitez les horodatages ou les identifiants de requête dans les préfixes stables lorsqu’ils n’y sont pas nécessaires.

Compressez sans perdre l’état

La compression est avec pertes, sauf si l’original reste adressable. L’évaluation de Factory Research portant sur trois approches de compression pour des sessions d’agents de longue durée définit la cible en tokens par tâche, et non en tokens par requête. J’en déduis une recommandation d’ingénierie : optimisez les tokens par tâche réussie, et non les tokens par requête, dans des conditions de tâche comparables — sans en faire une loi universelle. Évaluation de Factory Research

Utilisez des mécanismes distincts pour des contenus distincts :

• Conversation : résumer les décisions, les questions non résolues et les engagements.
• Observations d’outils : conserver les résultats typés et les références aux artefacts. Supprimer le boilerplate et les payloads répétés.
• Preuves récupérées : conserver les identifiants des sources, les extraits justificatifs et les dates d’entrée en vigueur afin que le système puisse les récupérer à nouveau.
• État de la tâche : le stocker de manière canonique en dehors du résumé.
• Trace des fichiers ou des artefacts : maintenir un index explicite des lectures, écritures, hash et résultats de tests.

Déclenchez la compaction à partir d’une dégradation mesurée ou d’un seuil budgétaire choisi pour le modèle et la tâche. Ne publiez pas une règle générique du type « compresser à 70 % » comme si tous les modèles échouaient au même moment.

Évaluez la compression avec des probes nécessitant une continuation, et non avec un simple chevauchement lexical :

• Quel est l’objectif actuel et quelle est l’action suivante ?
• Quels fichiers ou enregistrements ont changé ?
• Quelle décision a été rejetée et pourquoi ?
• Quelle source étaye l’affirmation actuelle ?
• Quelle validation est encore en attente ?

Exécutez la même tâche avec et sans compression. Comparez la réussite, les actions incorrectes, les nouveaux retrievals, la latence et le nombre total de tokens.

Optimisez le chemin du contexte

L’optimisation doit préserver le contrat de décision. Quatre techniques sont utiles une fois qu’un goulot d’étranglement mesuré a été identifié :

Ces techniques répondent à des problèmes différents. La compaction et l’édition du contexte peuvent réduire le contenu envoyé au modèle. Le chargement sélectif des outils évite d’envoyer des schemas inutilisés. Le prompt caching peut réduire le coût des préfixes répétés, mais ne réduit pas le nombre de tokens dans la fenêtre de contexte. Le partitionnement modifie les capacités et les preuves reçues par chaque décision. Le guide d’Anthropic sur le contexte des outils explicite ces distinctions, tandis que sa documentation sur l’édition du contexte expose des déclencheurs configurables plutôt qu’un seuil universel.

Compacter l’historique terminé

Remplacez les anciens tours de conversation par une transmission structurée consignant les décisions, les questions non résolues, les artefacts modifiés et l’état des tests. Conservez le transcript ou les artefacts originaux adressables lorsque la revue ou la reprise l’exige.

Masquer les observations verbeuses

Un outil peut renvoyer des pages de logs alors que l’étape suivante n’a besoin que d’un statut, d’un code d’erreur et d’une référence d’artefact. Convertissez le résultat brut en observation typée après l’avoir validé, et conservez le payload complet en dehors du prompt. Ne laissez pas le modèle résumer et faire disparaître la seule preuve de l’échec.

Préserver les préfixes pouvant être mis en cache

Les fournisseurs et les runtimes peuvent réutiliser du calcul lorsque le début d’une requête reste stable. Conservez les instructions durables et les tool schemas dans un ordre cohérent, et déplacez les horodatages, identifiants de requête, preuves récupérées et état actuel dans le suffixe dynamique. Vérifiez les sémantiques de cache du fournisseur avant de concevoir votre système autour d’elles.

Partitionner par décision

Un planner, un retriever, un tool caller et une étape de réponse finale n’ont pas besoin des mêmes éléments. Donnez à chaque étape le minimum d’instructions fiables, d’état, de preuves et d’outils nécessaire. Le partitionnement réduit simultanément l’utilisation des tokens et l’exposition des capacités, mais seules les évaluations au niveau de la tâche peuvent montrer s’il a supprimé des informations nécessaires.

Sécurisez la supply chain du contexte

Les recherches sur la prompt injection considèrent le contenu externe non fiable comme une surface d’attaque (article). Dans le modèle opérationnel de cet article, l’empoisonnement du contexte peut provenir de documents, de mémoires, de tool results, de skills ou de messages antérieurs de l’assistant. Marquer un texte comme « non fiable » aide le modèle, mais l’enforcement doit être architectural.

La checklist de supply chain suivante constitue ma recommandation d’ingénierie. Elle transforme les frontières du protocole et du threat model en contrôles applicatifs. Ni la spécification MCP ni l’article sur la prompt injection n’imposent l’intégralité de cette checklist.

Utilisez ces frontières :

1. Autoriser avant le retrieval et l’exécution des outils.
2. Séparer les données des canaux d’instructions et délimiter le texte externe.
3. Autoriser les outils par allowlist pour chaque étape et chaque acteur. Par défaut, n’offrir aucune capacité à effets de bord.
4. Valider les identifiants de ressources au lieu de laisser le modèle inventer des clés de tenant ou des chemins de fichiers.
5. Exiger une confirmation pour les opérations à fort impact selon la policy, et non selon la confiance du modèle.
6. Scanner et examiner les skills exécutables ou les connecteurs avant leur installation.
7. Empêcher les secrets et le contexte sensible brut d’entrer dans les logs et la mémoire à long terme.

La « réparation » automatique n’est appropriée que pour les modifications qui préservent le sens, comme l’analyse d’un format de date connu. Compléter des arguments d’outil manquants avec des « valeurs par défaut raisonnables » peut modifier l’opération. Demandez une clarification ou rejetez la requête lorsque le sens est incertain.

Exemple détaillé : une demande d’assistance concernant une clé API

Pour « Pourquoi ma clé API ne fonctionne-t-elle pas ? », la prochaine décision consiste à collecter des preuves de diagnostic, et non à générer la réponse finale. L’assembleur peut inclure :

• la policy d’assistance fiable et le contrat de réponse
• l’identifiant de compte authentifié et le plan issus de l’état applicatif
• l’objectif actuel du ticket et les actions déjà tentées
• deux extraits actuels du runbook sélectionnés dans le périmètre du produit et de la version
• une mémoire à périmètre contrôlé indiquant que la clé a été créée il y a trois jours, avec sa provenance
• check_api_key_status et search_incidents, mais pas les outils de suppression ou de rotation de clés

Le modèle propose une vérification d’état en lecture seule. Le code applicatif autorise le compte, appelle l’outil et enregistre une observation typée. Un second appel au modèle reçoit les extraits pertinents du runbook ainsi que cette observation. La réponse finale cite la version du runbook, n’affiche jamais la clé et propose la rotation uniquement comme une action autorisée séparément.

Notez ce qui reste exclu : l’historique sans rapport du ticket, tous les exemples d’assistance, les dumps bruts du compte, les outils de mutation et les mémoires d’autres tenants.

Anti-patterns à tester explicitement

• Remplir la fenêtre : charger tous les documents récupérés, l’historique, les mémoires et les outils parce qu’il reste de la capacité.
• RAG partout : utiliser le retrieval sémantique pour des valeurs qui devraient résider dans une base de données, un service de policy ou un état applicatif authentifié.
• Mémoire sans limites : conserver des faits inférés sans périmètre, expiration, mécanisme de correction ou sémantique de suppression.
• Un seul appel pour toutes les étapes : demander à un prompt unique de récupérer, raisonner, autoriser, modifier et expliquer sans frontières observables.
• Schema égal exactitude : considérer qu’un JSON valide prouve que les valeurs, les permissions ou les décisions métier sont valides.
• Aucune évaluation des composants : évaluer uniquement la prose finale et ignorer les échecs de retrieval, de sélection du contexte ou des outils.

Transformez chaque anti-pattern en contre-exemple dans le jeu d’évaluation. Une recommandation qui n’est jamais exercée par une tâche ou une trace est facile à violer sans s’en rendre compte.

Évaluez l’assembleur, pas seulement la réponse

Créez un jeu de tâches fixe avec des labels de preuves, des frontières de permissions, les tool calls requis et les actions interdites. Pour chaque modification de la policy de contexte, mesurez :

Utilisez des ablations pour identifier la valeur causale : retirez la mémoire, le reranking, les exemples ou la compression un par un. Un composant qui ajoute des tokens sans améliorer la tranche pertinente ne devrait pas être chargé par défaut.

Conclusion

Un bon context engineering est sélectif et responsable. Il ne remplit pas une grande fenêtre simplement parce que la capacité est disponible. Il construit un working set spécifique à chaque étape à partir d’instructions fiables, d’un état canonique de la tâche, de preuves à périmètre contrôlé, d’une mémoire revue et d’outils autorisés.

La boucle est courte : assembler, produire le manifest, proposer, valider, exécuter et évaluer. Lorsqu’une décision échoue, cette boucle indique si l’élément manquant était une preuve, la fraîcheur, l’autorité, l’état ou la policy. Elle fournit également un test pour la prochaine modification.

Références

• Lost in the Middle — utilisation du long contexte dépendante de la position
• RULER — évaluation multi-tâche de la longueur effective du contexte
• OpenAI Model Spec — niveaux d’autorité des instructions propres au fournisseur
• Anthropic Messages API — structure du paramètre système et des rôles de message
• Manage tool context — chargement sélectif des outils, caching et édition du contexte
• Anthropic context editing — suppression configurable des tool results et compaction
• Model Context Protocol specification — concepts du protocole et spécification actuelle
• Evaluating Context Compression for AI Agents — approche en tokens par tâche et évaluation par probes
• Formalizing and Benchmarking Prompt Injection Attacks and Defenses — taxonomie des menaces et défenses