Pydantic AI: guía para principiantes con ejemplos prácticos

Al crear aplicaciones con IA es habitual toparse con salidas desestructuradas, errores de tipos y problemas de fiabilidad en producción. Los enfoques tradicionales para integrar LLMs en aplicaciones Python carecen de la estructura y validación que exigen los sistemas en producción. Pydantic AI resuelve esto al combinar la validación de datos de Pydantic con un framework de agentes para interactuar con LLMs.

En este tutorial aprenderás a crear agentes de IA estructurados que produzcan salidas validadas y mantengan la seguridad de tipos. Veremos cómo configurar agentes con system prompts, crear herramientas (funciones) que los LLMs puedan invocar durante la conversación e implementar validación de salidas estructuradas. También descubrirás cómo gestionar dependencias entre componentes del agente y transmitir respuestas en tiempo real. Al final, habrás practicado la construcción de aplicaciones de IA capaces de manejar flujos de trabajo complejos.

Si buscas un curso práctico para construir sistemas de IA con agentes, te recomiendo el curso Building Multi-Agent Systems with LangGraph. 

¿Qué es Pydantic AI?

Pydantic AI es un framework de agentes en Python que aporta estructura y seguridad de tipos a las aplicaciones con LLM. A diferencia de las integraciones básicas que devuelven texto en bruto, Pydantic AI trata las interacciones con la IA como conversaciones estructuradas con entradas y salidas validadas, lo que facilita crear aplicaciones fiables.

Funciones y ventajas clave:

• Validación de salidas estructuradas — Las respuestas de la IA se ajustan automáticamente a modelos de Pydantic, evitando errores de parseo y garantizando la consistencia de datos
• Herramientas de función — Los LLMs pueden llamar a tus funciones de Python durante la conversación, con acceso a datos reales y cálculos
• Seguridad de tipos — Tipado completo para reducir errores en tiempo de ejecución y mejorar la asistencia del IDE al crear flujos de trabajo complejos
• System prompts — Define instrucciones claras para tus agentes de IA que se mantienen coherentes en todas las interacciones
• Inyección de dependencias — Comparte contexto, conexiones a bases de datos y preferencias de usuario entre todos los componentes del agente de forma ordenada
• Varios modos de ejecución — Ejecuta agentes de forma síncrona, asíncrona o transmite respuestas en tiempo real según tus necesidades
• Reutilización de agentes — Crea agentes una vez y reutilízalos por toda tu aplicación, de forma similar a los routers de FastAPI

Este enfoque convierte la IA de una generación de texto impredecible en interacciones tipadas y fiables que encajan de forma natural en tus aplicaciones Python. En lugar de pelearte con prompt engineering y el parseo de salidas, puedes centrarte en construir la funcionalidad que tus usuarios necesitan.

Requisitos previos

Antes de empezar con este tutorial, necesitarás lo siguiente:

Conocimientos necesarios:

• Fundamentos de Python: familiarízate con clases y funciones
• Conceptos básicos de programación asíncrona en Python
• Conceptos básicos de Pydantic: comprende modelos, validación de campos y anotaciones de tipo
• Familiaridad con LLMs:  conocimientos básicos de cómo funcionan los modelos de lenguaje y qué son los prompts

Útiles pero no imprescindibles:

• Conceptos de agentes:  algo de exposición a agentes de IA y tool calling, aunque lo veremos aquí

Requisitos de configuración:

• Python 3.9 o superior
• Claves de API de OpenAI y Anthropic
• Conocimientos básicos de terminal/línea de comandos para instalar paquetes

Si eres nuevo en Pydantic, su documentación oficial cubre bien los fundamentos. Para nociones básicas de LLM, cualquier guía introductoria a ChatGPT o modelos similares te dará el contexto suficiente para seguir el tutorial.

Primeros pasos con Pydantic AI

A lo largo del tutorial construiremos un agente de análisis de datos que nos ayude a entender el rendimiento de ventas por regiones y productos. Empezará sencillo y será más sofisticado a medida que añadamos funciones como herramientas personalizadas, salidas estructuradas y capacidades de streaming.

Instalación y configuración

Antes de ponernos con el código, instalemos Pydantic AI y preparemos el entorno:

pip install pydantic-ai

También necesitarás una clave de API de OpenAI y de Anthropic. Defínelas como variables de entorno:

export OPENAI_API_KEY="your-api-key-here"export ANTHROPIC_API_KEY="your-api-key-here"

> Usaremos tanto modelos de OpenAI como de Anthropic, ya que algunas funciones de Pydantic AI están soportadas en uno pero no en el otro.

Para los ejemplos de análisis de datos, también usaremos pandas para la manipulación de datos:

pip install pandas

Crea tu primer agente

Empecemos con el agente más simple — uno que responda preguntas básicas sobre datos de ventas. En Pydantic AI, un agente es tu interfaz principal para interactuar con LLMs (ejecuta el siguiente código en un script de Python):

from pydantic_ai import Agent# Create a basic sales analysis agentsales_agent = Agent(   'openai:gpt-4o',   system_prompt=(       "You are a data analyst specializing in sales performance. "       "Provide clear, actionable insights based on the data provided."   ))# Run the agent with a simple questionresult = sales_agent.run_sync("What are the key metrics I should track for sales performance? Answer in two sentences.")print(result.output)

Salida:

Key metrics to track for sales performance include conversion rate, which measures the percentage of leads that result in sales, and average deal size, indicating the average revenue earned per transaction. Additionally, monitoring customer acquisition cost (CAC) and customer lifetime value (CLV) helps evaluate the efficiency and profitability of sales efforts.

Esto crea un agente que entiende su rol como analista de ventas y puede dar recomendaciones relevantes. El system_prompt da al LLM el contexto sobre el tipo de respuestas que esperas, mientras que run_sync() ejecuta el agente y devuelve el resultado.

Aquí, la función run_sync() solo funciona en scripts de Python. Para ejecutar agentes en un Jupyter Notebook, puedes usar la siguiente sintaxis:

result = await agent.run("...")print(result.output)

Cambiar el LLM y su configuración

Pydantic AI soporta múltiples proveedores de LLM y te permite personalizar el comportamiento del modelo. Así puedes experimentar con distintas opciones:

# Creating agents with different modelsclaude_agent = Agent('anthropic:claude-3-5-sonnet-20241022', system_prompt="You are a sales analyst.")gpt_mini_agent = Agent('openai:gpt-4o-mini', system_prompt="You are a sales analyst.")

Cada modelo aporta capacidades diferentes a tu flujo de análisis de datos. Los modelos Claude destacan en razonamiento detallado y análisis complejo, ideales cuando necesitas conclusiones exhaustivas de tus datos de ventas. GPT-4o-mini ofrece respuestas más rápidas y menor coste, perfecto para consultas rápidas o cuando procesas grandes volúmenes de preguntas.

Más allá de elegir modelos, puedes afinar su comportamiento con ajustes específicos:

# Add model-specific settingsconfigured_agent = Agent(   'openai:gpt-4o',   system_prompt="You are a sales analyst.",   model_settings={       'temperature': 0.3,  # Respuestas más enfocadas, menos creativas       'max_tokens': 500,   # Limitar la longitud de la respuesta   })

Ajustes del modelo que puedes personalizar:

• temperature — Controla la creatividad (0.0 = enfocado, 1.0 = creativo)
• max_tokens — Limita la longitud de la respuesta
• top_p — Alternativa a temperature para controlar la aleatoriedad

Para tareas de análisis de datos, valores bajos de temperatura (0.1–0.3) suelen funcionar mejor porque buscas respuestas consistentes y factuales más que interpretaciones creativas. Establecer max_tokens ayuda a controlar la longitud de la respuesta, útil cuando necesitas resúmenes concisos o quieres optimizar costes de API.

Uso de herramientas en los agentes

Hasta ahora, nuestro agente de análisis de ventas solo puede trabajar con la información que incluimos en los prompts. Pero el análisis real suele requerir acceder a información externa, ejecutar cálculos o conectarse a sistemas de negocio. Aquí entran las herramientas: dan a tu agente la capacidad de actuar y recopilar información durante la conversación.

Herramientas integradas

Las herramientas integradas son funciones listas para usar que ofrecen los proveedores de LLM. Pydantic AI soporta búsqueda web y ejecución de código que se ejecutan directamente en la infraestructura del proveedor.

Empecemos con la búsqueda web, perfecta para obtener información actual del mercado:

from pydantic_ai import Agent, WebSearchTool# Create an agent with web search abilitiesmarket_research_agent = Agent(   'anthropic:claude-3-5-sonnet-20241022',   builtin_tools=[WebSearchTool()],   system_prompt=(       "You are a sales analyst. Use web search to find current information. "       "Keep responses to 3-4 sentences maximum."   ))# Get current market informationresult = market_research_agent.run_sync(   "Search for 2025 laptop sales trends and average selling prices. Give me the main trends.")print(result.output)

Let me search for current laptop sales trends.Based on the search results, here are the key laptop market trends for 2025:…

Esto cambia tu análisis de datos de trabajar con información desfasada a incluir datos de mercado en tiempo real. En lugar de analizar datos en solitario, tu agente ahora puede comparar el rendimiento de tu empresa con las tendencias actuales del sector.

Ahora añadamos ejecución de código para análisis matemático y procesamiento de datos:

from pydantic_ai import Agent, CodeExecutionTool# Agent that can run calculations and data analysiscalculation_agent = Agent(   'anthropic:claude-sonnet-4-0',   builtin_tools=[CodeExecutionTool()],   system_prompt=(       "You are a data analyst. Use code to perform calculations and create visualizations. "       "Show your work and provide clear explanations."   ))# Analyze sales data with calculationsresult = calculation_agent.run_sync("""I have sales data for Q1 2025:- North region: 150 laptops at $1,500 each, 320 phones at $500 each- South region: 89 laptops at $1,500 each, 245 phones at $500 each - East region: 201 laptops at $1,500 each, 180 phones at $500 each- West region: 167 laptops at $1,500 each, 290 phones at $500 eachCalculate total revenue by region and create a simple chart showing the results.""")print(result.output)```plaintext## SummaryBased on the Q1 2025 sales data analysis, here are the key findings:**Total Revenue by Region:**- **West Region**: $395,500 (highest)- **East Region**: $391,500- **North Region**: $385,000- **South Region**: $256,000 (lowest)

La ejecución de código va más allá de simples respuestas en texto y permite análisis computacionales reales. Tu agente puede realizar cálculos complejos, crear visualizaciones y procesar datos que serían imposibles solo con conversación. El objeto resultado incluye tanto el análisis del agente como los archivos generados durante la ejecución del código, que puedes descargar para seguir trabajando.

Crear herramientas personalizadas

Aunque las herramientas integradas son útiles, a menudo necesitarás herramientas propias que trabajen con tus sistemas de negocio. Las herramientas personalizadas son funciones de Python que tu agente puede invocar durante la conversación.

Creemos herramientas que calculen métricas comunes de ventas:

from pydantic_ai import Agent# Create an agent with custom business toolssales_agent = Agent(   'anthropic:claude-sonnet-4-0',   system_prompt=(       "You are a sales analyst. Use tools to calculate metrics and analyze business data. "       "Give concise answers in 3-4 sentences maximum."   ))@sales_agent.tool_plaindef calculate_conversion_rate(leads: int, sales: int) -> str:   """Calculate conversion rate from leads to sales."""   if leads == 0:       return "Cannot calculate conversion rate: no leads provided"     conversion_rate = (sales / leads) * 100   return f"Conversion rate: {conversion_rate:.2f}% ({sales} sales from {leads} leads)"@sales_agent.tool_plaindef calculate_average_order_value(total_revenue: float, total_orders: int) -> str:   """Calculate average order value."""   if total_orders == 0:       return "Cannot calculate AOV: no orders provided"     aov = total_revenue / total_orders   return f"Average Order Value: ${aov:.2f} (${total_revenue:,.0f} revenue from {total_orders} orders)"# Use the custom toolsresult = sales_agent.run_sync(   "Calculate conversion rate for 500 leads that resulted in 75 sales, and AOV for $180,000 revenue from 120 orders")print(result.output)

Your conversion rate is 15.00%, meaning you're successfully converting 75 out of every 500 leads into sales. The average order value is $1,500.00, indicating strong revenue per transaction. These metrics suggest effective sales processes with high-value customers, though there's room to improve lead conversion rates.

Estas herramientas a medida resuelven cálculos específicos de ventas que tu negocio usa con frecuencia. La conversión ayuda a medir el rendimiento del marketing, mientras que el valor medio del pedido refleja los patrones de gasto de los clientes. Las herramientas personalizadas conectan tu agente con tu lógica de negocio y sistemas concretos.

Para patrones más avanzados de herramientas, incluida la inyección de dependencias y el manejo de errores, consulta la documentación completa de herramientas.

Uso de salidas estructuradas

Hasta ahora los agentes han devuelto texto plano, útil para explorar pero problemático en aplicaciones de producción. Cuando necesitas procesar las respuestas del agente de forma programática, extraer datos concretos o integrar salidas de IA con otros sistemas, necesitas estructura garantizada.

Imagina que quieres analizar datos de ventas y recibir siempre unas métricas concretas. Con texto plano, la IA puede variar el formato cada vez. Con salidas estructuradas, defines exactamente lo que quieres:

from pydantic import BaseModelfrom pydantic_ai import Agentclass SalesInsight(BaseModel):   total_revenue: float   best_performing_region: str   worst_performing_region: str   recommendation: str# Create an agent that returns structured analysisanalysis_agent = Agent(   'anthropic:claude-sonnet-4-0',   output_type=SalesInsight,   system_prompt="Analyze sales data and provide structured insights with clear recommendations.")# Get structured analysisresult = analysis_agent.run_sync("""Q1 2025 sales data:- North: $385,000 revenue (470 units)- South: $256,000 revenue (334 units) - East: $391,500 revenue (381 units)- West: $395,500 revenue (457 units)Analyze this data and provide insights.""")print(f"Total Revenue: ${result.output.total_revenue:,.0f}")print(f"Best Region: {result.output.best_performing_region}")print(f"Recommendation: {result.output.recommendation}")

Total Revenue: $1,428,000Best Region: WestRecommendation: Focus on improving South region performance through targeted marketing and sales training, as it significantly underperforms with only $256,000 revenue. The West region's success ($395,500) should be analyzed and replicated across other regions. Additionally, investigate why East region has the lowest average selling price per unit ($1,028) compared to West's highest ($865) - there may be pricing strategy opportunities.

Fíjate en el parámetro output_type=SalesInsight. Esto le dice al agente que debe devolver un objeto SalesInsight con exactamente esos cuatro campos. Ni más ni menos. El resultado vuelve como result.output, que se valida automáticamente y viene tipado.

Las salidas estructuradas funcionan convirtiendo tu modelo de Pydantic en un esquema JSON que el LLM sigue. La IA no puede desviarse de tu estructura: si intenta devolver otra cosa, Pydantic AI le pedirá que lo intente de nuevo.

Para escenarios más complejos, puedes anidar modelos y usar listas:

from typing import Listfrom pydantic import BaseModelclass RegionalMetrics(BaseModel):   region: str   revenue: float   units_sold: int   average_price: float   performance_rating: str  # "excellent", "good", "needs_improvement"class ComprehensiveAnalysis(BaseModel):   total_revenue: float   total_units: int   regional_breakdown: List[RegionalMetrics]   top_performer: str   areas_for_improvement: List[str]   quarterly_grade: str# Agent with detailed structured outputdetailed_agent = Agent(   'anthropic:claude-sonnet-4-0',   output_type=ComprehensiveAnalysis,   system_prompt=(       "Provide comprehensive sales analysis with detailed regional metrics. "       "Rate each region's performance and give an overall quarterly grade (A-F)."   ))result = detailed_agent.run_sync("""Analyze Q1 2025 performance:- North: $385k revenue, 470 units- South: $256k revenue, 334 units- East: $391.5k revenue, 381 units - West: $395.5k revenue, 457 units""")# Access structured datafor region in result.output.regional_breakdown:   print(f"{region.region}: {region.performance_rating} (${region.average_price:.2f} avg price)")print(f"Quarterly Grade: {result.output.quarterly_grade}")

North: B ($819.15 avg price)South: C ($766.47 avg price)East: A ($1027.56 avg price)West: A- ($865.43 avg price)Quarterly Grade: B+

Este enfoque convierte la IA en procesamiento de datos fiable. Puedes guardar cada métrica regional en una base de datos, disparar alertas en función de las calificaciones de rendimiento o generar paneles ejecutivos automáticamente. Sin regex, sin formatos de respuesta cambiantes: datos limpios y validados siempre.

El parámetro output_type acepta cualquier modelo de Pydantic, dataclass de Python, TypedDict o incluso tipos sencillos como int o list[str]. Para flujos de análisis de datos, esto te permite construir canalizaciones fiables en las que el análisis con IA alimenta directamente tus sistemas de negocio.

Mensajes e historial de chat en agentes Pydantic

Al trabajar con agentes de análisis de datos, a menudo necesitas conversaciones que abarquen varias interacciones. Quizá empieces preguntando por tendencias de ventas y luego quieras profundizar en regiones concretas o comparar periodos. Los mensajes y el historial de chat te permiten mantener el contexto a lo largo de estas conversaciones.

Acceder al historial de mensajes

Cada vez que ejecutas un agente, Pydantic AI registra toda la conversación. Puedes acceder a este historial para entender qué ocurrió o continuarla después:

from pydantic_ai import Agent# Create our sales analysis agentsales_agent = Agent(   'anthropic:claude-sonnet-4-0',   system_prompt="You are a sales analyst. Provide clear, concise analysis.")# First questionresult1 = sales_agent.run_sync("What are the main KPIs I should track for Q1 2025 sales?")print(result1.output)# Access the conversation historyall_messages = result1.all_messages()print(f"Total messages in conversation: {len(all_messages)}")# Just the new messages from this runnew_messages = result1.new_messages()print(f"New messages from this run: {len(new_messages)}")

Here are the essential KPIs to track for Q1 2025 sales:...Total messages in conversation: 2New messages from this run: 2

El método all_messages() te da todo: system prompts, preguntas del usuario y respuestas del agente. El método new_messages() solo devuelve lo ocurrido en la ejecución actual. Es útil para construir conversaciones largas y ver qué ha cambiado.

Continuar conversaciones con historial

Para construir sobre conversaciones previas, pasa el historial de mensajes a la siguiente ejecución del agente. Así el agente recuerda lo ya hablado:

# Continue the conversation from where we left offresult2 = sales_agent.run_sync(   "How should I calculate conversion rates for each of those KPIs?",   message_history=result1.all_messages())print(result2.output)# The agent now has context from both interactionsprint(f"Full conversation length: {len(result2.all_messages())}")# Ask a follow-up that references the entire conversationresult3 = sales_agent.run_sync(   "Which of these metrics would be most important for a monthly executive report?",   message_history=result2.all_messages())print(result3.output)

Cada nueva ejecución se apoya en el contexto anterior. El agente recuerda no solo tus preguntas, sino también sus respuestas previas, creando una conversación analítica coherente.

Guardar y cargar mensajes en JSON

Para almacenamiento a largo plazo o compartir conversaciones entre sistemas, puedes serializar el historial a JSON:

import json# Get the conversation as JSONconversation_json = result3.all_messages_json()# Save to filewith open('sales_analysis_conversation.json', 'w') as f:   f.write(conversation_json.decode('utf-8'))print("Conversation saved to JSON file")# Load it back laterwith open('sales_analysis_conversation.json', 'r') as f:   loaded_conversation = f.read()# You can now use this loaded conversation in a new agent run# (Note: You'd need to convert back from JSON to message objects for actual use)print(f"Loaded conversation size: {len(loaded_conversation)} characters")

El método all_messages_json() devuelve la conversación como bytes JSON, perfecto para guardar en bases de datos, enviar por APIs o archivar sesiones de análisis. También existe new_messages_json() si solo quieres guardar la parte más reciente.

Este enfoque te permite crear flujos de trabajo analíticos persistentes. Puedes guardar la sesión de análisis de cada cliente, retomar investigaciones complejas durante varios días o compartir el contexto de la conversación entre miembros del equipo que trabajen en el mismo análisis.

Trabajar con imágenes y documentos

El análisis real va más allá de texto y números. Puede que necesites analizar gráficos de informes, extraer datos de PDFs o interpretar visualizaciones. Pydantic AI admite entrada de imágenes y documentos, permitiendo que tus agentes trabajen directamente con estas fuentes.

Analizar imágenes desde URLs

Si tienes gráficos o visualizaciones alojados online, puedes apuntar al agente directamente a ellos:

from pydantic_ai import Agent, ImageUrl# Create an agent that can analyze visual datavisual_agent = Agent(   'anthropic:claude-sonnet-4-0',   system_prompt="You are a data analyst who can interpret charts, graphs, and business documents.")# Analyze a sales chart from a URLresult = visual_agent.run_sync([   "What are the main trends shown in this sales chart? Give me 3 key takeaways.",   ImageUrl(url='https://example.com/q1-sales-chart.png')])print(result.output)

El agente puede identificar tipos de gráficos, leer ejes, detectar tendencias y aportar ideas de negocio como lo haría una persona al ver la misma visualización.

Trabajar con imágenes locales

Para imágenes almacenadas localmente — como capturas de tu herramienta de BI o gráficos exportados de Excel — usa BinaryContent:

from pathlib import Pathfrom pydantic_ai import Agent, BinaryContent# Load a local sales dashboard screenshotdashboard_path = Path('sales_dashboard_jan_2025.png')result = visual_agent.run_sync([   "Analyze this sales dashboard. What metrics need attention based on what you see?",   BinaryContent(       data=dashboard_path.read_bytes(),       media_type='image/png'   )])print(result.output)

Este enfoque es ideal para flujos de reporting automatizados. Puedes capturar tus paneles de forma programática y hacer que la IA aporte un análisis escrito que acompañe a las visuales.

Analizar documentos desde URLs

Muchos documentos de negocio se comparten mediante URLs — informes en intranets, PDFs en la nube o papers públicos que fundamentan tu análisis:

from pydantic_ai import Agent, DocumentUrl# Create an agent for document analysisdoc_agent = Agent(   'anthropic:claude-sonnet-4-0',   system_prompt="Extract and summarize business-relevant insights from documents.")# Analyze a quarterly report PDFresult = doc_agent.run_sync([   "Read this quarterly earnings report and summarize the revenue trends and outlook.",   DocumentUrl(url='https://company.com/reports/q1-2025-earnings.pdf')])print(result.output)

El agente puede leer documentos completos, extraer datos relevantes y ofrecer resúmenes que a una persona le llevarían mucho más tiempo.

Procesar documentos locales

Para documentos en tu sistema local — como informes exportados, contratos o presentaciones internas — usa BinaryContent:

from pathlib import Pathfrom pydantic_ai import Agent, BinaryContent# Load a local Excel export saved as PDFreport_path = Path('monthly_sales_analysis_jan_2025.pdf')result = doc_agent.run_sync([   "Extract the key performance metrics from this monthly sales report and identify any concerning trends.",   BinaryContent(       data=report_path.read_bytes(),       media_type='application/pdf'   )])print(result.output)

Esto abre potentes posibilidades de automatización. Puedes procesar lotes de informes, extraer datos de facturas o analizar términos contractuales: tareas que normalmente requieren revisión manual.

Notas importantes:

Los modelos admiten distintos formatos. La mayoría maneja imágenes comunes (PNG, JPEG) y PDFs, pero revisa la documentación de tu modelo. Algunos, como Vertex AI de Google, pueden acceder directamente a URLs de almacenamiento en la nube, mientras que otros descargan el contenido primero.

Para flujos de análisis, esta capacidad multimodal une tus informes visuales con insights impulsados por IA, haciendo posible automatizar el análisis de toda la documentación con la que trabajas a diario.

Activar el streaming en Pydantic AI

Cuando abordas análisis complejos, querrás ver los resultados conforme se generan en lugar de esperar a la respuesta completa. El streaming permite ver el análisis en tiempo real, muy útil al hacer preguntas detalladas sobre rendimiento de ventas.

Pydantic AI ofrece streaming integrado mediante el método run_stream(). Así funciona:

import asynciofrom pydantic_ai import Agent# Create our sales analysis agentsales_agent = Agent(   'anthropic:claude-sonnet-4-0',   system_prompt=(       "You are a data analyst specializing in sales performance. "       "Provide detailed, actionable insights based on the data provided."   ))async def demo_streaming():   question = """   Analyze this sales scenario: Our company sold 1,200 laptops and 2,300 phones   last quarter across 4 regions. Laptops average $1,500 each, phones $500 each.   What are the key insights and recommendations?   """     async with sales_agent.run_stream(question) as result:       async for text in result.stream_text():           print(text, end='', flush=True)# Run the streaming analysisasyncio.run(demo_streaming())

Entendiendo la sintaxis de streaming:

El async with crea una conexión con el LLM que permanece abierta mientras recibes fragmentos de texto. Piénsalo como abrir una llamada: estableces la conexión, mantienes la conversación y después cuelgas correctamente.

El bucle async for procesa cada fragmento según llega. Ten en cuenta que stream_text() regenera el texto completo cada vez: verás "Hola", luego "Hola mundo", después "Hola mundo, cómo". Te da el contexto completo, pero puede ser repetitivo al mostrarlo.

Por qué async y asyncio funcionan juntos:

Cuando preguntas a un LLM, tarda en generar la respuesta (normalmente 3–10 segundos). Durante ese tiempo, el modelo envía pequeños trozos de texto cada 50–200 milisegundos.

Sin async, tu programa quedaría bloqueado esperando cada fragmento. Con async, el event loop de Python (el sistema que gestiona estas esperas) puede cambiar entre tareas. Así tu programa sigue respondiendo e incluso puede llevar varias conversaciones a la vez.

asyncio.run() es lo que pone todo en marcha: crea el event loop que coordina todo. Cuando llamas a asyncio.run(demo_streaming()), configura el entorno en el que tus funciones async pueden pausar y reanudarse mientras esperan las respuestas del LLM.

Ahora creemos una función reutilizable que muestre solo los deltas de texto nuevos para una experiencia de streaming mejor:

from pydantic_ai.messages import PartDeltaEvent, TextPartDeltaasync def stream_agent_response(agent: Agent, task: str):   """   Stream a response from any Pydantic AI agent showing just new text deltas.   """   async def event_handler(ctx, event_stream):       async for event in event_stream:           if isinstance(event, PartDeltaEvent) and isinstance(               event.delta, TextPartDelta           ):               print(event.delta.content_delta, end="", flush=True)   # Use agent.run() with event_stream_handler for proper streaming   result = await agent.run(task, event_stream_handler=event_handler)   print()  # Add a newline when streaming is complete   return result# Usage exampleresponse = asyncio.run(stream_agent_response(   sales_agent,   "What are the top 3 metrics I should track for quarterly sales analysis?"))

Desglose de la función de streaming:

La función stream_agent_response() crea una experiencia de streaming más natural mostrando solo el texto nuevo a medida que llega. Así funciona:

1. Configuración del event handler: la función interna event_handler() escucha eventos específicos durante el procesamiento del agente. Filtra PartDeltaEvent con TextPartDelta, que representan nuevos fragmentos de texto.
2. Contenido delta: en lugar de recibir el texto regenerado completo cada vez, event.delta.content_delta nos da solo las palabras o caracteres nuevos. Crea un efecto "máquina de escribir" donde ves la respuesta escribirse palabra a palabra.
3. Ejecución del agente: usamos agent.run() con el parámetro event_stream_handler. Esto indica al agente que llame a nuestro handler personalizado para cada evento de streaming, dándonos control granular sobre lo que se muestra.
4. Salida en tiempo real: print(event.delta.content_delta, end="", flush=True) muestra cada fragmento al instante sin saltos de línea, creando un flujo continuo de texto.

Con este enfoque tendrás la sensación natural de ver a la IA pensar el análisis en tiempo real, en lugar de esperar a la respuesta completa o ver texto regenerado repetidamente. Usaremos esta función en las próximas secciones para mostrar respuestas en streaming en nuestros ejemplos de análisis de datos.

Conclusión

A lo largo de este tutorial, has adquirido una comprensión completa de Pydantic AI mediante ejemplos prácticos de análisis de datos. Has aprendido a crear agentes con system prompts, añadir herramientas integradas y personalizadas, estructurar salidas con modelos de Pydantic y transmitir respuestas para obtener feedback en tiempo real. Estos componentes se combinan para crear sistemas de IA que actúan más como socios analíticos que como simples chatbots.

Las aplicaciones van mucho más allá de los ejemplos de ventas que hemos visto. Ahora puedes construir agentes de IA que lean tus fuentes de datos, sigan tus reglas de negocio y devuelvan resultados en formatos compatibles con tus sistemas. Ya sea para automatizar informes, analizar feedback de clientes o procesar datos financieros, Pydantic AI te da la estructura y fiabilidad que necesitas en producción.

Si te interesa crear sistemas multiagente con LangGraph, no te pierdas nuestro curso práctico.