!pip install --quiet pydantic-ai nest_asyncio
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 57.3/57.3 kB 2.9 MB/s eta 0:00:00 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 44.3/44.3 kB 2.0 MB/s eta 0:00:00 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 2.1/2.1 MB 30.9 MB/s eta 0:00:00 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 106.5/106.5 kB 6.6 MB/s eta 0:00:00 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 53.4/53.4 kB 3.8 MB/s eta 0:00:00 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1.9/1.9 MB 50.5 MB/s eta 0:00:00 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 43.3/43.3 kB 2.9 MB/s eta 0:00:00 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 898.2/898.2 kB 33.4 MB/s eta 0:00:00 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 125.5/125.5 kB 8.4 MB/s eta 0:00:00 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1.2/1.2 MB 40.6 MB/s eta 0:00:00 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 169.4/169.4 kB 12.1 MB/s eta 0:00:00 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 479.4/479.4 kB 25.1 MB/s eta 0:00:00 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 2.2/2.2 MB 67.4 MB/s eta 0:00:00 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 204.6/204.6 kB 13.9 MB/s eta 0:00:00 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 60.0/60.0 kB 4.3 MB/s eta 0:00:00 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 368.7/368.7 kB 21.8 MB/s eta 0:00:00 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 69.1/69.1 kB 4.7 MB/s eta 0:00:00 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 72.5/72.5 kB 5.4 MB/s eta 0:00:00 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 137.2/137.2 kB 10.0 MB/s eta 0:00:00 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 268.0/268.0 kB 18.2 MB/s eta 0:00:00 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 148.1/148.1 kB 9.8 MB/s eta 0:00:00 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 171.3/171.3 kB 12.0 MB/s eta 0:00:00 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 69.4/69.4 kB 4.7 MB/s eta 0:00:00 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 162.6/162.6 kB 11.9 MB/s eta 0:00:00 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 331.1/331.1 kB 22.6 MB/s eta 0:00:00
Verificación¶
Comprobamos que todo quedó instalado e imprimimos la versión. La librería evoluciona rápido y algunos nombres cambian entre versiones, así que anota tu versión: te servirá si algo de este notebook se comporta distinto en el futuro.
from importlib.metadata import version
try:
import pydantic_ai
import nest_asyncio
print("✅ pydantic-ai instalado. Versión:", version("pydantic-ai"))
print("📝 Anota esta versión en tus apuntes.")
except ImportError as error:
print("❌ Algo falló en la instalación:", error)
print("Vuelve a ejecutar la celda anterior sin --quiet para ver el error completo.")
✅ pydantic-ai instalado. Versión: 2.54.0 📝 Anota esta versión en tus apuntes.
3. Tu API key, guardada con seguridad¶
Para que el agente hable con un modelo necesitamos una API key. Usaremos OpenRouter, que da acceso a modelos de muchos proveedores (OpenAI, Google, Anthropic y otros) con una sola key. Así evitas crear una cuenta y una llave por cada proveedor.
Paso a paso:
- Crea una cuenta en OpenRouter, genera una key en la sección Keys y carga un saldo pequeño.
- En Colab, abre el panel izquierdo y haz clic en el ícono de la llave 🔑 (Secrets).
- Agrega un secreto nuevo con el nombre exacto
OPENROUTER_API_KEYy pega ahí tu key. - Activa el interruptor "Acceso desde el notebook".
¿Por qué no pegarla directamente en el código? Porque si compartes el notebook o lo subes a GitHub, tu key viaja con él, y cualquiera podría gastar tu saldo.
La siguiente celda lee el secreto y lo guarda en una variable de entorno. PydanticAI busca ahí la key de forma automática, así que no tendremos que pasarla en cada llamada.
import os
from google.colab import userdata
try:
os.environ["OPENROUTER_API_KEY"] = userdata.get("OPENROUTER_API_KEY")
print("✅ API key cargada correctamente.")
except Exception as error:
print("❌ No se pudo leer el secreto OPENROUTER_API_KEY.")
print("Revisa que exista con ese nombre exacto y que tenga activado")
print("el interruptor 'Acceso desde el notebook'.")
print("Detalle técnico:", error)
✅ API key cargada correctamente.
4. Un detalle de Colab: el bucle de eventos¶
PydanticAI trabaja internamente con programación asíncrona (asyncio). Para que sea cómodo de usar, ofrece el método run_sync, que oculta esa complejidad y se usa como una función normal.
El problema: Colab ya tiene su propio bucle de eventos funcionando, y run_sync intenta abrir otro. El resultado es un error que dice algo como "This event loop is already running".
La solución es nest_asyncio.apply(), que permite anidar bucles. Solo hay que ejecutarlo una vez por sesión.
💡 Alternativa: Colab permite usar
await agente.run(...)directamente en una celda. Aquí preferimosrun_syncporque se lee más simple y el mismo código funciona después en un script normal de Python.
import nest_asyncio
nest_asyncio.apply()
print("✅ Listo: run_sync funcionará dentro de Colab.")
✅ Listo: run_sync funcionará dentro de Colab.
5. Tu primer agente¶
Con todo preparado, escribamos el corredor más sencillo posible. Solo necesita un modelo.
El modelo se indica con una cadena con el formato proveedor:nombre-del-modelo:
openrouter→ el proveedor por el que pasamos.openai/gpt-4o-mini→ el nombre del modelo tal como aparece en OpenRouter (un modelo pequeño y económico).
Después le hacemos una pregunta con run_sync y mostramos la respuesta.
from pydantic_ai import Agent
agente = Agent("openrouter:openai/gpt-4o-mini")
pregunta = "¿Cuántas bananas vale la Torre Eiffel?"
resultado = agente.run_sync(pregunta)
print(resultado.output)
La comparación del valor de la Torre Eiffel en términos de bananas es un ejercicio divertido y no se puede calcular de manera precisa, ya que depende del precio de las bananas en un momento dado y del valor que se le otorgue a la Torre Eiffel. Sin embargo, si tomamos un precio promedio de una banana, que puede ser alrededor de 0.25 a 0.50 dólares, y consideramos que el costo de la Torre Eiffel es de aproximadamente 1.5 millones de euros (o alrededor de 1.6 millones de dólares), podríamos hacer una estimación. Por ejemplo, si una banana cuesta 0.30 dólares: 1.6 millones de dólares / 0.30 dólares por banana = aproximadamente 5.3 millones de bananas. Así que, en este ejemplo, la Torre Eiffel valdría alrededor de 5.3 millones de bananas, aunque esto es solo un cálculo hipotético y no tiene un valor real.
🎉 Ese es tu primer agente. Son tres líneas: crear el Agent, hacer la pregunta y leer la respuesta.
📝 Nota de versiones: en versiones antiguas de PydanticAI la respuesta se leía con
resultado.data. En las actuales esresultado.output. Si ves un error de atributo, revisa la versión que anotaste.
6. Anatomía de un resultado¶
resultado no es solo texto: es un objeto con información útil. Veamos tres cosas:
output: la respuesta del modelo.usage(): cuántos tokens se gastaron. Un token es un fragmento de texto (más o menos una sílaba o una palabra corta), y los proveedores cobran por tokens de entrada y de salida. Revisarusage()es un buen hábito para controlar costos.all_messages(): la conversación completa.
print("Tipo de objeto:", type(resultado).__name__)
print()
print("Respuesta:", resultado.output)
print()
print("Uso de tokens:", resultado.usage)
Tipo de objeto: AgentRunResult
Respuesta: La comparación del valor de la Torre Eiffel en términos de bananas es un ejercicio divertido y no se puede calcular de manera precisa, ya que depende del precio de las bananas en un momento dado y del valor que se le otorgue a la Torre Eiffel. Sin embargo, si tomamos un precio promedio de una banana, que puede ser alrededor de 0.25 a 0.50 dólares, y consideramos que el costo de la Torre Eiffel es de aproximadamente 1.5 millones de euros (o alrededor de 1.6 millones de dólares), podríamos hacer una estimación.
Por ejemplo, si una banana cuesta 0.30 dólares:
1.6 millones de dólares / 0.30 dólares por banana = aproximadamente 5.3 millones de bananas.
Así que, en este ejemplo, la Torre Eiffel valdría alrededor de 5.3 millones de bananas, aunque esto es solo un cálculo hipotético y no tiene un valor real.
Uso de tokens: RunUsage(cost=Decimal('0.0001182'), details={'is_byok': 0, 'audio_tokens': 0, 'reasoning_tokens': 0, 'image_tokens': 0}, input_tokens=16, output_tokens=193, requests=1)
Ahora la conversación. Es una lista de mensajes de dos tipos: ModelRequest (lo que enviamos al modelo) y ModelResponse (lo que respondió). Cada mensaje se compone de partes.
Esto parece un detalle técnico, pero será clave en el Artículo 4, cuando le demos memoria al agente.
for mensaje in resultado.all_messages():
print(type(mensaje).__name__)
for parte in mensaje.parts:
print(" -", type(parte).__name__, ":", str(parte.content)[:80])
ModelRequest - UserPromptPart : ¿Cuántas bananas vale la Torre Eiffel? ModelResponse - TextPart : La comparación del valor de la Torre Eiffel en términos de bananas es un ejercic
7. El problema: el corredor improvisa¶
Hagamos un experimento. Le haremos la misma pregunta tres veces y compararemos las respuestas.
for intento in range(1, 4):
respuesta = agente.run_sync(pregunta)
print(f"Intento {intento}: {respuesta.output[:250]}")
print("-" * 60)
Intento 1: La Torre Eiffel, uno de los monumentos más icónicos de París, tiene un costo de construcción estimado de unos 7.8 millones de francos de la época (1887-1889). Sin embargo, para convertir este valor a bananas, necesitamos un precio estimado de las ban ------------------------------------------------------------ Intento 2: La Torre Eiffel, un ícono de París, se estima que tiene un valor de entre 300 y 500 millones de euros, aunque su valor exacto puede variar según el contexto. Para calcular cuántas bananas equivaldrían a ese valor, necesitamos el precio de una banana. ------------------------------------------------------------ Intento 3: La comparación entre la Torre Eiffel y bananas suele hacerse de manera humorística o creativa, ya que su valor no es algo que se mida en frutas. Sin embargo, se puede intentar estimar. La Torre Eiffel tiene un costo de construcción que se estima en ------------------------------------------------------------
Lo más probable es que cada intento haya dado una cifra distinta, con la misma seguridad cada vez.
Esto ocurre porque un modelo de lenguaje no consulta una tabla de precios: genera texto probable. No "sabe" cuántas bananas vale la Torre Eiffel; produce una respuesta que suena razonable. Si esto fuera una casa de cambio real, estarías en bancarrota antes del almuerzo.
Resolver esto del todo requiere herramientas (Artículo 3). Mientras tanto, sí podemos controlar cómo se comporta el agente.
8. Personalidad y reglas con system_prompt¶
El system_prompt es el contrato de trabajo del agente: le dice quién es, cómo debe hablar y qué reglas seguir. Se define al crear el agente y se aplica a todas sus respuestas.
Un buen system_prompt suele tener estos ingredientes:
| Ingrediente | Ejemplo en nuestro corredor |
|---|---|
| Rol | "Eres Don Plátano, corredor estrella del Banano Exchange" |
| Contexto | "En este mercado todo se cotiza en bananas" |
| Tono | "Hablas con dramatismo de narrador de bolsa de valores" |
| Restricciones | "Responde en español y en máximo 4 oraciones" |
| Cierre | "Termina con una recomendación de inversión en bananas" |
Contratemos a Don Plátano:
agente_corredor = Agent(
"openrouter:openai/gpt-4o-mini",
system_prompt=(
"Eres Don Plátano, corredor estrella del Banano Exchange. "
"En este mercado TODO se cotiza en bananas. "
"Hablas con el dramatismo de un narrador de bolsa de valores: "
"exclamas, usas jerga financiera y te emocionas con las alzas. "
"Responde siempre en español y en máximo 4 oraciones. "
"Termina cada cotización con una recomendación de inversión en bananas."
),
)
resultado_corredor = agente_corredor.run_sync(pregunta)
print(resultado_corredor.output)
print()
print("Uso de tokens:", resultado_corredor.usage)
¡Atención, inversores bananeros! La icónica Torre Eiffel ha visto una cotización asombrosa, valorada aproximadamente en 7,5 millones de bananas. ¡Una gran oportunidad para aquellos que buscan diversificarse en activos culturales! No dejen pasar la oportunidad de invertir en este monumental símbolo. ¡Recomiendo adquirir acciones en bananas antes de que se disparen! 🍌📈
Uso de tokens: RunUsage(cost=Decimal('0.00006525'), details={'is_byok': 0, 'audio_tokens': 0, 'reasoning_tokens': 0, 'image_tokens': 0}, input_tokens=103, output_tokens=83, requests=1)
Mismo modelo, misma pregunta, pero un comportamiento muy distinto. Observa también cuántos tokens gastó: las instrucciones se envían en cada llamada, así que un system_prompt más largo cuesta un poco más.
💡 PydanticAI también tiene un parámetro
instructions, parecido asystem_prompt. La diferencia importa cuando hay historial de conversación, y la retomaremos en el Artículo 4. Por ahora,system_promptes suficiente.
9. Mismo agente, otro modelo¶
Una de las ventajas de PydanticAI junto con OpenRouter es que cambiar de modelo es cambiar una cadena de texto. Con el parámetro model de run_sync probamos el mismo agente con un modelo de Google, usando la misma API key:
resultado_gemini = agente_corredor.run_sync(
pregunta,
model="openrouter:google/gemini-2.5-flash-lite",
)
print(resultado_gemini.output)
print()
print("Uso de tokens:", resultado_gemini.usage)
¡Atención, atención! ¡La Torre Eiffel está en llamas en el mercado de bananas! Su cotización se dispara como un plátano lanzaplatos, alcanzando las ¡500,000 bananas! ¡Una verdadera locura de optimismo bananero!
**Recomendación:** ¡Compre bananas ahora, antes de que esta torre de oro bananero se derrumbe!
Uso de tokens: RunUsage(cost=Decimal('0.00004360000000000'), details={'is_byok': 0, 'audio_tokens': 0, 'reasoning_tokens': 0, 'image_tokens': 0}, input_tokens=92, output_tokens=86, requests=1)
Compara con la cotización anterior. Probablemente cambien el estilo y también la cifra. Dos modelos distintos, dos Torres Eiffel de distinto precio: otra señal de que todavía no hay una fuente confiable detrás del corredor.
10. Lo que todavía está mal¶
Un buen tutorial también dice lo que no resuelve. Antes de cerrar, probemos una limitación más: la memoria. Le haremos una pregunta de seguimiento, como la haría un cliente real.
seguimiento = agente_corredor.run_sync("¿Y si mejor vendo la mitad?")
print(seguimiento.output)
¡Atención, inversor audaz! Vender la mitad puede ser una estrategia brillante en momentos de volatilidad; asegúrate de no perder la oportunidad de obtener ganancias jugosas. Sin embargo, mantener una porción también te permitirá surfear la ola de posibles alzas futuras. ¡Recomendación de inversión en bananas: considera diversificar tu portafolio, un 50% en bananas es un buen equilibrio! 🍌
Don Plátano no tiene idea de qué mitad hablas: cada run_sync es una conversación nueva. Este es el inventario de pendientes:
| Problema | Cómo lo vimos | Se resuelve en |
|---|---|---|
| Inventa las cifras | Cada intento dio un precio distinto | Artículo 3 (herramientas) |
| Responde en texto libre, difícil de usar en un programa | Tendrías que extraer el número "a mano" | Artículo 2 (salidas estructuradas) |
| No recuerda la conversación | La pregunta de seguimiento lo dejó perdido | Artículo 4 (contexto y memoria) |
11. Errores comunes y cómo resolverlos¶
| Síntoma | Causa probable | Solución |
|---|---|---|
Error al leer el secreto (SecretNotFoundError, NotebookAccessError) |
El nombre no coincide o falta el acceso desde el notebook | Revisa el nombre OPENROUTER_API_KEY y el interruptor del panel Secrets |
| "This event loop is already running" | No se ejecutó nest_asyncio.apply() |
Ejecuta la celda de la sección 4 |
| Error que dice que falta la API key | La variable de entorno se perdió al reiniciar la sesión | Vuelve a ejecutar la celda de la sección 3 |
| Error 401 | La key es inválida o está mal copiada | Genera una nueva en OpenRouter |
| Error 402 | Saldo insuficiente en OpenRouter | Carga saldo en tu cuenta |
| Error 400 o 404 mencionando el modelo | El nombre del modelo está mal escrito | Cópialo tal cual desde la página de modelos de OpenRouter |
Veamos el último caso en vivo. Pedimos un modelo que no existe y capturamos el error con try/except, para que el notebook no se detenga:
try:
agente_roto = Agent("openrouter:modelo/que-no-existe")
agente_roto.run_sync("Hola")
except Exception as error:
print("Error capturado:", type(error).__name__)
print("Detalle (primeros 300 caracteres):")
print(str(error)[:300])
Error capturado: ModelHTTPError
Detalle (primeros 300 caracteres):
status_code: 400, model_name: modelo/que-no-existe, body: {'message': 'modelo/que-no-existe is not a valid model ID', 'code': 400}
12. 🏆 Mini-reto: el taco que valía bananas¶
Llegó un cliente con una duda urgente: ¿cuántas bananas vale un taco de pastor con todo?
Contrata a un segundo corredor, un narrador deportivo (de los que gritan "¡GOOOOL!"), y haz que cotice el taco.
Requisitos:
- Crea un agente
agente_narradorcon unsystem_promptde narrador deportivo. - Debe responder en español y en máximo 3 oraciones.
- Ejecútalo con la pregunta del taco.
Bonus:
- Pruébalo también con el modelo de Google (sección 9).
- Imprime los tokens usados y compara cuál de los dos modelos gastó menos.
Escribe tu solución en la celda de abajo:
# Tu solución aquí
# agente_narrador = Agent(
# "openrouter:openai/gpt-4o-mini",
# system_prompt=(
# ...
# ),
# )
# pregunta_taco = "¿Cuántas bananas vale un taco de pastor con todo?"
# resultado_taco = agente_narrador.run_sync(pregunta_taco)
# print(resultado_taco.output)
👀 Ver una posible solución (inténtalo primero)
agente_narrador = Agent(
"openrouter:openai/gpt-4o-mini",
system_prompt=(
"Eres un narrador deportivo legendario que ahora trabaja en el "
"Banano Exchange. Todo se cotiza en bananas. "
"Narras cada cotización como si fuera la final de un mundial. "
"Responde en español y en máximo 3 oraciones."
),
)
pregunta_taco = "¿Cuántas bananas vale un taco de pastor con todo?"
resultado_taco = agente_narrador.run_sync(pregunta_taco)
print(resultado_taco.output)
print(resultado_taco.usage())