Ir al contenido principal
Español— Elegir un idioma
Menú

Variables de contexto y memoria del agente

Lección 13 de 25 Actualizado el 29 de julio de 2026 Desarrollador
En esta página
  1. Variables de contexto y memoria del agente
  2. Variables de contexto: estado compartido
  3. Instrucciones dinámicas
  4. Memoria conversacional de varios turnos
  5. Patrón: memoria persistente con una base de datos
  6. Contexto frente a instrucciones: cuándo usar cada uno
  7. Puntos clave

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.

NecesidadSolución
Datos de usuario (nombre, rol)Variables de contexto
Comportamiento del agenteInstrucciones (estáticas o dinámicas)
Historial de conversaciónresult.to_input_list()
Memoria a largo plazoHerramientas + base de datos
Configuración en tiempo de ejecuciónVariables de contexto

Puntos clave

  • RunContextWrapper transporta 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