Variables de contexte et mémoire de l'agent
Na ovoj stranici
Variables de contexte et mémoire de l’agent
Un agent sans mémoire oublie tout entre deux exécutions : il demande le nom du client à chaque message et repart de zéro à chaque tour. Deux mécanismes complémentaires résolvent ce problème. Les variables de contexte injectent un état partagé dans l’agent et ses outils, tandis que la mémoire conversationnelle maintient le fil d’une conversation sur plusieurs tours.
Variables de contexte : état partagé
Le RunContextWrapper est un objet typé qui circule entre l’agent, ses outils et ses garde-fous. Concrètement, tu définis une classe de données (dataclass) décrivant la session — identité, panier, préférences — et chaque outil la reçoit comme premier paramètre. Dans l’exemple ci-dessous, ajouter_au_panier écrit dans cet objet et voir_panier le relit : les deux outils partagent le même panier sans qu’aucune donnée ne transite par le prompt.
from dataclasses import dataclass, field
from agents import Agent, Runner, RunContextWrapper, function_tool
@dataclass
class SessionUtilisateur:
user_id: str
nom: str
email: str
panier: list[dict] = field(default_factory=list)
preferences: dict = field(default_factory=dict)
@function_tool
def ajouter_au_panier(
ctx: RunContextWrapper[SessionUtilisateur],
produit: str,
quantite: int = 1,
) -> str:
"""Adds a product to the user's cart."""
ctx.context.panier.append({"produit": produit, "quantite": quantite})
total = len(ctx.context.panier)
return f"{produit} (x{quantite}) added to cart. Total: {total} item(s)."
@function_tool
def voir_panier(ctx: RunContextWrapper[SessionUtilisateur]) -> str:
"""Displays the cart contents."""
if not ctx.context.panier:
return "Your cart is empty."
lignes = [f"- {item['produit']} x{item['quantite']}" for item in ctx.context.panier]
return f"Cart for {ctx.context.nom}:\n" + "\n".join(lignes)
agent = Agent(
name="Shop Agent",
instructions="You help customers with their shopping.",
tools=[ajouter_au_panier, voir_panier],
model="gpt-5.6-terra",
)
session = SessionUtilisateur(
user_id="usr_789",
nom="Marie Dupont",
email="[email protected]",
)
# Context is shared across all tools
result = Runner.run_sync(agent, "Add a laptop and two mice to my cart", context=session)
print(result.final_output)
print(f"Cart after execution: {session.panier}")
Le contexte est mutable : les outils peuvent le modifier et les changements persistent après l’exécution. C’est ce qui rend la dernière ligne intéressante : après run_sync, l’objet session de ton application contient réellement les deux articles, prêts à être envoyés à ton système de commandes.
Instructions dynamiques
Cet état ne sert pas qu’aux outils : il peut aussi façonner le comportement de l’agent. Les instructions peuvent être une fonction qui reçoit le contexte et construit le prompt système à la volée, en incluant le nom du client et sa langue préférée.
def instructions_dynamiques(ctx: RunContextWrapper[SessionUtilisateur]) -> str:
prefs = ctx.context.preferences
langue = prefs.get("langue", "français")
return f"""You are a sales assistant.
The customer's name is {ctx.context.nom}.
Their email is {ctx.context.email}.
They have {len(ctx.context.panier)} item(s) in their cart.
Communicate in {langue}."""
agent = Agent(
name="Personalized Agent",
instructions=instructions_dynamiques,
tools=[ajouter_au_panier, voir_panier],
model="gpt-5.6-terra",
)
Les instructions sont évaluées à chaque tour de la boucle de l’agent, permettant une personnalisation en temps réel : si un outil vient d’ajouter un article, le tour suivant en tient immédiatement compte dans le prompt système.
Mémoire conversationnelle multi-tours
Le contexte transporte des données, pas le dialogue lui-même. Pour maintenir une conversation sur plusieurs échanges, tu dois transmettre l’historique. Le principe se résume en trois étapes : tu ajoutes le message de l’utilisateur, tu exécutes l’agent sur la liste complète, puis tu remplaces ton historique par celui retourné dans le résultat — incluant messages, appels d’outils et réponses.
from agents import Agent, Runner
agent = Agent(
name="Assistant",
instructions="You are an assistant that remembers the conversation.",
model="gpt-5.6-terra",
)
historique = []
async def converser(message_utilisateur: str) -> str:
# Add the user's message to the history
historique.append({"role": "user", "content": message_utilisateur})
# Run the agent with the full history
result = await Runner.run(agent, historique)
# Save new exchanges for the next turn
historique.clear()
historique.extend(result.to_input_list())
return result.final_output
# Simulate a conversation
async def demo():
print(await converser("My name is Thomas."))
print(await converser("What is my first name?")) # The agent remembers
print(await converser("Recommend a good restaurant in Paris."))
Cette mémoire réside en RAM. Elle disparaît lorsque tu redéploies ton service et grossit indéfiniment si la conversation dure : deux limites à garder en tête avant de passer en production.
Modèle : mémoire persistante avec une base de données
Pour une mémoire qui survit aux redémarrages, stocke l’historique dans une base de données. L’approche présentée ici va plus loin : au lieu de tout conserver, l’agent décide lui-même de ce qui mérite d’être retenu, via une paire d’outils de sauvegarde et de récupération. Le client dit „Je suis allergique aux arachides“, l’agent appelle sauvegarder_note, et l’information reste disponible trois semaines plus tard.
import json
from agents import Agent, Runner, function_tool
@function_tool
async def sauvegarder_note(ctx: RunContextWrapper, cle: str, valeur: str) -> str:
"""Saves information to remember later."""
# In production: write to database
notes = ctx.context.notes
notes[cle] = valeur
return f"Note saved: {cle} = {valeur}"
@function_tool
async def recuperer_note(ctx: RunContextWrapper, cle: str) -> str:
"""Retrieves previously saved information."""
notes = ctx.context.notes
valeur = notes.get(cle)
if valeur:
return f"{cle} = {valeur}"
return f"No note found for '{cle}'"
@dataclass
class ContexteMemoire:
user_id: str
notes: dict = field(default_factory=dict)
agent = Agent(
name="Assistant with Memory",
instructions="""You are an assistant with persistent memory.
Use sauvegarder_note to retain important information
and recuperer_note to retrieve it.""",
tools=[sauvegarder_note, recuperer_note],
model="gpt-5.6-terra",
)
Contexte vs instructions : quand utiliser quoi
Ces quatre mécanismes se chevauchent partiellement et l’erreur classique consiste à tout faire passer par les instructions. Le tableau ci-dessous résume la correspondance à retenir.
| Besoin | Solution |
|---|---|
| Données utilisateur (nom, rôle) | Variables de contexte |
| Comportement de l’agent | Instructions (statiques ou dynamiques) |
| Historique de conversation | result.to_input_list() |
| Mémoire à long terme | Outils + base de données |
| Configuration d’exécution | Variables de contexte |
Ključne točke
RunContextWrappertransporte un état typé accessible par tous les outils- Le contexte est mutable : les outils peuvent le modifier pendant l’exécution
- Les instructions dynamiques (fonctions) s’adaptent au contexte à chaque tour
- L’historique conversationnel est maintenu avec
result.to_input_list() - Pour une mémoire persistante, combine des outils de sauvegarde avec une base de données