1. Instalar y comprobar la versión¶
Puedes ejecutar este notebook sin los anteriores.
!pip install --quiet pydantic-ai nest_asyncio httpx
ERROR: pip's dependency resolver does not currently take into account all the packages that are installed. This behaviour is the source of the following dependency conflicts. google-colab 1.0.0 requires google-auth==2.49.0, but you have google-auth 2.62.1 which is incompatible. google-adk 2.7.1 requires opentelemetry-api<=1.42.1,>=1.39, but you have opentelemetry-api 1.45.2 which is incompatible. google-adk 2.7.1 requires opentelemetry-sdk<=1.42.1,>=1.39, but you have opentelemetry-sdk 1.45.2 which is incompatible.
💡 Nota sobre el mensaje en rojo de arriba:
Si ves un aviso de pip que habla sobre "dependency conflicts" con paquetes como google-auth u opentelemetry, ¡no te preocupes en absoluto!
Google Colab viene con muchas librerías preinstaladas para interactuar con -Google Cloud. Al instalar pydantic-ai, algunas versiones se actualizan y Colab nos avisa de esa pequeña discrepancia. Para lo que vamos a construir aquí (nuestro agente Don Plátano y sus cotizaciones con Pydantic), todo funcionará de forma impecable. Puedes ignorar el aviso rojo y continuar con total tranquilidad.
from importlib.metadata import version
print("pydantic-ai:", version("pydantic-ai"))
pydantic-ai: 2.65.0
2. Leer OpenRouter desde Secrets¶
Crea OPENROUTER_API_KEY en el panel de Secrets y habilita el acceso desde el notebook.
import os
import nest_asyncio
from google.colab import userdata
clave = userdata.get("OPENROUTER_API_KEY")
if not clave:
raise RuntimeError("Falta OPENROUTER_API_KEY en Secrets")
os.environ["OPENROUTER_API_KEY"] = clave
nest_asyncio.apply()
print("✅ Configuración lista")
✅ Configuración lista
3. Crear el agente y la herramienta de precio¶
@agent.tool_plain registra una función normal. El precio es una convención inventada.
from pydantic_ai import Agent, RunContext
agente = Agent(
"openrouter:openai/gpt-4o-mini",
system_prompt=(
"Eres Don Plátano, corredor del Banano Exchange. "
"Responde en español, sin inventar precios ni tasas. "
"Usa las herramientas para consultar el precio de banana, USD/MXN y calcular. "
"Indica siempre que el precio de banana es ficticio y cita la fecha de la tasa."
),
)
@agente.tool_plain
def precio_banana_mxn() -> float:
"""Devuelve el precio fijo y ficticio de una banana en MXN."""
return 5.0
4. Tool de tipo de cambio¶
Frankfurter v2 publica tasas de referencia con fecha, no cotizaciones negociables en tiempo real.
import httpx
@agente.tool_plain
def tipo_cambio_usd_mxn() -> dict:
"""Obtiene tasa de referencia reciente de USD a MXN y fecha de publicación."""
try:
r = httpx.get("https://api.frankfurter.dev/v2/rate/USD/MXN", timeout=10.0)
r.raise_for_status()
d = r.json()
tasa = float(d["rate"])
if tasa <= 0:
raise ValueError("Tasa no positiva")
return {"fecha": d["date"], "mxn_por_usd": tasa, "fuente": "Frankfurter v2"}
except (httpx.HTTPError, KeyError, TypeError, ValueError) as error:
raise RuntimeError("Fallo de USD/MXN: no inventar la tasa") from error
5. Tool con contexto y calculadora¶
@agent.tool añade RunContext como primer parámetro; el artículo 4 lo aprovechará para dependencias de un cliente.
@agente.tool
def convertir_mxn_a_bananas(ctx: RunContext[None], monto_mxn: float, precio_mxn: float) -> float:
"""Convierte MXN a bananas usando el precio obtenido de la herramienta oficial."""
if monto_mxn < 0 or precio_mxn <= 0:
raise ValueError("Monto y precio deben ser válidos")
return round(monto_mxn / precio_mxn, 4)
6. Consultar 100 USD¶
El modelo debe decidir las llamadas. No des por hecho que lo hará correctamente.
pregunta = (
"¿Cuántas bananas equivalen a 100 USD? "
"Utiliza las tres herramientas: precio_banana_mxn, tipo_cambio_usd_mxn "
"y convertir_mxn_a_bananas. Muestra tasa, fecha y operación."
)
resultado = agente.run_sync(pregunta)
print(resultado.output)
print("Tokens:", resultado.usage())
Para convertir 100 USD a bananas, primero utilizamos el tipo de cambio y el precio de la banana.
1. **Tipo de cambio**: 1 USD = 18.6533 MXN (fecha: 03 de noviembre de 2026).
2. **Monto en MXN**: 100 USD * 18.6533 MXN/USD = 1865.33 MXN.
3. **Precio de la banana**: 5.0 MXN por banana (precio ficticio).
Ahora, convertimos 1865.33 MXN a bananas:
- \( \frac{1865.33 \text{ MXN}}{5.0 \text{ MXN/banana}} \approx 373.07 \text{ bananas} \).
Por lo tanto, 100 USD equivalen a aproximadamente **373.07 bananas**.
Tokens: RunUsage(cost=Decimal('0.00029370'), details={'is_byok': 0, 'audio_tokens': 0, 'reasoning_tokens': 0, 'image_tokens': 0}, input_tokens=926, output_tokens=258, requests=3, tool_calls=3)
/tmp/ipykernel_3852/1452424460.py:8: PydanticAIDeprecationWarning: `usage` is a property, not a method: use `.usage` instead of `.usage()`.
print("Tokens:", resultado.usage())
7. Auditar las llamadas¶
Inspecciona ToolCallPart y ToolReturnPart. La aserción te avisa si el agente omitió alguna herramienta; no prueba que la respuesta final sea matemáticamente correcta.
from pydantic_ai.messages import ToolCallPart, ToolReturnPart
llamadas = []
for mensaje in resultado.all_messages():
for parte in mensaje.parts:
if isinstance(parte, ToolCallPart):
llamadas.append(parte.tool_name)
print("LLAMADA:", parte.tool_name, "args:", parte.args)
elif isinstance(parte, ToolReturnPart):
print("RETORNO:", parte.tool_name, "resultado:", str(parte.content)[:250])
esperadas = {"precio_banana_mxn", "tipo_cambio_usd_mxn", "convertir_mxn_a_bananas"}
faltantes = esperadas - set(llamadas)
if faltantes:
print("⚠️ El modelo omitió herramientas:", sorted(faltantes))
else:
print("✅ El agente llamó las tres herramientas")
LLAMADA: precio_banana_mxn args: {}
LLAMADA: tipo_cambio_usd_mxn args: {}
RETORNO: precio_banana_mxn resultado: 5.0
RETORNO: tipo_cambio_usd_mxn resultado: {'fecha': '2026-11-03', 'mxn_por_usd': 18.6533, 'fuente': 'Frankfurter v2'}
LLAMADA: convertir_mxn_a_bananas args: {"monto_mxn":1865.33,"precio_mxn":5}
RETORNO: convertir_mxn_a_bananas resultado: 373.066
✅ El agente llamó las tres herramientas
8. Comparar con el agente sin herramientas¶
Esta respuesta puede inventar un precio: no la uses como referencia.
agente_sin_tools = Agent(
"openrouter:openai/gpt-4o-mini",
system_prompt="Eres Don Plátano. Responde en español y cotiza todo en bananas.",
)
comparacion = agente_sin_tools.run_sync("¿Cuántas bananas equivalen a 100 USD?")
print("Sin herramientas:", comparacion.output)
print("Con herramientas:", resultado.output)
Sin herramientas: Para calcular cuántas bananas equivalen a 100 USD, primero necesitamos saber el precio de una banana. Supongamos que el precio de una banana es de 0.25 USD.
Por lo tanto, para saber cuántas bananas hay en 100 USD, hacemos el siguiente cálculo:
100 USD ÷ 0.25 USD/banana = 400 bananas.
Así que, 100 USD equivalen a 400 bananas. 🍌
Con herramientas: Para convertir 100 USD a bananas, primero utilizamos el tipo de cambio y el precio de la banana.
1. **Tipo de cambio**: 1 USD = 18.6533 MXN (fecha: 03 de noviembre de 2026).
2. **Monto en MXN**: 100 USD * 18.6533 MXN/USD = 1865.33 MXN.
3. **Precio de la banana**: 5.0 MXN por banana (precio ficticio).
Ahora, convertimos 1865.33 MXN a bananas:
- \( \frac{1865.33 \text{ MXN}}{5.0 \text{ MXN/banana}} \approx 373.07 \text{ bananas} \).
Por lo tanto, 100 USD equivalen a aproximadamente **373.07 bananas**.
9. Mini-reto: presupuesto personal¶
Cotiza 250 USD y comprueba que el modelo llame las herramientas. Bonus: prueba con 1,000 MXN y razona por qué no debería necesitar consultar USD/MXN.
# Tu turno:
# reto = agente.run_sync("Tengo un presupuesto de 250 USD. ¿Cuántas bananas equivalen?")
# print(reto.output)
#@title Solución del Mini-reto 🍌 { display-mode: "both" }
print("=== RETO Parte 1: Presupuesto de 250 USD ===")
reto_usd = agente.run_sync(
"Tengo un presupuesto de 250 USD. ¿Cuántas bananas equivalen? "
"Muestra detalladamente qué herramientas utilizas."
)
print(reto_usd.output)
print("\n--- Verificando herramientas usadas en Parte 1 ---")
for mensaje in reto_usd.all_messages():
for parte in mensaje.parts:
if hasattr(parte, 'tool_name'):
print(f"Herramienta: {parte.tool_name}")
print("\n" + "="*40 + "\n")
print("=== RETO Parte 2: Presupuesto de 1,000 MXN ===")
# Al estar en MXN, el agente inteligente no debería necesitar llamar a `tipo_cambio_usd_mxn`.
reto_mxn = agente.run_sync(
"Tengo un presupuesto de 1000 MXN. ¿Cuántas bananas equivalen? "
"No es necesario que conviertas de USD a MXN ya que el dinero ya está en MXN."
)
print(reto_mxn.output)
print("\n--- Verificando herramientas usadas en Parte 2 ---")
for mensaje in reto_mxn.all_messages():
for parte in mensaje.parts:
if hasattr(parte, 'tool_name'):
print(f"Herramienta: {parte.tool_name}")