Variables de contexto y memoria del agente
En esta página
Variables de contexto y memoria del agente
Un agente sin memoria lo olvida todo entre ejecuciones: pide el nombre del cliente en cada mensaje y empieza desde cero en cada turno. Dos mecanismos complementarios solucionan esto. Las variables de contexto inyectan estado compartido en el agente y sus herramientas, mientras que la memoria conversacional mantiene el hilo de una conversación de varios turnos.
Variables de contexto: estado compartido
El objeto RunContextWrapper es un objeto tipado que circula entre el agente, sus herramientas y sus barreras de seguridad (guardrails). En concreto, defines una clase de datos (dataclass) que describe la sesión (identidad, cesta, preferencias) y cada herramienta la recibe como primer parámetro. En el ejemplo siguiente, ajouter_au_panier escribe en este objeto y voir_panier lo lee de vuelta: ambas herramientas comparten la misma cesta sin que ningún dato pase por el 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:
"""Añade un producto a la cesta del usuario."""
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:
"""Muestra el contenido de la cesta."""
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]",
)
# El contexto se comparte entre todas las herramientas
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}")
El contexto es mutable: las herramientas pueden modificarlo y los cambios persisten tras la ejecución. Esto es lo que hace interesante la última línea: después de run_sync, el objeto session de tu aplicación contiene realmente los dos artículos, listos para enviarse a tu sistema de pedidos.
Instrucciones dinámicas
Este estado no sirve solo para las herramientas: también puede moldear el comportamiento del agente. Las instrucciones pueden ser una función que recibe el contexto y construye el prompt del sistema al vuelo, incluyendo el nombre del cliente y su idioma preferido.
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",
)
Las instrucciones se evalúan en cada turno del bucle del agente, lo que permite una personalización en tiempo real: si una herramienta acaba de añadir un artículo, el siguiente turno lo tiene en cuenta inmediatamente en el prompt del sistema.
Memoria conversacional de varios turnos
El contexto transporta datos, no el diálogo en sí. Para mantener una conversación a lo largo de varios intercambios, pasa el historial. El principio se reduce a tres pasos: añades el mensaje del usuario, ejecutas el agente con la lista completa y luego reemplazas tu historial con el que devuelve el resultado, incluyendo mensajes, llamadas a herramientas y respuestas.
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:
# Añade el mensaje del usuario al historial
historique.append({"role": "user", "content": message_utilisateur})
# Ejecuta el agente con el historial completo
result = await Runner.run(agent, historique)
# Guarda los nuevos intercambios para el siguiente turno
historique.clear()
historique.extend(result.to_input_list())
return result.final_output
# Simula una conversación
async def demo():
print(await converser("My name is Thomas."))
print(await converser("What is my first name?")) # El agente lo recuerda
print(await converser("Recommend a good restaurant in Paris."))
Esta memoria vive en la RAM. Desaparece cuando redespliegas tu servicio y crece indefinidamente si la conversación se alarga: dos límites que debes tener en cuenta antes de pasar a producción.
Patrón: memoria persistente con una base de datos
Para una memoria que sobreviva a los reinicios, almacena el historial en una base de datos. El enfoque que presentamos aquí va un paso más allá: en lugar de guardarlo todo, el agente decide por sí mismo qué merece la pena retener, mediante un par de herramientas de guardado y recuperación. El cliente dice «Soy alérgico a los cacahuetes», el agente llama a sauvegarder_note y la información sigue disponible tres semanas después.
import json
from agents import Agent, Runner, function_tool
@function_tool
async def sauvegarder_note(ctx: RunContextWrapper, cle: str, valeur: str) -> str:
"""Guarda información para recordarla más tarde."""
# En producción: escribir en la base de datos
notes = ctx.context.notes
notes[cle] = valeur
return f"Note saved: {cle} = {valeur}"
@function_tool
async def recuperer_note(ctx: RunContextWrapper, cle: str) -> str:
"""Recupera información guardada anteriormente."""
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",
)
Contexto frente a instrucciones: cuándo usar cada uno
Estos cuatro mecanismos se solapan parcialmente y el error clásico es enrutarlo todo a través de las instrucciones. La tabla siguiente resume la correspondencia que debes recordar.
| Necesidad | Solución |
|---|---|
| Datos de usuario (nombre, rol) | Variables de contexto |
| Comportamiento del agente | Instrucciones (estáticas o dinámicas) |
| Historial de conversación | result.to_input_list() |
| Memoria a largo plazo | Herramientas + base de datos |
| Configuración en tiempo de ejecución | Variables de contexto |
Puntos clave
RunContextWrappertransporta estado tipado accesible por todas las herramientas- El contexto es mutable: las herramientas pueden modificarlo durante la ejecución
- Las instrucciones dinámicas (funciones) se adaptan al contexto en cada turno
- El historial conversacional se mantiene con
result.to_input_list() - Para memoria persistente, combina herramientas de guardado con una base de datos