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
| Pieza | Para qué sirve aquí | Qué no hace por sí sola |
|---|---|---|
deps_type=Cliente | Declara el tipo de dependencias del agente | No crea un cliente ni valida cualquier objeto que se le pase |
deps=ana | Entrega el objeto de esta ejecución | No lo envía completo automáticamente al modelo |
RunContext[Cliente] | Permite acceder a esos datos mediante ctx.deps | No recupera conversaciones anteriores |
message_history | Aporta mensajes previos al nuevo turno | No 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íntoma | Revisión mínima |
|---|---|
ModuleNotFoundError | Ejecuta instalación y revisa que haya terminado sin error |
| Conflictos de paquetes | Lee los mensajes; usa un runtime nuevo si afectan las dependencias necesarias |
| Falta la clave | Comprueba Secrets y el interruptor de acceso |
| Error de autenticación o saldo | Revisa la clave y la cuenta de OpenRouter sin publicarlas |
| Modelo no disponible | Consulta el catálogo y elige un modelo compatible con herramientas |
| El agente olvida el objeto | Comprueba que pasaste el historial del turno correcto |
| Responde con datos de otra persona | Revisa la asociación entre cliente e historial; no intentes resolverla solo con un prompt |
| Cambiaste código y aparecen comportamientos viejos | Reinicia 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:
- Ejecuta el agente con
TestModely verifica en la devolución de la herramienta que obtiene 35 bananas. - Abre una conversación simulada sobre un paraguas amarillo y pasa su historial a un segundo turno.
- 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
- Dependencias y RunContext.
- API del agente: system_prompt y dynamic.
- Mensajes e historial.
- Pruebas con TestModel.
- Proveedor OpenRouter.
- Distribución pydantic-ai-slim y versiones.
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.

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

