Si todavía no leíste la base conceptual, te recomendamos revisar la guía “Construyendo agentes de IA con LangChain y LangGraph: conceptos”, donde se explican de forma clara los principios, la arquitectura y los casos de uso más comunes de estos frameworks. Este conocimiento previo te va a ayudar a entender mejor cada paso de esta guía y a tomar mejores decisiones técnicas al momento de desarrollar tus propios agentes de IA.

Requisitos Previos

• Ubuntu 24.04 instalado
• Editor de código (VS Code, PyCharm, etc.)
• Conexión a internet

Paso 1: Instalar Python 3.11+

LangGraph requiere Python 3.11 o superior. Verificá tu versión actual:

python3 --version

Si necesitás instalar o actualizar Python:

sudo apt update
sudo apt install python3.11 python3.11-venv python3-pip -y

Paso 2: Crear el Directorio del Proyecto

mkdir mi-proyecto-langgraph
cd mi-proyecto-langgraph

Paso 3: Crear y Activar un Entorno Virtual

Es una buena práctica usar entornos virtuales para aislar las dependencias del proyecto:

python3 -m venv venv
source venv/bin/activate

Deberías ver (venv) al inicio de tu línea de comandos.

Paso 4: Instalar LangGraph y Dependencias

Instalá LangGraph y LangChain:

pip install --upgrade pip
pip install langgraph langchain langchain-core langraph-cli langgraph-api

Paso 5: Crear una Cuenta en LangSmith

LangSmith es una plataforma para monitorear, depurar y evaluar aplicaciones LLM.

1. Andá a https://smith.langchain.com/
2. Hacé clic en «Sign Up» o «Get Started»
3. Completá el registro con tu correo electrónico y contraseña
4. Verificá tu correo electrónico si es necesario
5. Iniciá sesión en tu cuenta de LangSmith

Paso 6: Generar una API Key de LangSmith

1. Una vez dentro de LangSmith, andá a Settings (Configuración) en el menú lateral
2. Buscá la sección «API Keys»
3. Hacé clic en «Create API Key» o «+ New API Key»
4. Dale un nombre descriptivo a tu clave (ejemplo: «Proyecto LangGraph Local»)
5. Copiá la API key generada (guardala en un lugar seguro, no podrás verla de nuevo)

Paso 7: Configurar Variables de Entorno

Creá un archivo .env en la raíz de tu proyecto para almacenar las credenciales:

touch .env

Abrí el archivo .env con tu editor y agregá:

LANGCHAIN_TRACING_V2=true
LANGCHAIN_ENDPOINT=https://api.smith.langchain.com
LANGCHAIN_API_KEY=tu_api_key_de_langsmith_aqui
LANGCHAIN_PROJECT=mi-proyecto-langgraph

Reemplazá tu_api_key_de_langsmith_aqui con la API key que copiaste.

Paso 8: Obtener API Key de un Proveedor LLM

LangGraph soporta múltiples proveedores de modelos de lenguaje. Seleccioná uno de los siguientes:

• OpenAI – Registrate en platform.openai.com y generá una API key
• Anthropic (Claude) – Registrate en console.anthropic.com
• Google (Gemini) – Obtené credenciales en ai.google.dev
• Cohere – Registrate en dashboard.cohere.com
• Azure OpenAI – Configurá en tu portal de Azure

Agregá la API key de tu proveedor elegido al archivo .env:

# Para OpenAI
OPENAI_API_KEY=tu_api_key_de_openai

# Para Anthropic
ANTHROPIC_API_KEY=tu_api_key_de_anthropic

# Para Google
GOOGLE_API_KEY=tu_api_key_de_google

Paso 9: Instalar el Paquete del Proveedor LLM

# Para OpenAI
pip install langchain-openai

# Para Anthropic
pip install langchain-anthropic

# Para Google
pip install langchain-google-genai

# Para Cohere
pip install langchain-cohere

Paso 10: Instalar python-dotenv

Para cargar las variables de entorno desde el archivo .env:

pip install python-dotenv

Paso 11: Crear un Archivo de Prueba

Creá un archivo test_setup.py para verificar la instalación:

from dotenv import load_dotenv
import os

# Cargar variables de entorno
load_dotenv()

# Verificar que las variables están cargadas
print("LANGCHAIN_API_KEY:", "✓ Configurada" if os.getenv("LANGCHAIN_API_KEY") else "✗ No encontrada")
print("OPENAI_API_KEY:", "✓ Configurada" if os.getenv("OPENAI_API_KEY") else "✗ No encontrada")

# Prueba simple de LangGraph
from langgraph.graph import StateGraph
from typing import TypedDict

class State(TypedDict):
    mensaje: str

def nodo_saludo(state: State):
    return {"mensaje": "¡Hola desde LangGraph!"}

# Crear grafo
workflow = StateGraph(State)
workflow.add_node("saludo", nodo_saludo)
workflow.set_entry_point("saludo")
workflow.set_finish_point("saludo")

app = workflow.compile()

# Ejecutar
resultado = app.invoke({"mensaje": ""})
print("\nResultado:", resultado)

Paso 12: Ejecutar la Prueba

python test_setup.py

Si todo está configurado correctamente, deberías ver las confirmaciones de las API keys y el mensaje de saludo.

Paso 13: Crear requirements.txt

pip freeze > requirements.txt

Paso 14: Configurar .gitignore

Si usás Git, creá un archivo .gitignore para evitar subir información sensible:

.env
venv/
__pycache__/
*.pyc
.DS_Store

¡Entorno Listo!

Tu entorno de desarrollo para LangGraph está completamente configurado. Ahora podés empezar a construir tus agentes de IA.

Comandos Útiles

• Activar entorno virtual: source venv/bin/activate
• Desactivar entorno virtual: deactivate
• Instalar desde requirements.txt: pip install -r requirements.txt
• Actualizar dependencias: pip install --upgrade langgraph langchain

Recursos Adicionales

• Documentación oficial de LangGraph
• Documentación de LangSmith
• Guía de LangChain

La entrada Construyendo Agentes de IA con LangChain y LangGraph: Entorno de desarrollo se publicó primero en Jorge Castrillo.

Luego, investigando y leyendo sobre Agentes de IA, descubrí LangGraph, un framework especializado para construir agentes de IA disponible en dos lenguajes: TypeScript (JavaScript tipado) y Python. Así que me di a la tarea de aprenderlo. Inicié viendo algunos videos en YouTube para visualizar sus capacidades y luego me inscribí en el curso gratuito que ofrecen en LangChain Academy, altamente recomendado para iniciarse bien en este mundo de construcción de Agentes de IA.

💡 Si te gusta tener el control y programar, LangGraph es lo que necesitas para construir tus agentes de IA.

¿Qué es LangGraph?

Utilizado por las compañías más grandes del mundo como Replit, Klarna, Elastic y muchas más, LangGraph es un framework que te permite construir agentes de IA a bajo nivel. Esto quiere decir que vos como desarrollador tenés la libertad de programar al agente con tus propias reglas y tu propia lógica.

Beneficios

Es de código abierto, lo que significa que lo podés desplegar localmente o en tus propios servidores. Por supuesto, LangChain también te provee de un ecosistema avanzado de pago con funcionalidades adicionales.

«El cielo es el límite», y en este caso la capacidad de abstraer un problema y llevarlo a una solución con LangGraph es posible para casi cualquier cosa. No te voy a mentir, será laborioso, pero si estás buscando una solución robusta y estable para construir un Agente de IA, esto es lo que necesitas.

Además, hay más beneficios propios del framework:

• Ejecución Duradera: Los agentes pueden ejecutarse por largos períodos de tiempo, manteniendo su estado y retomando donde lo dejaron, incluso después de interrupciones.
• Human-in-the-loop: Te permite crear una lógica donde puedas incorporar al humano en la toma de decisiones del grafo. Por ejemplo, antes de agendar una cita importante, el agente puede pausar y pedir confirmación.
• Memoria: Los agentes tienen un State (estado) de memoria a corto plazo que podés usar para el razonamiento continuo, y memoria a largo plazo en cada sesión.
• Debugging: En el ecosistema se te provee de una aplicación web llamada LangSmith que te ayuda a tener visibilidad completa de qué está pasando con tu agente, cómo lo está haciendo, cuánto te está costando y más.

Caso de Uso: Agente de Gestión de Calendario

Cuando vas a desarrollar un Agente en LangGraph, lo primero que necesitás hacer es descomponer la tarea en pasos, llamados Nodos. Un nodo puede ser un proceso determinista, no determinista (como una llamada a un LLM), o una decisión. Finalmente, debés tener claro que todos los nodos comparten un estado (estructura de objeto) global, que podés consultar y actualizar en cada paso.

Veamos el siguiente proceso con un ejemplo práctico:

Piensa qué querés automatizar

Para este ejemplo, lo que quiero automatizar es el proceso de gestión de calendario con las siguientes capacidades:

Ejemplos de escenarios
-Buscar espacio en la agenda: "Podrías buscar un hueco en mi agenda para el martes"
-Verificar horario: "Revisa si tengo libre el jueves a las 3"
-Agendar cita: "Agendame una reunión para mañana a la 1"
-Cancela una cita: "Cancela la cita del viernes a las 4 de la tarde"
-Reprogramar una cita: "Reprograma la reunión de mañana a las 2 y ponela para la próxima semana"

El Agente debe poder
-Conectarse a mi calendario
-Consultar disponibilidad de horarios
-Agendar una cita
-Cancelar una cita
-Reprogramar una cita

Paso 1: Diagrama el flujo

Comienza identificando cada uno de los pasos en el proceso. Cada paso se convierte en un nodo, una función que hace solo una tarea específica.

Las flechas declaran las rutas posibles, pero la decisión de qué ruta tomar se encuentra dentro de cada nodo o en nodos de decisión especiales.

A esto le podemos llamar Agente. Un agente puede ser simple o muy complejo, y el ejemplo anterior lo demuestra. El proceso de agendar una cita, cancelarla, reagendarla o buscar espacios no se puede simplificar en una sola función, y para ello introduzco el concepto de sub-agentes, donde cada nodo podría ser un sub-agente con su propia lógica de nodos para intentar resolver una petición del usuario.

Por ejemplo, para nuestro agente de calendario, el flujo podría verse así:

• Inicio → Recibir mensaje del usuario
• Analizar intención → ¿Qué quiere hacer el usuario? (Nodo LLM)
• Decisión de ruta → ¿Buscar disponibilidad, agendar, cancelar o reprogramar?
• Ejecutar acción correspondiente → Sub-agente específico para cada caso
• Confirmar con usuario → Mostrar resultado

Paso 2: Identifica cada paso

Una vez identificado cada paso, ahora tenemos que decidir qué tipo de paso será. Podemos definir 4 tipos de pasos:

1. Paso LLM: Se usa cuando se necesita analizar, entender, generar texto o tomar una decisión de razonamiento. Ejemplo: Conocer la intención del usuario cuando dice «necesito un hueco mañana» → interpretar que quiere buscar disponibilidad.
2. Paso de Datos: Usado para extraer información de una fuente de datos externa. Ejemplo: Consultar el calendario mediante la API de Google Calendar para obtener las citas existentes del martes.
3. Paso de Acción: Usado para ejecutar una acción que modifica el estado del sistema. Ejemplo: Crear una cita en el calendario mediante una llamada POST a la API.
4. Paso de Solicitud de Usuario: Utilizado cuando se necesita la intervención humana. Ejemplo: «Encontré 3 horarios disponibles el martes: 10am, 2pm y 4pm. ¿Cuál preferís?»

Para nuestro agente de calendario, tendríamos algo así:

• «Agendame una reunión mañana a la 1» → Paso LLM para extraer: acción=agendar, fecha=mañana, hora=1pm
• Verificar disponibilidad → Paso de Datos consultando el calendario
• Si hay conflicto → Paso de Solicitud de Usuario «Ya tenés una reunión a la 1pm, ¿querés reprogramarla?»
• Si está libre → Paso de Acción crear la cita

Paso 3: Diseña el estado

El State (estado) es la memoria compartida entre los nodos de tu agente. Pensá en todo lo que tus nodos deberían saber para ejecutar sus tareas de manera armónica.

¿Qué se incluye en el state? Los datos que son necesarios en varios pasos. Por ejemplo:

• La intención del usuario (agendar, cancelar, buscar)
• Fecha y hora solicitadas
• Resultado de la consulta al calendario
• Mensajes del historial de la conversación
• Estado de confirmación (¿el usuario confirmó la acción?)

¿Qué no incluir? Lo contrario, datos que no necesitamos en todos los pasos y que podemos extraer en un momento específico. Por ejemplo:

• El token de autenticación de la API (se puede obtener cuando se necesite)
• Detalles internos de la respuesta de la API que no afectan decisiones futuras

Un ejemplo de estructura de estado para nuestro agente sería:

{
  messages: Message[],        // Historial de conversación
  intent: "agendar" | "cancelar" | "buscar" | "reprogramar",
  requestedDate: string,      // "2026-01-15"
  requestedTime: string,      // "13:00"
  availability: TimeSlot[],   // Horarios disponibles encontrados
  conflictingEvent: Event | null,  // Si hay conflicto
  needsConfirmation: boolean,
  actionCompleted: boolean
}

Paso 4: Crea los nodos (Funciones)

Creá las funciones para cada uno de tus nodos, usando el patrón de diseño que mejor se adecúe a tu solución. Cada función recibe el estado actual y devuelve una actualización del estado.

Por ejemplo, el nodo que analiza la intención del usuario:

async function analyzeIntent(state: AgentState): Promise<Partial<AgentState>> {
  const userMessage = state.messages[state.messages.length - 1];
  
  // Llamada al LLM para extraer la intención
  const response = await llm.invoke([
    { role: "system", content: "Extrae la intención del usuario: agendar, cancelar, buscar o reprogramar" },
    { role: "user", content: userMessage.content }
  ]);
  
  // Parsear la respuesta
  const { intent, date, time } = parseIntentResponse(response);
  
  return {
    intent,
    requestedDate: date,
    requestedTime: time
  };
}

Y el nodo que consulta disponibilidad:

async function checkAvailability(state: AgentState): Promise<Partial<AgentState>> {
  // Consultar el calendario externo
  const events = await calendarAPI.getEvents(state.requestedDate);
  
  // Verificar si el horario solicitado está ocupado
  const conflict = events.find(e => e.time === state.requestedTime);
  
  if (conflict) {
    return {
      conflictingEvent: conflict,
      needsConfirmation: true
    };
  }
  
  return {
    availability: [{ date: state.requestedDate, time: state.requestedTime }],
    conflictingEvent: null
  };
}

Paso 5: Une todo

Ahora conectás todos tus nodos usando el API de LangGraph. Definís las conexiones entre nodos y las condiciones para cada transición:

import { StateGraph } from "@langchain/langgraph";

// Crear el grafo
const workflow = new StateGraph({
  channels: agentStateSchema
});

// Agregar nodos
workflow.addNode("analyzeIntent", analyzeIntent);
workflow.addNode("checkAvailability", checkAvailability);
workflow.addNode("createAppointment", createAppointment);
workflow.addNode("askConfirmation", askConfirmation);

// Definir las conexiones
workflow.addEdge("__start__", "analyzeIntent");
workflow.addEdge("analyzeIntent", "checkAvailability");

// Agregar lógica condicional
workflow.addConditionalEdges(
  "checkAvailability",
  (state) => {
    if (state.conflictingEvent) {
      return "askConfirmation";
    }
    return "createAppointment";
  }
);

workflow.addEdge("createAppointment", "__end__");
workflow.addEdge("askConfirmation", "__end__");

// Compilar el grafo
const app = workflow.compile();

Paso 6: Prueba y refina

Finalmente, probá tu agente con diferentes escenarios y refiná el comportamiento. LangGraph te permite inspeccionar el estado en cada paso, lo que facilita el debugging:

// Ejecutar el agente
const result = await app.invoke({
  messages: [{ role: "user", content: "Agendame una reunión mañana a la 1" }]
});

console.log("Estado final:", result);

// Usar LangSmith para ver el trace completo
// Podés visualizar cada nodo ejecutado, su entrada y salida

Algunos tips para probar:

• Probá casos simples primero: «Tengo libre el martes?»
• Luego probá casos con conflictos: «Agendame algo cuando ya tengo una cita»
• Probá casos ambiguos: «Necesito reunirme la semana que viene» (sin especificar día ni hora)
• Usá LangSmith para visualizar el flujo completo y detectar dónde el agente se confunde

Con este enfoque paso a paso, podés construir agentes de IA complejos y robustos que resuelvan problemas reales. LangGraph te da el control total sobre la lógica, mientras te abstrae de la complejidad de manejar el estado y las transiciones entre pasos.

Conceptos claves

Estado (State)

La memoria compartida entre todos los nodos del agente. Contiene toda la información necesaria para que los diferentes pasos del flujo puedan ejecutarse de manera coordinada. Se actualiza conforme el agente avanza por los diferentes nodos.

Nodo (Node)

Una función individual que realiza una tarea específica dentro del flujo del agente. Cada nodo recibe el estado actual, ejecuta su lógica particular, y devuelve una actualización del estado. Los nodos pueden ser de tipo LLM, de datos, de acción o de solicitud al usuario.

Arista (Edge)

Una conexión entre dos nodos que define el flujo de ejecución. Las aristas pueden ser simples (conexión directa) o condicionales (la ruta depende de una condición evaluada en tiempo de ejecución).

Grafo (Graph)

La estructura completa del agente, compuesta por todos los nodos y aristas que definen el flujo de ejecución. LangGraph utiliza esta representación para orquestar la ejecución del agente.

Sub-agente

Un agente completo que funciona como un nodo dentro de otro agente más grande. Permite modularizar lógica compleja dividiendo el problema en sub-problemas más manejables, cada uno con su propio flujo de nodos.

LLM (Large Language Model)

Modelo de lenguaje grande utilizado para tareas que requieren comprensión, razonamiento o generación de texto. En el contexto de agentes, se usa típicamente para analizar intenciones, extraer información o tomar decisiones basadas en lenguaje natural.

Nodo LLM

Un nodo que utiliza un modelo de lenguaje para procesar información. Se usa cuando se necesita analizar, entender, generar texto o tomar decisiones de razonamiento sobre el input del usuario.

Nodo de Datos

Un nodo especializado en consultar información de fuentes externas (APIs, bases de datos, servicios). No modifica datos, solo los recupera y los añade al estado.

Nodo de Acción

Un nodo que ejecuta operaciones que modifican el estado del sistema externo (crear, actualizar, eliminar recursos). Por ejemplo, crear una cita en un calendario o enviar un email.

Nodo de Solicitud de Usuario

Un nodo que requiere intervención humana. Detiene el flujo automático del agente y espera input adicional del usuario antes de continuar con el siguiente paso.

Arista Condicional (Conditional Edge)

Una conexión entre nodos que evalúa una condición basada en el estado actual para determinar qué nodo debe ejecutarse a continuación. Permite crear flujos dinámicos que se adaptan según el contexto.

Compilación (Compile)

El proceso de convertir la definición del grafo (nodos y aristas) en una aplicación ejecutable. Una vez compilado, el grafo puede ser invocado para procesar requests.

Invocación (Invoke)

La acción de ejecutar el agente compilado con un estado inicial. El agente procesará el input siguiendo el flujo definido hasta llegar a un nodo final.

LangSmith

Herramienta de observabilidad y debugging para aplicaciones con LangChain y LangGraph. Permite visualizar el trace completo de ejecución, ver el estado en cada paso, y detectar problemas en el flujo del agente.

Intención (Intent)

La acción o propósito que el usuario quiere realizar, extraída de su mensaje. Por ejemplo: agendar, cancelar, buscar, reprogramar. Identificar correctamente la intención es crucial para dirigir el flujo del agente.

Historial de Conversación (Message History)

El registro de todos los mensajes intercambiados entre el usuario y el agente. Almacenado en el estado, permite al agente mantener contexto de conversaciones multi-turno.

StateGraph

La clase principal de LangGraph para crear agentes basados en grafos con estado. Permite definir la estructura del estado, agregar nodos, conectarlos con aristas, y compilar el grafo resultante.

Channels

Los campos que componen el esquema del estado en LangGraph. Cada channel representa una propiedad específica del estado que puede ser leída y actualizada por los nodos.

Reducer

Una función opcional que controla cómo se combinan múltiples actualizaciones a un mismo campo del estado. Útil cuando varios nodos pueden modificar la misma propiedad y necesitas definir la lógica de merge.

¿Quien soy yo?

Te cuento quien soy en la siguiente entrada Por qué inicié mi blog personal sobre tecnología y emprendimiento

La entrada Construyendo Agentes de IA con LangChain y LangGraph: Conceptos se publicó primero en Jorge Castrillo.

Estas notificaciones aparecen en el dispositivo, lo cual es sumamente util para mantener una comunicación cercana con el usuario y puede mejorar la retención y seguimiento.

Componentes necesarios para a utilizar

1. service-worker:
   Un service worker es un script que corre de manera independiente en tu web.
2. Browser APIs:
   Es la herramienta que nos va a ayudar a integrar las funciones de Notification API y Permission API para habilitar las notificaciones push.
3. VAPID Keys (Voluntary Application Server Identification):
   Consiste en una llave pública y otra privada que son usadas para firmar y verificar la identidad del remitente.

Suscripción de service worker

La suscripción de un service worker consiste en registrar el navegador del usuario para recibir notificaciones push. Este proceso genera un endpoint único para cada usuario, permitiendo que el servidor envía los mensajes a un destino concreto.

¿Cómo funciona?

1. Se registra el service worker utilizando navigator.serviceWorker.register()
2. Proceso de suscripción
   • Se solicita el permiso del usuario con Notification.requestPermission().
   • Si es permitido se realiza las suscripción push con registration.pushManager.subscribe()
   • Lo anterior devuelve un Objeto PushSubscription que contiene el endpoint único del navegador y las llaver de encriptación.
3. Guardar Objeto PushSubscription, está información es la que vas a usar para enviar los mensaje push a tus usuarios

Lo que necesitas

• Framework Nextjs npm create next-app@latest push-notifications --yes
• Instala web push npm i -web-push
• Instala los typos web-dev npm i --save-dev @types/web-push
• VAPID Keys

Genera VAPID Keys

Para generar la llave pública y privada que usará tu web app para push messages puedes usar la siguientes alternativas

• Opción 1: Instala el paquete web-push globalmente npm install -g web-push y luego web-push generate-vapid-keys
• Opición 2: Ve a https://vapidkeys.com/ ingresa tu email y te llegará un mail con las llaves

Luego copia y pega las llave en tus variables de entorno (.env)

NEXT_PUBLIC_VAPID_PUBLIC_KEY=llave_publica
VAPID_PRIVATE_KEY=llave_privada

Estructura del proyecto

Te comparto el repositorio en git para que puedas analizarlo y adaptarlo a tu solución aquí

Paso a paso

1. Agrega soporte para PWA. Crea el archivo manifest.ts en la carpeta app.

import type { MetadataRoute } from 'next'
 
export default function manifest(): MetadataRoute.Manifest {
  return {
    name: 'Notificaciones Push',
    short_name: 'push-notifications',
    description: 'Notificaciones Push by Jorge Castrillo',
    start_url: '/',
    display: 'standalone',
    background_color: '#ffffff',
    theme_color: '#000000',
    icons: [
      {
        src: '/icon-192x192.png',
        sizes: '192x192',
        type: 'image/png',
      },
      {
        src: '/icon-512x512.png',
        sizes: '512x512',
        type: 'image/png',
      },
    ],
  }
}

Cambia el nombre, la descripción y el nombre corto a los de tu app. Tambien te comparto una herramienta muy útil para generar todos los tamaños para tus favicon https://realfavicongenerator.net/

2. Crear los Server Actions

Crea el archivo actions.ts en la carpeta app. Para este ejemplo particular usaremos server actions de nextjs. Tendremos unicamente 3 funciones.

• subscribeUser: Acá es donde debes almacenar el objeto de suscripción que contiene el endpoint qye utilizar web-push y las key para enviar los mensajes push
• unsubscribeUser: Eliminar la suscripción de tu sistema de almacenamiento
• sendNotification: Función para enviar las notificaciones. En este ejemplo esta función recibe 2 parámetros (mensaje y suscripción). Cuando apliques a tu proyecto, lo ideal es que la suscripción la obtengas desde tu sistema de almacenamiento, de momento la optenemos del navegador.

Importamos webpush, lo inicializamos con las variables de entorno y lo usamos para enviar notificaciones desde la función sendNotification

'use server'
 
import webpush from 'web-push'
import type { PushSubscription } from 'web-push'

type SerializedSubscription = {
  endpoint: string
  keys: {
    p256dh: string
    auth: string
  } | null
}

type PushMessage = {
    title: string
    body: string
    url: string
}
 
webpush.setVapidDetails(
  'mailto:castrillodev@gmail.com',
  process.env.NEXT_PUBLIC_VAPID_PUBLIC_KEY!,
  process.env.VAPID_PRIVATE_KEY!
)
 
let subscription: SerializedSubscription | null = null
 
export async function subscribeUser(sub: SerializedSubscription) {
  subscription = sub
  // En un entorno de producción, se almacenaría la suscripción en una base de datos
  // Por ejemplo: await db.subscriptions.create({ data: sub })
  return { success: true }
}
 
export async function unsubscribeUser() {
  subscription = null
  // En un entorno de producción, se eliminaría la suscripción de la base de datos
  // Por ejemplo: await db.subscriptions.delete({ where: { ... } })
  return { success: true }
}
 
export async function sendNotification(message: PushMessage, sub: SerializedSubscription) {
  if (!sub || !sub.keys) {
    throw new Error('No hay suscripción disponible')
  }
 
  // Convertir el objeto serializado al formato que espera web-push
  const pushSubscription: PushSubscription = {
    endpoint: sub.endpoint,
    keys: {
      p256dh: sub.keys.p256dh,
      auth: sub.keys.auth,
    },
  }

  try {
    await webpush.sendNotification(
      pushSubscription,
      JSON.stringify({
        title: message.title,
        body: message.body,
        icon: '/icon.png',
        url: message.url,
      })
    )
    return { success: true }
  } catch (error) {
    console.error('Error al enviar la notificación:', error)
    return { success: false, error: 'Error al enviar la notificación' }
  }
}

3. Crear el service worker

Creas el archivo sw.js en la carpeta public. Habilitamos 2 listeners, uno para el evento push y el otro para notificationClick. En Cada evento podemos obtener los datos de la notificación.

self.addEventListener('push', function (event) {
    if (event.data) {
        const data = event.data.json()
        const options = {
            body: data.body,
            icon: data.icon || '/icon.png',
            badge: '/badge.png',
            vibrate: [100, 50, 100],
            data: {
                dateOfArrival: Date.now(),
                primaryKey: '2',
            },
        }
        event.waitUntil(self.registration.showNotification(data.title, options))
    }
})

self.addEventListener('notificationclick', function (event) {
    console.log('Notificación clicada.')
    event.notification.close()

    // Los datos están en event.notification.data, no en event.data
    const data = event.notification.data
    const url = data?.url || 'https://jorgecastrillo.blog'
    event.waitUntil(clients.openWindow(url))
})

5. Componente de Notificaciones

Una vez que tenemos los actions y el service worker ya podemos crear nuestro componente de pruebas para notificaciones push. Crea el archivo push.tsx en app

El componente tiene las siguiente funciones

1. Revisa si el navegador soporta notificaciones push.
2. Obtenemos la suscripción push del navegador
3. Luego tenemos tres acciones
   • subscribeToPush acá cargamos el service worker del navegador, luego registramos la suscripción push usando la llave pública y luego asignamos el valor al estado subscription
   • unsubscribeFromPush Elimina la suscripción con await subscription?.unsubscribe()
   • sendTestNotification Envía el mensaje
4. Imprimimos la interfaz y listo

'use client'

import { useState, useEffect } from 'react'
import { subscribeUser, unsubscribeUser, sendNotification } from './actions'

const VAPID_PUBLIC_KEY = process.env.NEXT_PUBLIC_VAPID_PUBLIC_KEY!

function urlBase64ToUint8Array(base64String: string) {
    const padding = '='.repeat((4 - (base64String.length % 4)) % 4)
    const base64 = (base64String + padding).replace(/-/g, '+').replace(/_/g, '/')

    const rawData = window.atob(base64)
    const outputArray = new Uint8Array(rawData.length)

    for (let i = 0; i < rawData.length; ++i) {
        outputArray[i] = rawData.charCodeAt(i)
    }
    return outputArray
}

export default function PushNotificationManager() {
    const [isSupported, setIsSupported] = useState(false)
    const [subscription, setSubscription] = useState<PushSubscription | null>(
        null
    )
    const [title, setTitle] = useState('')
    const [message, setMessage] = useState('')
    const [url, setUrl] = useState('')

    useEffect(() => {
        if ('serviceWorker' in navigator && 'PushManager' in window) {
            setIsSupported(true)
            registerServiceWorker()
        }
    }, [])

    async function registerServiceWorker() {
        const registration = await navigator.serviceWorker.register('/sw.js', {
            scope: '/',
            updateViaCache: 'none',
        })
        const sub = await registration.pushManager.getSubscription()
        setSubscription(sub)
    }

    async function subscribeToPush() {
        if (!VAPID_PUBLIC_KEY) {
            alert('Error: La clave VAPID pública no está configurada. Por favor, configura NEXT_PUBLIC_VAPID_PUBLIC_KEY en tu archivo .env.local')
            return
        }
        const registration = await navigator.serviceWorker.ready
        const sub = await registration.pushManager.subscribe({
            userVisibleOnly: true,
            applicationServerKey: urlBase64ToUint8Array(VAPID_PUBLIC_KEY),
        })
        setSubscription(sub)
        const serializedSub = JSON.parse(JSON.stringify(sub))
        await subscribeUser(serializedSub)
    }

    async function unsubscribeFromPush() {
        await subscription?.unsubscribe()
        setSubscription(null)
        await unsubscribeUser()
    }

    async function sendTestNotification() {
        if (subscription) {
            console.log('Enviando notificación de prueba:', message)
            const serializedSub = JSON.parse(JSON.stringify(subscription))
            await sendNotification({ title, body: message, url }, serializedSub)
            setMessage('')
        }
    }

    if (!isSupported) {
        return <p>Push notifications are not supported in this browser.</p>
    }

    return (
        <div className="flex flex-col gap-4 items-start justify-start w-full">
            {subscription ? (
                <>
                    <p>Estas suscrito a notificaciones push.</p>
                    <button
                        onClick={unsubscribeFromPush}
                        className='bg-red-500 text-white py-2 px-4 rounded-md cursor-pointer'
                    >
                        Cancelar suscripción
                    </button>
                    <div className='border-t border-gray-300 w-full'></div>
                    <h2 className='text-lg font-bold'>Enviar notificación de prueba</h2>
                    <input
                        type="text"
                        placeholder="Ingrese el titulo de la notificación"
                        className='w-full max-w-xs p-2 rounded-md border border-gray-300 bg-white placeholder:text-gray-500 text-black'
                        value={title}
                        onChange={(e: React.ChangeEvent<HTMLInputElement>) => setTitle(e.target.value)}
                    />
                    <textarea
                        placeholder="Ingrese el mensaje de la notificación"
                        className='w-full p-2 rounded-md border border-gray-300 bg-white placeholder:text-gray-500 text-black'
                        value={message}
                        onChange={(e: React.ChangeEvent<HTMLTextAreaElement>) => setMessage(e.target.value)}
                    >{message}</textarea>
                    <input
                        type="text"
                        placeholder="Ingrese la url de la notificación"
                        className='w-full p-2 rounded-md border border-gray-300 bg-white placeholder:text-gray-500 text-black'
                        value={url}
                        onChange={(e: React.ChangeEvent<HTMLInputElement>) => setUrl(e.target.value)}
                    />
                    <button
                        onClick={sendTestNotification}
                        className='bg-blue-500 text-white py-2 px-4 rounded-md cursor-pointer'
                    >
                        Enviar prueba
                    </button>
                </>
            ) : (
                <>
                    <p>No estás suscrito a notificaciones push.</p>
                    <button
                        onClick={subscribeToPush}
                        className='bg-blue-500 text-white py-2 px-4 rounded-md cursor-pointer'
                    >
                        Suscribirme
                    </button>
                </>
            )}
        </div>
    )
}

Conclusión

Con esta guia tienes un punto de partida completo para poder implementar notificaciones push en tu proyecto de nextjs. Si prestas atención y entiendes bien el flujo te darás cuenta que esta misma lógica la podrías implementar en otros frameworks de programación.

Espero les sea de mucha utilidad, al menos para mi, lo es y lo estaré consultando cada que lo necesite.

Gracias Jorge del pasado.

La entrada Nextjs + Notificaciones Push se publicó primero en Jorge Castrillo.

En este artículo te compartiré exactamente qué hacer antes de arrancar a desarrollar una web o app y cómo la etapa de planning en el desarrollo de software te ahorra dolores de cabeza y, sobre todo, dinero.

Al final te cuento una historia de terror real de dos emprendedoras que perdieron miles de dólares por contratar desarrollo sin planificar.

¿Por Qué Planificar el Desarrollo de Software es Crítico para tu Negocio?

Me gustaría hablarte desde la experiencia. Desde que arranqué en el fascinante mundo del emprendimiento tecnológico, he visto un patrón repetitivo en negocios emergentes y establecidos.

Lo más común es que las empresas empiecen a pensar en tener una página web o, cuando están más avanzadas, implementar soluciones tipo SAAS o crear una aplicación a la medida porque nada en el mercado se adapta a su operación.

Las 5 Preguntas Fundamentales Antes de Desarrollar Software

Antes de contratar un SAAS, crear una página web o desarrollar una solución de software a la medida, debes hacerte estas preguntas:

1. ¿Cuáles son los cuellos de botella en los procesos de mi negocio?
2. ¿Cuáles son mis dolores de cabeza operativos?
3. ¿Qué procesos son repetitivos en mi negocio?
4. ¿Esta solución me ayudará a ahorrar tiempo y dinero?
5. ¿Cuál es el objetivo real de implementar esta solución de software?

Por Qué Estas Preguntas Son Cruciales

Tu negocio, para funcionar y ser rentable, necesita activos. Si una solución de software se va a volver un pasivo, algo no cuadra ¿cierto?

Esa inversión en software que vas a realizar tiene que ser con sentido y propósito. Tiene que volverse un activo importante en tu organización, ya sea para ahorrar dinero o generar más ingresos.

Mi Postura sobre las Webs Informativas

Siempre he sido crítico de las páginas web puramente informativas, aunque me ha tocado hacerlas porque el cliente lo quiere a pesar de mi asesoría.

Seamos claros: una web informativa se vuelve un pasivo con el tiempo. Una página web tiene que tener un propósito, una intención clara. ¿De qué nos sirve crear una página web informativa que no convierte nada? Lo veo como simple ego empresarial.

¿Qué es el Planning en Desarrollo de Software?

Cuando ya te has respondido las preguntas anteriores y estás decidido a implementar una solución de software en tu negocio, ya sea una página web o una solución a la medida, es momento de hacer un documento de planning.

Definición de Planning de Software

El Planning en la etapa previa al desarrollo no es más que un documento que define las reglas de juego a la hora de crear la solución.

En esta etapa, el profesional experto en tecnologías debe acompañar y escuchar al cliente y stakeholders para crear un documento de planificación ajustado y certero.

Qué Incluye un Planning de Software Profesional

• Reuniones y Análisis de Procesos – Reuniones virtuales o presenciales, identificar y entender los procesos, mapear dolores y cuellos de botella
• Establecimiento de KPIs – Métricas de éxito del proyecto e indicadores de rendimiento
• Casos de Uso – Descripción detallada de escenarios y flujos de usuario
• Definición de Requerimientos – Funcionales y no funcionales, priorización de features
• Diseño de Arquitectura – Estructura de datos y patrón de diseño recomendado
• Stack de Tecnología – Análisis de tecnologías apropiadas y selección de herramientas
• Prototipo Visual – Wireframes en baja fidelidad y validación de flujos
• Tiempos de Desarrollo – Cronograma realista y fases del proyecto
• Costos del Proyecto – Presupuesto detallado y ROI esperado

La Analogía de la Construcción

Es como hacer una casa: antes de arrancar a construirla, necesitas los planos estructurales, eléctricos, mecánicos, civiles, topográficos y ambientales.

Bonus: Si tienes un proyecto de construcción de vivienda o comercial, te invito a ver la página que hice para Daniel Chavarría, un crack que lleva tu proyecto de construcción de 0 a 100: danielconstruye.cr

¿Cuánto Cuesta el Planning y Por Qué Vale la Pena?

El planning tiene un costo, sí, no es gratuito. El precio va a depender del tamaño de la solución, pero te aseguro que te evitará dolores de cabeza a futuro.

Beneficios Comprobados del Planning

• ✓ Reducción de riesgo del proyecto hasta en un 70%
• ✓ Claridad técnica total antes de invertir miles
• ✓ Decisiones correctas de arquitectura desde el inicio
• ✓ Evitar rehacer el sistema 2-3 veces
• ✓ Base para cotizar correctamente el desarrollo
• ✓ Ahorro significativo de dinero a largo plazo

Conclusión: No Cometas Este Error Común

Recomendación personal: Antes de pagar por desarrollar una solución de software, planifica por favor.

He hablado con dueños de negocio que por no planificar han tirado a la basura miles de dólares. Una reunión de 45 minutos NO es suficiente para que un profesional de TI entienda y genere una solución de software que realmente resuelva.

Planifica bien tu próxima solución de software, desde una web «informativa» hasta una aplicación a la medida.

Historia de Terror: Cuando No Planificar Cuesta Miles de Dólares

Hace 3 años conocí a 2 emprendedoras que querían crear una web de tiquetera para eventos. Spoiler alert: no planificaron.

Primer Intento Fallido

Se acercaron a mí porque la solución que les habían comenzado a desarrollar no funcionaba. El proceso de compra era deficiente, las notificaciones por email no llegaban correctamente y los tiquetes se perdían en el sistema.

Lamentablemente no les pude ayudar en esa ocasión porque no tenía tiempo disponible. Estaba desarrollando otra solución que me consumía mucho tiempo.

Segundo Intento: Mismo Error, Peor Resultado

El año pasado (2025) volvieron a contactarme con el mismo problema, pero con una solución de software distinta y programador distinto. Un completo desastre.

De recordarlo me llevo las manos a la cabeza e inhalo profundamente por la congoja.

El Desastre Técnico

Otra vez, el «experto» que se supone tenía que guiarlas y darles un servicio de calidad NO PLANIFICÓ.

Se puso a montar un WordPress con 300 plugins tratando de resolver el problema y terminó creando un frankenstein técnico, y no te imagines el frankenstein que interpreta Jacob Elordi, de haber sido ese, no estaría tan mal.

Importante: No digo que WordPress sea malo, al contrario, es buenísimo. Pero sin planificación de desarrollo puede terminar no siendo la herramienta ideal para la solución. El stack de tecnología se define en la etapa de planning.

El Resultado Final

Las emprendedoras perdieron miles de dólares y el profesional en TI quedó con una reputación fatal en la comunidad, siendo eventualmente expuesto.

Puras pérdidas por no planificar.

Preguntas Frecuentes sobre Planning de Software

¿Cuánto tiempo toma un planning de software?
Depende de la complejidad, pero típicamente entre 2-4 semanas para proyectos medianos.

¿Es obligatorio hacer planning para cualquier desarrollo?
No es obligatorio legalmente, pero es altamente recomendado para cualquier inversión seria en software.

¿Puedo hacer el planning yo mismo?
Puedes intentarlo, pero un profesional experimentado identificará aspectos técnicos y riesgos que podrías pasar por alto.

¿Quien soy yo?
Te cuento quien soy en la siguiente entrada Por qué inicié mi blog personal sobre tecnología y emprendimiento

La entrada Planning en Desarrollo de Software: Evita Perder Miles de Dólares se publicó primero en Jorge Castrillo.

Sin embargo, hoy me levanté con una decisión clara: voy a hacer el blog de una vez por todas. Sin preocuparme demasiado por el diseño o el nombre. Simplemente ponerlo a funcionar, escribir la primera entrada y ver qué sucede.

Y aquí estoy. Un lunes 5 de enero de 2026, dando forma a esta primera publicación y dando el primer paso en este proyecto personal.

Debo dar un agradecimiento indirecto a Enzo Cavalie de Startupeable y a su último podcast junto a Iván Landaso titulado “El Apalancamiento Sin Permiso: Cómo Escalar sin Capital ni Conexiones”. Ese episodio fue el empujón final que necesitaba para iniciar este blog.

Objetivos del blog

• Hablar sobre inteligencia artificial y tecnología
• Documentar guías prácticas y aprendizajes
• Compartir experiencias reales de emprendimiento

Me presento

Mi nombre es Jorge Castrillo. Mi historia es una más entre muchas, nada extraordinaria. Soy de una zona rural de Costa Rica llamada La Cruz, en la provincia de Guanacaste. De niño soñaba con ser futbolista profesional (spoiler: no lo logré).

Con el tiempo descubrí que tenía habilidades para el canto. A los 14 años hice un amigo que tocaba guitarra y comenzó a enseñarme. Fue amor a primera vista (La Guitarra). Practicaba todos los días hasta que logré tocar mi primera canción (no la recuerdo, pero nunca olvidaré esa sensación). Eso me dio el valor para pedirle una guitarra a mis padres, y una de mis tías, Evelyn (gracias infinitas), me regaló una. Hasta el día de hoy, la conservo.

Pasó el tiempo y, como buen muchacho de pueblo, tocaba guitarra y cantaba con bastante confianza. Luego llegó el momento de tomar decisiones importantes. A los 17 años entendí que no sería futbolista. Entonces decidí que quería ser músico y, al mismo tiempo, salir de mi pueblo y conocer el mundo.

Me inscribí en la Universidad Nacional de Costa Rica para estudiar Música con énfasis en guitarra acústica. No logré entrar. No sabía leer música; había aprendido de forma empírica, con amigos y tardes interminables viendo atardeceres.

Ese golpe fue duro, pero tenía un plan B: Ingeniería en Sistemas de Información. En ese momento no tenía muy claro qué aprendería, solo sabía que era computación, algo que siempre me había apasionado.

Comencé a estudiar y, aunque pasaron muchas cosas interesantes que quizás cuente en futuras entradas, no terminé la carrera. Llegué hasta tercer año y con ese conocimiento empecé a trabajar en el área de TI.

Hoy llevo más de 15 años trabajando en tecnología, enfocado principalmente en desarrollo web. He fundado cuatro empresas; una no funcionó y tres siguen activas. A continuación te cuento brevemente sobre ellas.

Train-In Formación Virtual

Empresa fundada junto a tres amigos, enfocada en el desarrollo de soluciones educativas en línea. Entre los servicios que ofrecemos están:

• Desarrollo de e-learning a la medida
• Animaciones 2D y 3D
• Hosting especializado en Moodle
• Instalación y personalización de plataformas Moodle

Slothgeek Soluciones Web

En el año 2020 comencé a profundizar en WordPress y decidí fundar junto con Caro (mi esposa) Slothgeek, una agencia digital enfocada en ayudar a pequeñas y medianas empresas a establecer su presencia en línea.

• Desarrollo de sitios web WordPress a la medida
• Desarrollo de tiendas en línea con WordPress y Shopify
• Desarrollo de plugins
• Desarrollo de plantillas personalizadas
• Soporte y mantenimiento WordPress
• WordPress Headless
• Desarrollo de aplicaciones web a la medida

iSmart Comply

Startup que fundé junto a cinco socios más. Era una aplicación que conectaba abogados con clientes, ofrecía cursos en línea, plantillas legales y servicios profesionales. Fracasó. En retrospectiva, no resolvía un problema real ni atacaba un dolor claro. Aun así, fue una experiencia invaluable.

Agente Officia

A finales de 2024 inicié este proyecto a partir de una necesidad personal: agendar una cita con mi barbero sin tener que esperar horas una respuesta por WhatsApp.

Investigando descubrí que este problema es común en negocios que trabajan con citas. Programé un MVP, se lo presenté a mi barbero y comenzó a usarlo. La aplicación ofrece reservas en línea, gestión de agendas y un asistente virtual conectado a WhatsApp que responde y agenda citas automáticamente.

Hoy son decenas de negocios y cientos de personas que ya no sufren tener que agendar una cita.

Habilidades técnicas

• CMS: WordPress, Strapi
• LMS: Moodle, LearnDash
• Frontend: React, Next.js, Astro, HTML5, CSS3, Tailwind CSS
• Backend: Node.js, Express, WordPress, Strapi 5, Supabase, LangGraph
• Bases de datos: MongoDB, PostgreSQL, MySQL
• Automatización: WhatsApp API, integración con OpenAI

Habilidades blandas

• Liderazgo y organización
• Comunicación efectiva
• Compromiso y constancia

Aterricemos

Al escribir todo esto me doy cuenta de algo: sé más de lo que pensaba. Durante años di por sentado todo lo que aprendí porque siempre lo guardé para mí. Hoy quiero compartirlo con el mundo. Tal vez a alguien le sirva. Tal vez este blog sea útil para alguien más que esté empezando.

La entrada Por qué inicié mi blog personal sobre tecnología y emprendimiento se publicó primero en Jorge Castrillo.