Stratégie de contexte pour les agents
Na tejto strane
Le défi du contexte pour les agents
Un agent autonome enchaîne des dizaines d’appels API : il raisonne, utilise des outils, lit les résultats et itère. À chaque étape, le contexte grossit. La différence avec une conversation ordinaire, c’est que cette croissance ne vient pas de l’utilisateur, mais de l’agent lui-même : une requête SQL renvoyant trois cents lignes, une page web entière récupérée ou un fichier de journal complet lu. Sans stratégie de gestion, un agent atteint la limite de contexte en quelques itérations seulement, souvent avant d’avoir terminé la tâche que tu lui as confiée.
Concevoir un agent qui gère efficacement sa mémoire revient donc à répondre à trois questions : ce qui doit rester intact, ce qui peut être résumé et ce qui n’aurait jamais dû entrer dans le contexte en premier lieu. Nous allons les aborder dans cet ordre.
Une mémoire à trois niveaux
La structure que nous utilisons s’appuie sur la distinction classique entre mémoire de travail, mémoire épisodique et mémoire sémantique. La mémoire de travail conserve les actions les plus récentes sous leur forme brute, car l’agent en a besoin exactement telles quelles pour décider de la suite. La mémoire épisodique garde des résumés des étapes passées : l’agent sait qu’il a exploré telle piste et ce que cela a donné, sans avoir à relire les détails. Enfin, la mémoire sémantique accumule des faits établis une fois pour toutes — l’ID client, la version du schéma de base de données, la contrainte budgétaire — qui ne doivent jamais se perdre dans un résumé.
from dataclasses import dataclass, field
@dataclass
class AgentMemory:
"""Système de mémoire à trois niveaux pour un agent."""
# Niveau 1 : mémoire de travail (contexte actuel)
working: list[dict] = field(default_factory=list)
# Niveau 2 : mémoire épisodique (résumés des étapes passées)
episodes: list[str] = field(default_factory=list)
# Niveau 3 : mémoire sémantique (faits permanents)
facts: list[str] = field(default_factory=list)
max_tokens_working: int = 20_000
max_episodes: int = 10
def add_action(self, action: str, result: str):
"""Ajoute une action à la mémoire de travail."""
self.working.append({
"action": action,
"result": result[:2000], # Tronquer les résultats longs
})
self._check_compaction()
def add_fact(self, fact: str):
"""Ajoute un fait permanent."""
if fact not in self.facts:
self.facts.append(fact)
def _check_compaction(self):
tokens = sum(
len(str(e)) // 4 for e in self.working
)
if tokens > self.max_tokens_working:
self._compact()
def _compact(self):
"""Compacte la mémoire de travail en un épisode."""
import openai
client = openai.OpenAI()
text = "\n".join(
f"Action: {a['action']}\nResult: {a['result']}"
for a in self.working[:-2]
)
response = client.responses.create(
model="gpt-5.6-terra",
input=(
"Résume ces actions de l'agent en 3 à 5 points clés. "
"Conserve les faits importants, les résultats et les décisions.\n\n"
f"{text}"
),
max_output_tokens=300,
)
self.episodes.append(response.output_text)
self.working = self.working[-2:] # Garder les 2 dernières actions
# Limiter le nombre d'épisodes
if len(self.episodes) > self.max_episodes:
self.episodes = self.episodes[-self.max_episodes:]
def build_context(self) -> str:
"""Construit le contexte complet pour le prochain appel."""
parts = []
if self.facts:
parts.append(
"Faits établis :\n" + "\n".join(f"- {f}" for f in self.facts)
)
if self.episodes:
parts.append(
"Historique résumé :\n" + "\n---\n".join(self.episodes)
)
if self.working:
parts.append(
"Actions récentes :\n" + "\n".join(
f"- {a['action']} → {a['result'][:500]}"
for a in self.working
)
)
return "\n\n".join(parts)
Deux paramètres méritent discussion avant que tu ne les copies tels quels. La troncature à 2 000 caractères dans add_action protège contre les outils verbeux, mais elle coupe aveuglément : si tes outils renvoient du JSON, tu te retrouveras avec un objet invalide au milieu de ton contexte. Et max_episodes: 10 impose une amnésie bornée : au onzième résumé, le premier disparaît. Pour un agent qui tourne longtemps, promeus les faits importants vers facts avant qu’ils ne sortent de la fenêtre épisodique, sinon tu les perdras définitivement.
Maîtriser les résultats des outils
Les outils renvoient souvent des résultats volumineux : pages web, résultats SQL, contenus de fichiers. C’est de loin la cause principale de saturation du contexte pour un agent, et c’est aussi la plus facile à corriger car tu la gères à l’ingestion plutôt qu’après coup.
La fonction ci-dessous propose trois stratégies de troncature. Le mode start convient aux documents dont l’essentiel se trouve en haut, comme un article ou un rapport. Le mode start_end fonctionne lorsque la fin porte l’information décisive : une trace d’exécution où l’erreur apparaît en dernier, un fichier de journal ou une réponse paginée dont le total figure à la fin. Le mode summary coûte un appel API supplémentaire, ce qui ne se justifie que pour des contenus longs vraiment utiles à la suite du raisonnement.
def truncate_tool_result(
result: str,
max_tokens: int = 2000,
strategy: str = "start_end",
) -> str:
"""Tronque un résultat d'outil tout en préservant les informations clés."""
estimated_tokens = len(result) // 4
if estimated_tokens <= max_tokens:
return result
max_chars = max_tokens * 4
match strategy:
case "start":
return result[:max_chars] + "\n[... tronqué]"
case "start_end":
half = max_chars // 2
return (
result[:half]
+ "\n[... milieu tronqué ...]\n"
+ result[-half:]
)
case "summary":
import openai
client = openai.OpenAI()
response = client.responses.create(
model="gpt-5.6-terra",
input=f"Résume ces données en gardant l'essentiel :\n{result}",
max_output_tokens=max_tokens,
)
return response.output_text
return result[:max_chars]
Les résultats tabulaires nécessitent un traitement spécial. Couper un tableau SQL en son milieu supprime l’en-tête ou fausse le sens du volume : l’agent voit vingt lignes et conclut que le tableau n’en contient que vingt. Le filtre ci-dessous conserve l’en-tête, un échantillon du début et de la fin, et — c’est le point clé — indique explicitement le nombre de lignes omises et le total. L’agent sait alors qu’il regarde un extrait et peut décider d’exécuter une requête d’agrégation plutôt que de raisonner sur un échantillon.
def filter_sql_result(result: str, question: str) -> str:
"""Filtre un résultat SQL pour ne garder que ce qui est pertinent."""
lines = result.strip().split("\n")
if len(lines) <= 20:
return result
# Garder l'en-tête et les premières/dernières lignes
header = lines[0]
first_lines = lines[1:6]
last_lines = lines[-5:]
return (
f"{header}\n"
+ "\n".join(first_lines)
+ f"\n[... {len(lines) - 11} lignes omises ...]\n"
+ "\n".join(last_lines)
+ f"\n\nTotal : {len(lines) - 1} lignes"
)
Quand plusieurs agents travaillent ensemble
Lorsque plusieurs sous-agents travaillent en parallèle, la tentation est de leur donner à tous le contexte complet, juste par sécurité. C’est le meilleur moyen de multiplier ta facture par le nombre d’agents tout en dégradant leurs performances, car un contexte encombré rend le modèle moins précis sur sa propre tâche. Partage plutôt le contexte minimal : l’objectif global pour que l’agent comprenne à quoi il contribue, son propre rôle, les contraintes communes et un extrait borné des résultats produits par ses pairs.
@dataclass
class SharedContext:
"""Contexte partagé entre les sous-agents."""
objective: str
constraints: list[str]
partial_results: dict[str, str] = field(default_factory=dict)
def context_for_sub_agent(self, role: str) -> str:
"""Génère un contexte ciblé pour un sous-agent."""
return (
f"Objectif global : {self.objective}\n"
f"Ton rôle : {role}\n"
f"Contraintes : {', '.join(self.constraints)}\n"
f"Résultats des autres agents :\n"
+ "\n".join(
f"- {k}: {v[:200]}"
for k, v in self.partial_results.items()
)
)
La limite de 200 caractères par résultat partiel reflète une intention : un sous-agent a besoin de savoir ce que les autres ont trouvé, pas comment ils l’ont trouvé. Si tes agents ont besoin du détail complet des résultats voisins, tu dois probablement repenser la façon dont tu as réparti les rôles.
Kľúčové poznatky
- Structure la mémoire de l’agent en trois niveaux : travail, épisodique, sémantique
- Compacte automatiquement lorsque la mémoire de travail dépasse le seuil
- Tronque les résultats des outils avant de les injecter dans le contexte
- Signale toujours qu’un résultat a été tronqué, et dans quelle proportion
- Pour les configurations multi-agents, partage un contexte minimal ciblé par rôle