1. Configuración y primer éxito

¡Bienvenido a tu aventura para construir agentes (agent) de IA con Python! Al final de este capítulo, habrás hecho tu primera llamada exitosa a un Modelo de Lenguaje Grande (LLM) y habrás entendido exactamente qué ocurrió entre bambalinas. Esta es tu base para todo lo que viene después.

Requisitos previos

Audiencia y supuestos

Este libro está escrito para desarrolladores de Python que quieren construir agentes de IA pero no tienen experiencia previa con LLM o frameworks de IA. Asumimos que te sientes cómodo con:

Fundamentos de Python: funciones, clases, imports, estructuras de datos básicas
Python 3.10+: deberías tener Python 3.10 o superior instalado en tu sistema
Entornos virtuales: crear y activar venvs con python -m venv
Gestión de paquetes: instalar paquetes con pip
Variables de entorno: configurar y leer variables de entorno en tu shell
Claves de API: entender qué son las claves de API y cómo obtenerlas de proveedores de servicios

Si alguno de estos conceptos te resulta desconocido, recomendamos repasarlos por separado antes de continuar. La documentación de Python y los tutoriales sobre entornos virtuales y pip son excelentes puntos de partida.

Lo que NO asumimos: no necesitas ningún conocimiento previo de machine learning, redes neuronales, transformers o teoría de IA. Explicaremos los conceptos específicos de LLM a medida que los encontremos, conectándolos siempre con patrones de programación familiares.

Convención de modelo

A lo largo de este libro, usaremos GPT-5-mini como nuestro modelo predeterminado para los ejemplos. Aquí tienes por qué:

Ampliamente disponible: la API de OpenAI es accesible globalmente con un registro sencillo
Velocidad razonable: con un esfuerzo mínimo de razonamiento, las respuestas llegan lo suficientemente rápido para un desarrollo iterativo
Rentable: a $0.25 por millón de tokens de entrada y $2.00 por millón de tokens de salida (a fecha de 2026), es asequible para aprender y experimentar
Capacidad suficiente: maneja muy bien la gran mayoría de tareas prácticas de agentes de IA

Cuando veas ejemplos de código sin un modelo especificado explícitamente, asume que estamos usando GPT-5-mini. En el Capítulo 2, exploraremos todo el panorama de modelos disponibles (Claude, Gemini y otras variantes de GPT) y hablaremos sobre cuándo podrías elegir alternativas según el tamaño de la ventana de contexto, el coste o capacidades especializadas.

1.1) ¿Qué es un LLM?

Antes de escribir cualquier código, establezcamos con qué estamos trabajando realmente. Un Modelo de Lenguaje Grande (LLM) es una red neuronal entrenada con cantidades masivas de datos de texto para predecir qué texto debería venir a continuación en una secuencia.

Piensa en ello como un sistema de autocompletado extremadamente sofisticado. Cuando escribes en tu teléfono y te sugiere la siguiente palabra, eso es una versión simple de lo que hacen los LLM. Pero los LLM operan a una escala y con una sofisticación que les permite:

Generar respuestas coherentes y contextualmente apropiadas a preguntas
Escribir código, ensayos, correos electrónicos y otro contenido estructurado
Traducir entre idiomas
Resumir documentos largos
Extraer información de texto no estructurado
Y mucho más

En qué se diferencian los LLM del software tradicional

El software tradicional sigue reglas explícitas que tú programas:

python

def calculate_discount(price, customer_type):
    if customer_type == "premium":
        return price * 0.8  # 20% discount
    elif customer_type == "regular":
        return price * 0.95  # 5% discount
    else:
        return price

Esta función siempre produce la misma salida para las mismas entradas. La lógica es determinista y transparente.

Los LLM funcionan de otra manera. En lugar de reglas explícitas, usan patrones aprendidos a partir de los datos de entrenamiento para generar respuestas. Tú proporcionas texto de entrada (llamado un prompt), y el modelo genera texto de salida (llamado una completion o respuesta).

python

# Ejemplo conceptual: pronto escribiremos código real
response = llm.generate("¿Cuál es un buen descuento para clientes premium?")
# Ejemplo de salida: "Los clientes premium normalmente reciben descuentos del 15-25%..."

El LLM no tiene un porcentaje de descuento codificado. Genera una respuesta basada en patrones que aprendió durante el entrenamiento. Esto significa:

Las respuestas pueden variar: el mismo prompt podría producir respuestas ligeramente diferentes cada vez
El comportamiento se aprende, no se programa: guías al modelo con prompts en lugar de escribir lógica explícita
Las capacidades emergen a partir de la escala: el modelo puede manejar tareas para las que no fue entrenado explícitamente

Terminología clave

Definamos términos que encontrarás constantemente:

Prompt: el texto de entrada que envías al modelo. Piensa en ello como la "pregunta" o "instrucción"
Completion/Respuesta: el texto que el modelo genera en respuesta a tu prompt
Token: la unidad básica con la que trabajan los LLM. Aproximadamente, 1 token ≈ 4 caracteres o ¾ de una palabra. "Hello world" son alrededor de 2 tokens
Ventana de contexto: la cantidad máxima de texto (en tokens) que el modelo puede procesar de una vez. GPT-5-mini tiene una ventana de contexto de 400K tokens
Temperatura: un parámetro que controla la aleatoriedad. Más baja (0.0-0.3) = más enfocada y determinista. Más alta (0.7-1.0) = más creativa y variada

Qué pueden y qué no pueden hacer los LLM

Entender qué hacen de forma fiable los LLM—y qué solo parece que hacen—es esencial para construir agentes de IA robustos.

Los LLM son excelentes en:

Entender y generar lenguaje natural: pueden interpretar la intención, generar respuestas coherentes y manejar formulaciones complejas

"Quiero un reembolso" → Reconoce la intención: refund_request
"Resume este documento" → Produce un resumen conciso

Seguir instrucciones en prompts: cuando se les dan directrices claras, pueden producir salidas estructuradas como JSON o texto con formato

"Convierte a JSON: John Smith, 32, vive en Boston"
→ {"name": "John Smith", "age": 32, "city": "Boston"}

Reconocer patrones en texto: el análisis de sentimiento, la categorización y la extracción de información funcionan de forma fiable
Generar código y contenido estructurado: pueden escribir Python válido, SQL u otra salida formateada cuando se les da el prompt adecuado
Razonamiento paso a paso: cuando se les indica explícitamente que "piensen paso a paso", descomponen los problemas de manera metódica

Limitaciones de los LLM:

No son una base de datos: no recuperan hechos, generan texto estadísticamente plausible. Pueden afirmar con seguridad información incorrecta que suena autoritativa.

"¿Cuándo se lanzó Python 4.0?" 
→ Podría generar "Python 4.0 se lanzó en 2023" (falso, pero plausible)

No son una calculadora: predicen cómo debería verse una respuesta en lugar de calcularla. La aritmética simple suele funcionar; las matemáticas complejas fallan de forma impredecible.

"¿Cuánto es 8,247 × 6,839?" → Puede dar un resultado incorrecto que parece razonable

No son deterministas: el mismo prompt puede producir salidas diferentes cada vez. Esta variabilidad se controla con el parámetro de temperatura.
No siempre son precisos: generan texto plausible independientemente de la corrección factual. Las "alucinaciones"—información detallada, segura, pero completamente inventada—ocurren con frecuencia.

La idea clave: construye agentes que combinen LLM (para comprensión y toma de decisiones) con herramientas tradicionales (para cálculo, recuperación de datos y operaciones factuales). Implementaremos este patrón a partir del Capítulo 13, donde el LLM decide cuándo usar una calculadora en lugar de intentar hacer matemáticas por sí mismo.

Lo que aprenderás

En este libro, aprenderás a construir agentes de IA: sistemas en los que el LLM decide de manera autónoma qué acciones tomar para lograr objetivos, en lugar de seguir lógica predeterminada. Exploraremos este paradigma en profundidad en el Capítulo 2.

1.2) Instalar dependencias

Vamos a configurar tu entorno de desarrollo. Crearemos una estructura de proyecto limpia e instalaremos LangChain, el framework que usaremos para construir agentes de IA.

Verificar la instalación de Python

Primero, asegúrate de que Python esté instalado en tu sistema. Recomendamos Python 3.10 o superior (a fecha de 2026, Python 3.13 o 3.14 son buenas opciones).

Comprueba tu versión de Python:

bash

python --version
# or
python3 --version

Deberías ver una salida como Python 3.13.x o Python 3.14.x.

Si Python no está instalado:

macOS:
- Descárgalo desde python.org
- O usa Homebrew: brew install python@3.14
Windows:
- Descárgalo desde python.org
- Marca "Add Python to PATH" durante la instalación
Linux:
- Ubuntu/Debian: sudo apt update && sudo apt install python3.14
- Fedora: sudo dnf install python3.14

Después de instalarlo, verifica de nuevo con python --version.

Nota: en algunos sistemas, puede que necesites usar python3 en lugar de python. A lo largo de este libro, si python no funciona, prueba python3.

Crea tu proyecto

Abre tu terminal y crea un nuevo directorio para tu proyecto:

bash

mkdir agentic-ai-project
cd agentic-ai-project

Crea un entorno virtual para aislar dependencias:

bash

python -m venv venv

Activa el entorno virtual:

bash

# On macOS/Linux:
source venv/bin/activate
 
# On Windows:
venv\Scripts\activate

Deberías ver (venv) aparecer en el prompt de tu terminal, lo que indica que el entorno virtual está activo.

Instalar LangChain y OpenAI

Instalaremos la integración de OpenAI de LangChain, que incluye todo lo necesario para trabajar con los modelos de OpenAI:

bash

pip install langchain-openai

Esto instala langchain-openai junto con sus dependencias, incluyendo langchain-core (las abstracciones principales de LangChain) y el cliente de Python de OpenAI. Deberías ver salida que confirme la instalación de múltiples paquetes.

Verifica la instalación:

bash

pip show langchain-openai

Deberías ver detalles sobre el paquete instalado, incluyendo su número de versión y ubicación. Esto confirma que la instalación fue exitosa.

Obtén tu clave de API de OpenAI

Para llamar a los modelos de OpenAI, necesitas una clave de API:

Ve a platform.openai.com
Regístrate o inicia sesión
Navega a API Keys en la configuración de tu cuenta
Haz clic en "Create new secret key"
Copia la clave (empieza con sk-)

⚠️ Advertencia de seguridad: trata esta clave como una contraseña. Nunca la subas a control de versiones ni la compartas públicamente. Cualquiera con tu clave puede hacer llamadas a la API que se facturarán a tu cuenta.

Configura tu clave de API como variable de entorno

La forma recomendada de proporcionar tu clave de API es mediante una variable de entorno:

bash

# On macOS/Linux:
export OPENAI_API_KEY='sk-your-actual-key-here'
 
# On Windows (Command Prompt):
set OPENAI_API_KEY=sk-your-actual-key-here
 
# On Windows (PowerShell):
$env:OPENAI_API_KEY='sk-your-actual-key-here'

Nota: esta configuración es temporal y se perderá cuando cierres la terminal. Para una solución permanente, puedes:

Añadir el comando export a tu archivo de configuración del shell (.bashrc, .zshrc, etc.)
Usar un .env file (lo configuraremos en el Capítulo 3 para una mejor organización del proyecto)

Por ahora, la configuración temporal es suficiente para continuar.

Verifica que esté configurada:

bash

# On macOS/Linux:
echo $OPENAI_API_KEY
 
# On Windows (Command Prompt):
echo %OPENAI_API_KEY%
 
# On Windows (PowerShell):
echo $env:OPENAI_API_KEY

Deberías ver tu clave de API impresa. Si no, repite el comando export/set y asegúrate de que no haya errores tipográficos.

1.3) Tu primera llamada a un LLM

Ahora viene la parte emocionante: vamos a hacer tu primera llamada a un LLM. Crea un archivo llamado first_call.py:

python

# first_call.py
from langchain_openai import ChatOpenAI
 
# Inicializa el LLM
llm = ChatOpenAI(model="gpt-5-mini")
 
# Envía un prompt y obtiene una respuesta
response = llm.invoke("¿Qué es LangChain?")
 
# Imprime la respuesta
print(response.content)

Ejecútalo:

bash

python first_call.py

Deberías ver una salida similar a esta (la redacción exacta puede variar):

LangChain es un framework diseñado para simplificar el desarrollo de aplicaciones impulsadas por modelos de lenguaje grandes (LLM). Proporciona herramientas y abstracciones para construir cadenas de llamadas a LLM, integrar fuentes de datos externas, gestionar prompts y crear agentes que pueden interactuar con varias API y bases de datos. LangChain facilita la construcción de aplicaciones de IA complejas al proporcionar componentes y patrones reutilizables.

¡Enhorabuena! Acabas de hacer tu primera llamada a un LLM. Vamos a desglosar lo que ocurrió en este código.

Solución de problemas: si ves un error:

AuthenticationError: la clave de API no es válida o no está configurada → revisa tu variable de entorno OPENAI_API_KEY (consulta la sección 1.2)
RateLimitError: peticiones demasiado rápidas o límite de uso excedido → espera unos segundos y reintenta, o revisa el uso en platform.openai.com/usage
APIConnectionError: problema de conectividad de red → revisa tu conexión a internet

Entender el código

Importa el wrapper del LLM:

python

from langchain_openai import ChatOpenAI

ChatOpenAI es el wrapper de LangChain alrededor de los modelos de chat de OpenAI. Maneja por ti la autenticación de la API, el formateo de la solicitud y el parseo de la respuesta.

Inicializa el modelo:

python

llm = ChatOpenAI(model="gpt-5-mini")

Esto crea una instancia configurada para usar GPT-5-mini. Entre bambalinas, LangChain lee tu variable de entorno OPENAI_API_KEY para autenticación. También podrías pasar la clave explícitamente:

python

llm = ChatOpenAI(model="gpt-5-mini", api_key="sk-your-key")

Pero usar variables de entorno es más seguro y flexible.

Invoca el modelo:

python

response = llm.invoke("¿Qué es LangChain?")

El método invoke() envía tu prompt a la API de OpenAI y espera la respuesta completa. Esta es una llamada sincrónica: tu programa se pausa hasta que llega la respuesta.

Accede al contenido de la respuesta:

python

print(response.content)

El objeto de respuesta contiene varios campos. El campo .content contiene el texto real generado por el modelo. Exploraremos otros campos en la siguiente sección.

Prueba prompts diferentes

Modifica el prompt para ver cómo responde el modelo a distintas entradas:

python

# first_call.py
from langchain_openai import ChatOpenAI
 
llm = ChatOpenAI(model="gpt-5-mini")
 
# Prueba prompts diferentes
prompts = [
    "Explica los decoradores de Python en una frase.",
    "¿Cuánto es 15 * 23?",
    "Enumera tres beneficios de usar type hints en Python.",
]
 
for prompt in prompts:
    response = llm.invoke(prompt)
    print(f"Prompt: {prompt}")
    print(f"Response: {response.content}\n")

El modelo maneja diferentes tipos de peticiones: explicaciones, cálculos y listas estructuradas. Notarás que las respuestas pueden variar ligeramente si ejecutas el mismo prompt varias veces. Este comportamiento es normal: exploraremos por qué ocurre y cómo controlarlo en el Capítulo 2.

1.4) ¿Qué acaba de pasar? (Flujo Solicitud → Modelo → Respuesta)

Examinemos exactamente qué ocurrió cuando llamaste a llm.invoke(). Entender este flujo es crucial para construir agentes de IA confiables.

El ciclo completo de solicitud-respuesta

Sigamos cada paso:

Paso 1: Tu código llama a invoke()

python

response = llm.invoke("¿Qué es LangChain?")

El método invoke() es tu interfaz principal con el LLM. Le pasas un string de prompt y devuelve un objeto de respuesta que contiene la respuesta del modelo. Detrás de esta llamada simple, ocurren automáticamente varios pasos.

Paso 2: LangChain formatea la solicitud

LangChain transforma tu string en una solicitud estructurada para la API. Entre bambalinas, crea un payload JSON como este:

json

{
  "model": "gpt-5-mini",
  "messages": [
    {
      "role": "user",
      "content": "¿Qué es LangChain?"
    }
  ],
  "temperature": 1.0
}

El array messages es la forma en la que los modelos de chat reciben entrada. Cada mensaje tiene un role (user, assistant, o system) y content (el texto). Exploraremos los roles de mensajes en el Capítulo 4.

Paso 3: Llamada a la API de OpenAI

LangChain envía una solicitud HTTPS POST al endpoint de la API de OpenAI:

POST https://api.openai.com/v1/chat/completions
Authorization: Bearer sk-your-api-key
Content-Type: application/json
 
{request payload}

Tu clave de API autentica la solicitud. Los servidores de OpenAI reciben la solicitud y la enrutan al modelo especificado.

Paso 4: El modelo procesa el prompt

GPT-5-mini recibe tu prompt y genera una respuesta token por token. El modelo:

Convierte tu texto en tokens (representaciones numéricas)
Procesa tokens a través de sus capas de red neuronal
Predice el token siguiente más probable
Repite hasta que genera una respuesta completa o alcanza una condición de parada

Esto ocurre en los servidores de OpenAI: tu código solo espera el resultado.

Paso 5: La API devuelve la respuesta

La API de OpenAI envía de vuelta una respuesta JSON:

json

{
  "id": "chatcmpl-8x7y9z",
  "object": "chat.completion",
  "created": 1704067200,
  "model": "gpt-5-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "LangChain es un framework diseñado para simplificar..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 58,
    "total_tokens": 70
  }
}

Campos clave:

message.content: el texto generado
usage: conteos de tokens para facturación y monitoreo
finish_reason: por qué se detuvo la generación ("stop" = finalización natural, "length" = alcanzó el límite de tokens)

Paso 6: LangChain parsea la respuesta

LangChain convierte el JSON en un objeto de Python con el que puedes trabajar:

python

from langchain_openai import ChatOpenAI
 
llm = ChatOpenAI(model="gpt-5-mini")
response = llm.invoke("¿Qué es LangChain?")
 
# Explora el objeto de respuesta
print(f"Content: {response.content}")
print(f"Type: {type(response)}")
print(f"Response metadata: {response.response_metadata}")

Salida:

Content: LangChain es un framework diseñado para simplificar...
Type: <class 'langchain_core.messages.ai.AIMessage'>
Response metadata: {'token_usage': {'completion_tokens': 58, 'prompt_tokens': 12, 'total_tokens': 70}, 'model_name': 'gpt-5-mini', 'finish_reason': 'stop'}

La respuesta es un objeto AIMessage con varios atributos útiles:

content: el texto generado (lo que normalmente quieres)
response_metadata: uso de tokens, nombre del modelo, motivo de finalización
id: identificador único para esta respuesta
usage_metadata: desglose detallado de tokens

Entender el uso de tokens

Antes de ver los conteos de tokens, una nota rápida: los tokens son las unidades básicas que procesan los LLM. En inglés, el texto suele usar un poco más de 1 token por palabra (p. ej., "explain quantum computing" = 3 palabras, 4-5 tokens), pero lenguajes no ingleses como el coreano o el chino requieren significativamente más tokens para representar el mismo texto. Exploraremos los tokens con más detalle en el Capítulo 2.

Examinemos el consumo de tokens con más detalle:

python

from langchain_openai import ChatOpenAI
 
llm = ChatOpenAI(model="gpt-5-mini")
response = llm.invoke("Explain quantum computing in simple terms.")
 
usage = response.response_metadata['token_usage']
print(f"Input tokens: {usage['prompt_tokens']}")
print(f"Output tokens: {usage['completion_tokens']}")
print(f"Total tokens: {usage['total_tokens']}")

Salida:

Input tokens: 11
Output tokens: 95
Total tokens: 106

Nota: prompt_tokens = tokens de entrada (tu prompt), completion_tokens = tokens de salida (la respuesta del modelo), total_tokens = suma de ambos.

El consumo de tokens varía según:

Longitud del prompt: prompts más largos usan más tokens de entrada
Detalle de la respuesta: respuestas detalladas generan más tokens de salida
Complejidad del idioma: términos técnicos y código pueden tokenizarse de forma diferente

Por ejemplo, un prompt corto como "What's 2+2?" podría usar solo 5-6 tokens de entrada y 8-10 tokens de salida, mientras que "Write a detailed essay about the history of Python programming language" podría usar 15-20 tokens de entrada y 500+ tokens de salida.

Cálculo de coste para el ejemplo anterior:

Con el precio de GPT-5-mini ($0.25 por millón de tokens de entrada, $2.00 por millón de tokens de salida):

Entrada: 11 tokens × $0.25 / 1,000,000 = $0.00000275
Salida: 95 tokens × $2.00 / 1,000,000 = $0.00019
Total: ~$0.0002 (dos centésimas de un centavo)

Pagas por tokens de entrada y de salida, pero los tokens de salida cuestan más (8× en este caso).

Lo que has aprendido

Ahora entiendes el ciclo de vida completo de una llamada a un LLM:

Tu código proporciona un string de prompt
LangChain lo formatea en una solicitud a la API con autenticación
La API de OpenAI enruta la solicitud al modelo
El modelo genera una respuesta token por token
La API devuelve JSON estructurado con la respuesta y metadatos
LangChain lo parsea a un objeto de Python
Tu código accede al contenido y a los metadatos

También has aprendido:

Cómo inspeccionar objetos de respuesta y extraer metadatos
Cómo el uso de tokens afecta a los costes

Esta base te prepara para el Capítulo 2, donde exploraremos cómo funcionan realmente los LLM por dentro, compararemos distintos modelos y aprenderemos técnicas de prompt engineering para obtener mejores resultados.