Variabile de context și memoria agentului
Pe această pagină
Variabile de context și memoria agentului
Un agent fără memorie uită totul între execuții: cere numele clientului la fiecare mesaj și o ia de la capăt la fiecare interacțiune. Două mecanisme complementare rezolvă această problemă. Variabilele de context injectează o stare partajată în agent și în instrumentele sale, în timp ce memoria conversațională menține firul unei conversații pe mai multe tururi.
Variabile de context: Stare partajată
RunContextWrapper este un obiect tipizat care circulă între agent, instrumentele sale și sistemele de protecție (guardrails). Concret, definiți o clasă de date (dataclass) care descrie sesiunea—identitate, coș de cumpărături, preferințe—iar fiecare instrument o primește ca prim parametru. În exemplul de mai jos, ajouter_au_panier scrie în acest obiect, iar voir_panier îl citește ulterior: ambele instrumente partajează același coș fără ca datele să treacă prin 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}")
Contextul este mutabil: instrumentele îl pot modifica, iar schimbările persistă după execuție. Acest lucru face ca ultima linie să fie interesantă—după run_sync, obiectul session al aplicației dumneavoastră conține efectiv cele două articole, gata de a fi trimise către sistemul de comenzi.
Instrucțiuni dinamice
Această stare nu servește doar instrumentelor: poate modela și comportamentul agentului. Instrucțiunile pot fi o funcție care primește contextul și construiește promptul de sistem din mers, incluzând numele clientului și limba preferată.
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",
)
Instrucțiunile sunt evaluate la fiecare tur al buclei agentului, permițând o personalizare în timp real: dacă un instrument tocmai a adăugat un articol, următorul tur ține cont imediat de acest lucru în promptul de sistem.
Memoria conversațională pe mai multe tururi
Contextul transportă date, nu dialogul în sine. Pentru a menține o conversație pe mai multe schimburi, trebuie să transmiteți istoricul. Principiul se reduce la trei pași: adăugați mesajul utilizatorului, rulați agentul pe lista completă, apoi înlocuiți istoricul dumneavoastră cu cel returnat de rezultat—incluzând mesaje, apeluri de instrumente și răspunsuri.
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."))
Această memorie trăiește în RAM. Dispare atunci când redeployați serviciul și crește la infinit dacă conversația durează: două limite de care trebuie să țineți cont înainte de a trece în producție.
Model: Memorie persistentă cu o bază de date
Pentru o memorie care supraviețuiește repornirilor, stocați istoricul într-o bază de date. Abordarea prezentată aici merge un pas mai departe: în loc să păstrați totul, agentul decide singur ce merită reținut, prin intermediul unei perechi de instrumente de salvare și recuperare. Clientul spune „Sunt alergic la arahide“, agentul apelează sauvegarder_note, iar informația rămâne disponibilă trei săptămâni mai târziu.
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",
)
Context vs. Instrucțiuni: Când să folosiți ce
Aceste patru mecanisme se suprapun parțial, iar greșeala clasică este de a direcționa totul prin instrucțiuni. Tabelul de mai jos rezumă corespondența de reținut.
| Necesitate | Soluție |
|---|---|
| Date utilizator (nume, rol) | Variabile de context |
| Comportament agent | Instrucțiuni (statice sau dinamice) |
| Istoric conversație | result.to_input_list() |
| Memorie pe termen lung | Instrumente + bază de date |
| Configurație runtime | Variabile de context |
Puncte cheie
RunContextWrappertransportă o stare tipizată accesibilă tuturor instrumentelor- Contextul este mutabil: instrumentele îl pot modifica în timpul execuției
- Instrucțiunile dinamice (funcții) se adaptează la context la fiecare tur
- Istoricul conversațional este menținut cu
result.to_input_list() - Pentru memorie persistentă, combinați instrumentele de salvare cu o bază de date