Bienvenido al Banano Exchange, la única casa de cambio del mundo donde todo, absolutamente todo, se cotiza en bananas: la Torre Eiffel, un taco de pastor, tu auto, tu deuda con la tarjeta de crédito.
Tú eres el dueño del negocio y hoy contratas a tu primer corredor de bolsa. Es un agente de inteligencia artificial. Empieza siendo muy entusiasta y poco confiable, y a lo largo de la serie lo convertiremos en un profesional.
🎯 Objetivos de este artículo
- Entender qué es PydanticAI y qué problema resuelve frente a llamar a la API “a mano”.
- Instalar la librería y guardar tu API key de forma segura con los Secrets de Colab.
- Crear y ejecutar tu primer
Agent. - Inspeccionar la respuesta: texto, tokens usados y mensajes.
- Darle personalidad con
system_prompty descubrir por qué todavía no podemos confiar en él.
📋 Antes de empezar
- Una cuenta de Google (para usar Colab) y conocimientos básicos de Python.
- Una cuenta en OpenRouter con unos centavos de crédito. Usaremos modelos económicos, así que ejecutar todo el notebook cuesta muy poco, pero no es gratis.
- Ejecuta las celdas en orden, de arriba hacia abajo.
⚠️ Límite de Colab: la sesión gratuita se reinicia si la dejas inactiva un rato. Al reiniciarse se pierden las librerías instaladas y las variables, así que tendrás que volver a ejecutar las celdas de instalación y de la API key.
1. ¿Qué es PydanticAI?
PydanticAI es una librería de Python, creada por el equipo detrás de Pydantic, para construir agentes con modelos de lenguaje (LLM). Su idea central es tratar al LLM como una pieza más de tu programa, con reglas, formatos y validaciones, y no como una caja mágica que devuelve texto.
Una analogía bananera:
- Llamar a la API a mano es llamar por teléfono a un corredor y anotar en una servilleta lo que diga.
- Usar un agente es contratarlo con un contrato (instrucciones), un formulario oficial (formato de salida), herramientas de trabajo (calculadora, consultas) y un expediente de cada cliente (contexto).
| Necesidad | API “a mano” | PydanticAI | ¿Dónde lo veremos? |
|---|---|---|---|
| Cambiar de modelo o proveedor | Reescribir código y librerías | Cambiar una cadena de texto | Este artículo |
| Darle personalidad y reglas | Armar mensajes manualmente | Parámetro system_prompt | Este artículo |
| Exigir un formato de respuesta | Pedir “responde en JSON” y cruzar los dedos | Declarar un modelo Pydantic | Artículo 2 |
| Que ejecute funciones reales | Interpretar llamadas a funciones a mano | Decorador @agent.tool | Artículo 3 |
| Pasarle contexto y memoria | Variables globales | Dependencias tipadas | Artículo 4 |
Esta tabla es el mapa de la serie. Hoy solo recorremos las dos primeras filas.
Un agente, en su versión más simple, es: instrucciones + un modelo. Eso es exactamente lo que construiremos.
2. Instalación
En Colab, un signo ! al inicio de una celda significa: “ejecuta esto en la terminal, no como código Python”. Lo usamos para instalar con pip.
Instalaremos dos paquetes:
pydantic-ai: la librería principal.nest_asyncio: un parche pequeño que necesitaremos en la sección 4 (te explico por qué más adelante).
⚠️ Usamos
--quietpara que la salida no sea kilométrica, pero eso también oculta los errores. Si algo falla, la celda de verificación de abajo te lo dirá; si necesitas ver el detalle, vuelve a ejecutar esta celda sin--quiet.Si Colab muestra un aviso de conflicto de dependencias o pide reiniciar la sesión, suele ser inofensivo. Si te lo pide, reinicia y vuelve a ejecutar desde esta celda.
✅ Lo que aprendiste
- PydanticAI trata al LLM como una pieza de tu programa, no como una caja mágica.
- Un
Agenten su forma más simple es instrucciones + modelo. - Guardas tu API key en Secrets, nunca dentro del código.
- Colab necesita
nest_asyncio.apply()para usarrun_sync. resultado.output,usage()yall_messages()te dicen qué respondió el modelo, cuánto costó y cómo fue la conversación.- Con
system_promptdefines rol, tono y reglas, y cambiar de modelo es cambiar una cadena de texto. - Todavía improvisa cifras, responde en texto libre y no tiene memoria.
🔜 En el próximo artículo
Don Plátano ya tiene personalidad, pero entrega sus cotizaciones como texto libre. Si mañana quisieras guardar cien cotizaciones en una hoja de cálculo, tendrías que rescatar el número de entre sus exclamaciones a mano. 😅
En el Artículo 2 lo obligaremos a entregar un formulario oficial: un objeto Cotizacion con campos validados con Pydantic, listo para convertirse en una tabla.
Serie PydanticAI desde cero · Artículo 1 de 5. ¿Dudas o comentarios? Déjalos en el blog.

