Contexto y memoria del cliente: Don Plátano aprende a continuar una conversación

Contexto y memoria del cliente: Don Plátano aprende a continuar una conversación

Artículo 4 de 5 · PydanticAI desde cero en Google Colab

Don Plátano ya sabe consultar herramientas. Ahora necesita saber a quién atiende y qué se dijo antes. Son dos problemas distintos: un perfil no es una conversación.

Al terminar podrás pasar datos con deps, leerlos desde RunContext, construir un mensaje de sistema dinámico y continuar una charla con message_history. También prepararás pruebas sin pagar llamadas al modelo.

1. Antes de empezar

Necesitas un runtime de Colab con Python 3.11 o superior. Ejecuta las celdas en orden. Este notebook funciona primero con pruebas simuladas: no requieren API key. Para la demostración real necesitas saldo y una clave de OpenRouter.

La instalación descarga paquetes. Las pruebas con TestModel no consultan un LLM, pero las demostraciones reales sí consumen tokens. Reenviar un historial aumenta el contenido de entrada y puede aumentar el costo. No fijamos una tarifa: depende del modelo y proveedor vigentes.

Aquí usamos presupuestos ficticios, cantidades enteras en MXN y un precio didáctico de 5 MXN por banana. No consultamos tipos de cambio ni hacemos operaciones financieras.

2. Preparación

Instalamos pydantic-ai-slim[openrouter]==2.68.0, versión identificada en PyPI al preparar este borrador. Es el mismo espacio de importación pydantic_ai, con las dependencias del proveedor que necesitamos. La versión fijada se validó en Colab con Python 3.13.18, Pydantic 2.14.2 y nest-asyncio 1.6.0.

No ocultamos la salida de instalación: si aparece un conflicto, revisa qué paquetes afecta. Si Colab pide reiniciar la sesión, hazlo y continúa desde la siguiente celda.

Celda 1

import subprocess
import sys

if sys.version_info < (3, 11):
    raise RuntimeError("Selecciona un runtime con Python 3.11 o superior.")

subprocess.check_call([
    sys.executable, "-m", "pip", "install",
    "pydantic-ai-slim[openrouter]==2.68.0", "nest_asyncio",
])

Celda 2

from importlib.metadata import version
import platform
import nest_asyncio

print("Python:", platform.python_version())
print("pydantic-ai-slim:", version("pydantic-ai-slim"))
print("pydantic:", version("pydantic"))
print("nest-asyncio:", version("nest-asyncio"))
nest_asyncio.apply()

Salida

Python: 3.13.18
pydantic-ai-slim: 2.68.0
pydantic: 2.14.2
nest-asyncio: 1.6.0

Conservamos run_sync y nest_asyncio para seguir el estilo de la serie en Colab. El parche permite este uso dentro del bucle de eventos del notebook; no es un requisito universal de PydanticAI.

3. Cuatro piezas, cuatro responsabilidades

PiezaPara qué sirve aquíQué no hace por sí sola
deps_type=ClienteDeclara el tipo de dependencias del agenteNo crea un cliente ni valida cualquier objeto que se le pase
deps=anaEntrega el objeto de esta ejecuciónNo lo envía completo automáticamente al modelo
RunContext[Cliente]Permite acceder a esos datos mediante ctx.depsNo recupera conversaciones anteriores
message_historyAporta mensajes previos al nuevo turnoNo guarda nada después de cerrar Colab

Los type hints de las herramientas y sus docstrings forman parte de la interfaz que interpreta PydanticAI. Aquí sí tienen una función práctica.

4. Un cliente validado antes de llamar al agente

Reutilizamos Pydantic, que conociste en el artículo 2. El perfil contiene solo los datos del ejercicio. La validación ocurre cuando construimos Cliente; no por escribir deps_type.

Ana tiene 100 MXN y Bruno 250 MXN. frozen=True evita reasignaciones accidentales de campos en estos perfiles simples.

Celda 3

from typing import Literal
from pydantic import BaseModel, ConfigDict, Field, ValidationError
from pydantic_ai import Agent, RunContext

class Cliente(BaseModel):
    model_config = ConfigDict(frozen=True)
    cliente_id: str = Field(min_length=1)
    nombre: str = Field(min_length=1)
    presupuesto_mxn: int = Field(ge=0, strict=True)
    estilo: Literal["breve", "detallado"] = "breve"

ana = Cliente(cliente_id="ana", nombre="Ana", presupuesto_mxn=100)
bruno = Cliente(
    cliente_id="bruno", nombre="Bruno", presupuesto_mxn=250,
    estilo="detallado",
)
print(ana.model_dump())

Salida

{'cliente_id': 'ana', 'nombre': 'Ana', 'presupuesto_mxn': 100, 'estilo': 'breve'}

5. El mismo agente, datos distintos

En el artículo 3 usamos RunContext[None]. Ahora el parámetro es Cliente y ctx.deps contiene el perfil que entregamos en cada ejecución.

Creamos el agente sin modelo predeterminado: las pruebas lo sustituirán con override, y la demostración elegirá OpenRouter al ejecutarse. Así no necesitamos una clave para definir el agente.

Celda 4

agente = Agent(
    deps_type=Cliente,
    system_prompt=(
        "Eres Don Plátano, corredor teatral del Banano Exchange. "
        "Responde en español con humor ligero. Este es un ejercicio ficticio. "
        "No inventes datos del cliente ni compras anteriores. "
        "Para consultar el presupuesto usa resumen_presupuesto. "
        "No ejecutas compras ni modificas saldos. "
        "Si una referencia no aparece en el historial, pide aclaración."
    ),
)

@agente.system_prompt(dynamic=True)
def instrucciones_cliente(ctx: RunContext[Cliente]) -> str:
    cliente = ctx.deps
    return (
        f"Cliente actual: {cliente.nombre}. "
        f"Estilo de respuesta: {cliente.estilo}. "
        "El perfil no contiene el objeto de interés de la conversación."
    )

@agente.tool
def resumen_presupuesto(ctx: RunContext[Cliente]) -> dict:
    """Consulta el presupuesto ficticio y su equivalencia en bananas a 5 MXN cada una."""
    return {
        "presupuesto_mxn": ctx.deps.presupuesto_mxn,
        "precio_ficticio_banana_mxn": 5,
        "bananas_enteras": ctx.deps.presupuesto_mxn // 5,
    }

La herramienta toma el presupuesto de ctx.deps; el modelo no recibe un argumento para elegir otro cliente. La división entera cuenta bananas completas: con 103 MXN serían 20, sin gastar ni descontar nada.

El perfil vive en Python. El texto que devolvemos desde instrucciones_cliente y el resultado de la herramienta sí pueden llegar al modelo. Por eso no colocamos secretos en esos textos.

Por qué dynamic=True

Registrar una función con @agente.system_prompt permite construir un mensaje de sistema. Añadir dynamic=True hace que se reevalúe también al reutilizar un historial que contiene ese mensaje dinámico. Eso evita conservar, por ejemplo, un estilo anterior tras actualizar el perfil del mismo cliente.

Este mecanismo no separa usuarios ni borra datos viejos. Nunca lo uses como justificación para pasar el historial de Ana a Bruno. Para nuevos proyectos también existe @agente.instructions; aquí conservamos system_prompt para desarrollar el temario de la serie.

6. Pruebas sin llamadas al modelo

TestModel simula respuestas y llamadas a herramientas. No comprende la conversación como un LLM. Verificaremos datos, mensajes y conexiones; estas pruebas no demuestran que un modelo real recordará o responderá correctamente.

Bloqueamos las solicitudes reales durante este bloque y restauramos la configuración al terminar, incluso si falla una comprobación.

Celda 5

from pydantic_ai import models
from pydantic_ai.models.test import TestModel
from pydantic_ai.messages import SystemPromptPart, ToolReturnPart, UserPromptPart

# Recuperamos las partes de cada mensaje, sin depender del texto final simulado.
def partes(resultado):
    return [parte for mensaje in resultado.all_messages() for parte in mensaje.parts]

permitidas_antes = models.ALLOW_MODEL_REQUESTS
models.ALLOW_MODEL_REQUESTS = False
try:
    with agente.override(model=TestModel()):
        prueba_ana = agente.run_sync("Consulta mi presupuesto.", deps=ana)
        prueba_bruno = agente.run_sync("Consulta mi presupuesto.", deps=bruno)

    for resultado, esperado in [(prueba_ana, 20), (prueba_bruno, 50)]:
        devoluciones = [
            p.content for p in partes(resultado)
            if isinstance(p, ToolReturnPart) and p.tool_name == "resumen_presupuesto"
        ]
        assert devoluciones, "No se registró la devolución de la herramienta."
        assert devoluciones[-1]["bananas_enteras"] == esperado

    # El simulador devuelve texto fijo: no está recordando este objeto.
    with agente.override(model=TestModel(call_tools=[], custom_output_text="Simulación")):
        primero = agente.run_sync("Me interesa una bicicleta roja.", deps=ana)
        segundo = agente.run_sync(
            "¿De qué objeto hablamos?", deps=ana,
            message_history=primero.all_messages(),
        )
        sin_historial = agente.run_sync("¿De qué objeto hablamos?", deps=ana)
        ana_detallada = Cliente(
            cliente_id="ana", nombre="Ana", presupuesto_mxn=100,
            estilo="detallado",
        )
        actualizado = agente.run_sync(
            "Responde con mi estilo actual.", deps=ana_detallada,
            message_history=primero.all_messages(),
        )

    assert any(
        isinstance(p, UserPromptPart) and p.content == "Me interesa una bicicleta roja."
        for p in partes(segundo)
    )
    assert not any(
        isinstance(p, UserPromptPart) and p.content == "Me interesa una bicicleta roja."
        for p in partes(sin_historial)
    )
    assert any(
        isinstance(p, SystemPromptPart) and "Estilo de respuesta: detallado" in p.content
        for p in partes(actualizado)
    )
    try:
        Cliente(cliente_id="invalido", nombre="Prueba", presupuesto_mxn=-1)
    except ValidationError:
        pass
    else:
        raise AssertionError("Se aceptó un presupuesto negativo.")
    print("Pruebas superadas: perfiles, herramienta, historial y prompt dinámico.")
finally:
    models.ALLOW_MODEL_REQUESTS = permitidas_antes

Salida

Pruebas superadas: perfiles, herramienta, historial y prompt dinámico.

7. Conversación real con OpenRouter (opcional)

En Secrets de Colab crea OPENROUTER_API_KEY y habilita el acceso desde el notebook. Cambia la bandera a True para ejecutar esta sección y vuelve a ejecutar las dos celdas siguientes.

Se usa openrouter:openai/gpt-4o-mini, el identificador de la serie. Se comprobó su funcionamiento mediante una ejecución real de este notebook. Su disponibilidad y precio pueden cambiar; consulta el catálogo vigente de OpenRouter.

La clave no se imprime ni se guarda en el notebook. Las excepciones de la solicitud se propagan para facilitar el diagnóstico; no las convertimos en una respuesta aparentemente correcta.

Celda 6

USAR_OPENROUTER = False
MODELO = "openrouter:openai/gpt-4o-mini"

if USAR_OPENROUTER:
    import os
    from google.colab import userdata

    try:
        clave = userdata.get("OPENROUTER_API_KEY")
    except Exception:
        raise RuntimeError(
            "No se pudo leer el secreto. Revisa su nombre y el permiso en Colab."
        ) from None
    if not clave or not clave.strip():
        raise RuntimeError("El secreto OPENROUTER_API_KEY está vacío.")
    os.environ["OPENROUTER_API_KEY"] = clave.strip()
    del clave
else:
    print("Modo sin llamadas reales. Las pruebas anteriores no necesitan clave.")

Celda 7

if USAR_OPENROUTER:
    turno_1 = agente.run_sync(
        "Me interesa una bicicleta roja. Recuérdala durante esta conversación.",
        deps=ana, model=MODELO,
    )
    print("Primer turno:", turno_1.output)

    pregunta = "¿Qué objeto me interesa y a cuántas bananas equivale mi presupuesto?"
    turno_2 = agente.run_sync(
        pregunta, deps=ana, model=MODELO,
        message_history=turno_1.all_messages(),
    )
    print("Con historial:", turno_2.output)

    sin_memoria = agente.run_sync(pregunta, deps=ana, model=MODELO)
    print("Sin historial:", sin_memoria.output)

    otro_cliente = agente.run_sync(
        "Consulta mi presupuesto y su equivalencia en bananas.",
        deps=bruno, model=MODELO,
    )
    print("Otro cliente:", otro_cliente.output)

Salida

Primer turno: ¡Una bicicleta roja! Perfecta para hacer un desfile por la pista de carreras de plátanos. Pero como soy un bananero y no tengo memoria, no podré recordarla más allá de nuestra charla. ¿Te gustaría que consulte el presupuesto para ver cuántas bananas necesitarías para tu bicicleta roja? 🍌🚲
Con historial: Te interesa una bicicleta roja y tu presupuesto equivale a 20 bananas. ¡Con eso puedes hacer un buen recorrido por la jungla bananera! 🍌🚲 Si necesitas más información o quieres explorar otras opciones, aquí estoy para ayudarte. ¡No dudes en preguntar!
Sin historial: Tu presupuesto es de 100 MXN, lo que equivale a 20 bananas. ¡Así que ya sabes cuántas bananas puedes llevarte al teatro! Pero aún necesitamos clarificar qué objeto te interesa. 🍌🎭
Otro cliente: ¡Hola, Bruno! Tu presupuesto actual es de 250 MXN. Si lo convertimos a bananas, eso te da un total de **50 bananas**. ¡Eso es un montón de tentaciones! 🍌 ¿En qué gustaría gastar esas bananas hoy? ¡Estoy aquí para ayudarte a hacer la mejor compra de la selva!

Estas respuestas se obtuvieron con USAR_OPENROUTER = True. La bandera se dejó en False después de la prueba. El texto del modelo puede variar al repetirla.

Qué debes observar

Con historial, la bicicleta roja está disponible como referencia. Sin historial, la pregunta no identifica el objeto: esperamos una aclaración, aunque el modelo podría adivinar. Para Ana, la herramienta devuelve 20 bananas; para Bruno, 50. No estamos calculando el precio de la bicicleta.

Revisa la evidencia antes de concluir que el modelo utilizó una herramienta. La siguiente celda muestra llamadas y devoluciones del segundo turno. No basta con que el texto final contenga una cifra plausible.

Celda 8

if USAR_OPENROUTER:
    from pydantic_ai.messages import ToolCallPart

    for mensaje in turno_2.new_messages():
        for parte in mensaje.parts:
            if isinstance(parte, (ToolCallPart, ToolReturnPart)):
                print(parte)
    print("Mensajes acumulados:", len(turno_2.all_messages()))
    print("Mensajes nuevos:", len(turno_2.new_messages()))

Salida

ToolCallPart(tool_name='resumen_presupuesto', args='{}', tool_call_id='call_rsG21udddtYlaG515p5dwBOH')
ToolReturnPart(tool_name='resumen_presupuesto', content={'presupuesto_mxn': 100, 'precio_ficticio_banana_mxn': 5, 'bananas_enteras': 20}, tool_call_id='call_rsG21udddtYlaG515p5dwBOH', timestamp=datetime.datetime(2026, 11, 14, 2, 6, 31, 445343, tzinfo=datetime.timezone.utc))
Mensajes acumulados: 6
Mensajes nuevos: 4

8. Cómo continuar sin duplicar mensajes

En el turno siguiente pasa turno_2.all_messages(). Este método ya incluye el historial recibido. No hagas historial.extend(resultado.all_messages()) repetidamente: duplicarías los mensajes previos. Para un almacenamiento incremental, añadirías únicamente new_messages().

Aquí conservamos todo en variables. Eso es memoria de conversación dentro de esta sesión, no memoria permanente. Reiniciar Colab elimina las variables; descargar el notebook no convierte sus objetos Python en una base de datos.

En una aplicación real cada conversación necesita su propio historial y una asociación verificada con el usuario. Un diccionario por ID puede servir para practicar, pero no proporciona autenticación ni aislamiento por sí solo.

9. Limitaciones y errores comunes

SíntomaRevisión mínima
ModuleNotFoundErrorEjecuta instalación y revisa que haya terminado sin error
Conflictos de paquetesLee los mensajes; usa un runtime nuevo si afectan las dependencias necesarias
Falta la claveComprueba Secrets y el interruptor de acceso
Error de autenticación o saldoRevisa la clave y la cuenta de OpenRouter sin publicarlas
Modelo no disponibleConsulta el catálogo y elige un modelo compatible con herramientas
El agente olvida el objetoComprueba que pasaste el historial del turno correcto
Responde con datos de otra personaRevisa la asociación entre cliente e historial; no intentes resolverla solo con un prompt
Cambiaste código y aparecen comportamientos viejosReinicia la sesión y ejecuta las celdas en orden

El historial puede contener datos antiguos: actualizar deps no reescribe todas las respuestas previas ni sus resultados de herramientas. No uses respuestas históricas como fuente de un saldo actual.

Los mensajes largos pueden aumentar costo, latencia y uso de contexto. No recortes listas de mensajes arbitrariamente: podrías separar llamadas de sus devoluciones. Este ejercicio mantiene una conversación corta.

El modelo aún puede equivocarse o ignorar instrucciones. Las pruebas simuladas comprueban nuestra integración; la comparación real permite observar el comportamiento del LLM.

10. Mini-reto

Crea a Carla, con presupuesto ficticio de 175 MXN y estilo breve. Sin usar OpenRouter:

  1. Ejecuta el agente con TestModel y verifica en la devolución de la herramienta que obtiene 35 bananas.
  2. Abre una conversación simulada sobre un paraguas amarillo y pasa su historial a un segundo turno.
  3. Comprueba que ese mensaje está presente en el historial del segundo turno.

Bonus con OpenRouter: repite dos turnos con Carla y compara una respuesta con historial frente a otra sin historial. Esta parte consume tokens.

Mostrar solución del mini-reto

El texto fijo del simulador no demuestra comprensión. El assert verifica el mensaje transmitido y el resultado de la herramienta.

Celda 9

carla = Cliente(cliente_id="carla", nombre="Carla", presupuesto_mxn=175)
permitidas_antes = models.ALLOW_MODEL_REQUESTS
models.ALLOW_MODEL_REQUESTS = False
try:
    with agente.override(model=TestModel()):
        consulta_carla = agente.run_sync("Consulta mi presupuesto.", deps=carla)
    assert any(
        isinstance(p, ToolReturnPart)
        and p.tool_name == "resumen_presupuesto"
        and p.content["bananas_enteras"] == 35
        for p in partes(consulta_carla)
    )
    with agente.override(model=TestModel(call_tools=[], custom_output_text="Simulación")):
        inicio_carla = agente.run_sync("Me interesa un paraguas amarillo.", deps=carla)
        siguiente_carla = agente.run_sync(
            "¿De qué objeto hablamos?", deps=carla,
            message_history=inicio_carla.all_messages(),
        )
    assert any(
        isinstance(p, UserPromptPart) and p.content == "Me interesa un paraguas amarillo."
        for p in partes(siguiente_carla)
    )
    print("Mini-reto superado: 35 bananas y mensaje previo transmitido.")
finally:
    models.ALLOW_MODEL_REQUESTS = permitidas_antes

Salida

Mini-reto superado: 35 bananas y mensaje previo transmitido.

11. Lo que aprendiste y lo que sigue

Don Plátano ahora tiene tres fuentes distintas: el perfil que recibe, los datos que producen sus herramientas y los mensajes previos que decide enviar tu programa. Mantener esa diferencia hace más fácil detectar por qué una respuesta está mal.

En el artículo 5 integraremos lo aprendido en el reporte de cierre del Banano Exchange. La lectura de archivos y el alcance exacto del reporte se definirán allí; este notebook no los implementa.

Referencias oficiales

Documentación consultada el 13 de noviembre de 2026. Validación técnica completada en Google Colab: pruebas simuladas, mini-reto y ejecución real con OpenRouter. Las salidas registradas corresponden a esa ejecución y pueden variar al repetirla.

Notebook


Si quieres que la IA deje de ser un experimento en el chat y empiece a trabajar en tu operación diaria, automatizando lo repetitivo, conectando las herramientas que ya usas y atendiendo cuando tú no estás, en Clarvex AI lo hacemos a la medida de tu negocio.

Armamos la página que explica tu servicio y el chatbot de WhatsApp que responde a tus clientes cuando tú no estás, usando la API oficial de Meta. También conectamos lo que ya usas, como correo, hojas y agenda, para que dejes de copiar y pegar. 👉🏻 clarvexai.com