LangChain tutorial en español: primeros pasos

El ecosistema LangChain incluye: langchain-core (abstracciones base), langchain-community (integraciones con 300+ servicios), LangGraph (framework de agentes), y LangSmith (observabilidad y evaluación).

LangGraph vs LangChain: qué usar en 2026

La confusión más común: LangChain es un ecosistema, y LangGraph es parte de ese ecosistema. Aquí la distinción clara:

LangChain (langchain-core + langchain-community):

• Abstracciones para prompts, modelos, parsers y retrievers
• El operador | (pipe) para encadenar componentes
• Ideal para: chains lineales, RAG básico, transformaciones de datos
• Cuándo usarlo: tareas secuenciales sin decisiones condicionales

LangGraph:

• Framework de agentes basado en grafos de estados
• Nodos (funciones), aristas (transiciones), estado persistente
• Ideal para: agentes con herramientas, flujos condicionales, multi-agente
• Cuándo usarlo: cualquier cosa que necesite tomar decisiones o hacer loops

Regla práctica: si tu flujo es lineal (input → procesamiento → output), usa LangChain chains. Si tu flujo tiene decisiones, loops o herramientas, usa LangGraph. En 2026, para cualquier agente nuevo, LangGraph es la elección por defecto.

Instalación y setup

# Crear entorno virtual
python -m venv langchain-env
source langchain-env/bin/activate # Linux/Mac
# langchain-env\Scripts\activate # Windows

# Instalar LangChain con proveedor de LLM
pip install langchain langchain-anthropic

# O con OpenAI
pip install langchain langchain-openai

# Para agentes (LangGraph)
pip install langgraph

# Para RAG
pip install langchain-community chromadb

# Configurar API key
export ANTHROPIC_API_KEY="tu-api-key"
# O: export OPENAI_API_KEY="tu-api-key"

Setup recomendado para el tutorial:

# Instalar todo de una vez
pip install langchain langchain-anthropic langchain-openai \
    langchain-community langgraph chromadb \
    langchain-text-splitters

# Verificar instalación
python -c "import langchain; print(langchain.__version__)"
# Debería mostrar 0.3.x o superior

Sobre API keys: necesitas al menos una API key de un proveedor LLM. Anthropic (Claude) cuesta 0 para el primer millón de tokens con el plan gratuito de la API. OpenAI da 5 USD de créditos gratuitos para nuevas cuentas. Para zero cost, usa Ollama (modelos locales) con pip install langchain-ollama.

Conceptos clave

Models: wrappers para LLMs. ChatAnthropic, ChatOpenAI, ChatOllama (local). Todos comparten la misma interfaz: .invoke(), .stream(), .batch().

Prompts: templates reutilizables con variables. ChatPromptTemplate te permite definir system message, human message y variables que se rellenan en runtime.

Chains: composición de pasos. Prompt → LLM → Parser. Se encadenan con el operador | (pipe). Es la unidad básica de LangChain.

Tools: funciones que un agente puede llamar. Definidas con @tool decorator. El LLM decide cuándo y cómo usarlas.

Retrievers: interfaces para buscar documentos. Conectan con bases de datos vectoriales, búsquedas SQL, APIs de búsqueda.

State (LangGraph): un diccionario tipado que persiste entre nodos del grafo. Cada nodo lee del estado, procesa, y escribe de vuelta al estado. Es la memoria del agente.

Tu primer chain

from langchain_anthropic import ChatAnthropic
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser

# 1. Definir el modelo
model = ChatAnthropic(model="claude-sonnet-4-20250514")

# 2. Definir el prompt template
prompt = ChatPromptTemplate.from_messages([
 ("system", "Eres un experto en {dominio}. Responde en español, "
 "de forma concisa y práctica."),
 ("human", "{pregunta}")
])

# 3. Crear el chain: prompt → modelo → parser
chain = prompt | model | StrOutputParser()

# 4. Ejecutar
respuesta = chain.invoke({
 "dominio": "marketing digital",
 "pregunta": "¿Cuáles son las 3 métricas más importantes "
 "para un ecommerce?"
})

print(respuesta)

Este es el patrón básico: defines un prompt con variables, lo conectas a un modelo y a un parser de output. El operador | encadena los pasos. Para entender mejor los prompts, revisa nuestra guía de prompts profesionales.

Chain con streaming (para interfaces de usuario):

# Streaming: muestra tokens en tiempo real
for chunk in chain.stream({
    "dominio": "Python",
    "pregunta": "Explica list comprehensions con 3 ejemplos"
}):
    print(chunk, end="", flush=True)

Chain con output estructurado:

from langchain_core.output_parsers import JsonOutputParser
from pydantic import BaseModel, Field

class Análisis(BaseModel):
    resumen: str = Field(description="Resumen en una frase")
    sentimiento: str = Field(description="positivo, negativo o neutro")
    temas: list[str] = Field(description="Temas principales")

parser = JsonOutputParser(pydantic_object=Análisis)

prompt = ChatPromptTemplate.from_messages([
    ("system", "Analiza el siguiente texto. {format_instructions}"),
    ("human", "{texto}")
])

chain = prompt | model | parser

resultado = chain.invoke({
    "texto": "El producto es excelente pero el envío tardó 3 semanas.",
    "format_instructions": parser.get_format_instructions()
})
# resultado = {"resumen": "...", "sentimiento": "...", "temas": [...]}

RAG con LangChain

LangChain es la forma más popular de implementar RAG con código. El flujo completo:

from langchain_anthropic import ChatAnthropic
from langchain_community.document_loaders import PyPDFLoader
from langchain_text_splitters import RecursiveCharacterTextSplitter
from langchain_community.vectorstores import Chroma
from langchain_openai import OpenAIEmbeddings
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.runnables import RunnablePassthrough

# 1. Cargar documentos
loader = PyPDFLoader("mi-documento.pdf")
docs = loader.load()

# 2. Dividir en chunks
splitter = RecursiveCharacterTextSplitter(
 chunk_size=1000, chunk_overlap=200
)
chunks = splitter.split_documents(docs)

# 3. Crear vector store
vectorstore = Chroma.from_documents(
 chunks, OpenAIEmbeddings()
)
retriever = vectorstore.as_retriever(search_kwargs={"k": 4})

# 4. Definir prompt RAG
prompt = ChatPromptTemplate.from_messages([
 ("system", "Responde basándote SOLO en el contexto. "
 "Si no sabes, di que no tienes información.\n\n"
 "Contexto:\n{context}"),
 ("human", "{question}")
])

# 5. Crear chain RAG
model = ChatAnthropic(model="claude-sonnet-4-20250514")

chain = (
 {"context": retriever, "question": RunnablePassthrough()}
 | prompt
 | model
)

# 6. Consultar
respuesta = chain.invoke(
 "¿Qué dice el documento sobre plazos de entrega?"
)
print(respuesta.content)

Agentes con LangGraph

LangGraph es el framework de agentes de LangChain. Modela agentes como grafos de estados: cada nodo es un paso, las aristas son transiciones condicionales.

from langchain_anthropic import ChatAnthropic
from langchain_core.tools import tool
from langgraph.prebuilt import create_react_agent

# 1. Definir tools
@tool
def buscar_precio(producto: str) -> str:
 """Busca el precio de un producto en la base de datos."""
 # Aquí iría la lógica real (SQL, API, etc.)
 precios = {"laptop": "899 EUR", "monitor": "349 EUR"}
 return precios.get(producto, "Producto no encontrado")

@tool
def calcular_descuento(precio: str, porcentaje: int) -> str:
 """Calcula el precio con descuento."""
 precio_num = float(precio.replace(" EUR", ""))
 descuento = precio_num * (1 - porcentaje / 100)
 return f"{descuento:.2f} EUR"

# 2. Crear agente
model = ChatAnthropic(model="claude-sonnet-4-20250514")
agent = create_react_agent(
 model, [buscar_precio, calcular_descuento]
)

# 3. Ejecutar
result = agent.invoke({
 "messages": [("human",
 "¿Cuánto cuesta un monitor con 15% de descuento?")]
})
print(result["messages"][-1].content)

El agente decide automáticamente: primero llama a buscar_precio("monitor"), luego a calcular_descuento("349 EUR", 15), y finalmente genera la respuesta.

Agente personalizado con LangGraph (control total):

from langgraph.graph import StateGraph, END
from typing import TypedDict, Annotated
from langgraph.graph.message import add_messages

# Definir el estado del agente
class AgentState(TypedDict):
    messages: Annotated[list, add_messages]
    paso_actual: str
    intentos: int

# Definir nodos
def analizar(state: AgentState):
    """Nodo que analiza la pregunta."""
    # Lógica de análisis...
    return {"paso_actual": "buscar", "intentos": 0}

def buscar(state: AgentState):
    """Nodo que busca información."""
    # Lógica de búsqueda...
    return {"paso_actual": "responder"}

def responder(state: AgentState):
    """Nodo que genera la respuesta final."""
    # Lógica de generación...
    return {"paso_actual": "fin"}

# Construir el grafo
graph = StateGraph(AgentState)
graph.add_node("analizar", analizar)
graph.add_node("buscar", buscar)
graph.add_node("responder", responder)

graph.set_entry_point("analizar")
graph.add_edge("analizar", "buscar")
graph.add_edge("buscar", "responder")
graph.add_edge("responder", END)

agent = graph.compile()

Patrones de memoria

Los agentes necesitan memoria para mantener contexto entre interacciones. LangGraph ofrece varios patrones:

Memoria de conversación (corto plazo):

from langgraph.checkpoint.memory import MemorySaver

# El checkpointer guarda el estado entre invocaciones
memory = MemorySaver()
agent = create_react_agent(model, tools, checkpointer=memory)

# Cada thread_id mantiene su propia conversación
config = {"configurable": {"thread_id": "usuario-123"}}

# Primera interacción
agent.invoke({"messages": [("human", "Me llamo María")]}, config)

# Segunda interacción (recuerda el nombre)
agent.invoke({"messages": [("human", "Cómo me llamo?")]}, config)
# → "Te llamas María"

Memoria a largo plazo (entre sesiones):

Para persistir memoria entre sesiones, usa un checkpointer con base de datos:

# PostgreSQL checkpointer (producción)
from langgraph.checkpoint.postgres import PostgresSaver

DB_URI = "postgresql://user:pass@localhost/mydb"
memory = PostgresSaver.from_conn_string(DB_URI)

# SQLite checkpointer (desarrollo)
from langgraph.checkpoint.sqlite import SqliteSaver
memory = SqliteSaver.from_conn_string("checkpoints.db")

Memoria semántica (RAG sobre conversaciones pasadas):

Para agentes que necesitan recordar hechos de conversaciones antiguas, combina el checkpointer con una vector store donde indexas resúmenes de conversaciones pasadas. Es el patrón más avanzado y el que usamos en producción.

Deployment en producción

LangChain/LangGraph en desarrollo es fácil. En producción necesitas considerar:

LangServe (API REST rápida):

# server.py
from fastapi import FastAPI
from langserve import add_routes

app = FastAPI()

# Exponer tu chain como API
add_routes(app, chain, path="/análisis")

# Ejecutar: uvicorn server:app --host 0.0.0.0 --port 8000
# Endpoint: POST /análisis/invoke
# Playground: GET /análisis/playground

LangSmith (observabilidad):

# Activar tracing (una línea)
export LANGCHAIN_TRACING_V2=true
export LANGCHAIN_API_KEY="tu-langsmith-key"

# Ahora todas las ejecuciones se loggean automáticamente
# Dashboard: smith.langchain.com
# Ver: latencia, tokens, costes, errores, trazas completas

Consideraciones de producción:

• Rate limiting: Los proveedores de LLM tienen límites. Implementa retry con backoff exponencial.
• Caching: Usa LangChain cache para respuestas idénticas. Reduce costes y latencia.
• Fallbacks: Configura modelos de fallback. Si Claude falla, cae a GPT-4o. Si GPT-4o falla, cae a un modelo local.
• Timeouts: Siempre configura timeouts. Un LLM que no responde puede bloquear tu aplicación indefinidamente.
• Streaming: Para interfaces de usuario, siempre usa streaming. La experiencia de esperar 30 segundos sin feedback es inaceptable.

Alternativas a LangChain

LangChain no es la única opción. Según tu caso de uso, estas alternativas pueden ser mejores:

CrewAI

Framework multi-agente con roles definidos. Cada agente tiene un rol, objetivo y backstory. Ideal para simular equipos de trabajo donde diferentes "personas" colaboran. Más simple que LangGraph para multi-agente básico, pero menos flexible para flujos complejos.

# CrewAI: equipo de agentes con roles
from crewai import Agent, Task, Crew

investigador = Agent(
    role="Investigador",
    goal="Encontrar datos relevantes",
    backstory="Eres un analista experto en búsqueda de información"
)

escritor = Agent(
    role="Escritor",
    goal="Redactar un informe conciso",
    backstory="Eres un redactor técnico experimentado"
)

AutoGen (Microsoft)

Framework para conversaciones entre agentes. Los agentes hablan entre sí para resolver problemas. Bueno para pair programming simulado y revisiones de código. Más experimental que LangGraph, pero con una comunidad activa.

Anthropic SDK directo

Si solo usas Claude y no necesitas abstracciones, el SDK de Anthropic es más ligero y directo. Sin capas intermedias, máximo control, mínima dependencia. Para aplicaciones simples o cuando LangChain añade complejidad innecesaria.

# Anthropic SDK directo (sin LangChain)
import anthropic

client = anthropic.Anthropic()
message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Explica recursión"}]
)
print(message.content[0].text)

LlamaIndex

Especializado en RAG. Si tu único caso de uso es buscar y responder sobre documentos, LlamaIndex es más simple y directo que LangChain para ese fin. Menos flexible para otros casos de uso, pero mejor documentado para RAG específicamente.

Cuándo usar qué:

• Chain lineal simple → LangChain core
• Agente con herramientas → LangGraph
• RAG puro → LlamaIndex o LangChain
• Multi-agente con roles → CrewAI
• Máximo control, sin abstracciones → SDK directo
• Producción enterprise → LangGraph + LangSmith

Siguiente paso

Instala LangChain, ejecuta el primer chain, y luego prueba con RAG sobre un PDF tuyo. Cuando entiendas el flujo, pasa a agentes. La documentación oficial (python.langchain.com) es excelente.

Si prefieres empezar sin código, Claude Code es un agente listo para usar que no requiere programar LangChain.

Preguntas frecuentes

LangChain cambia mucho entre versiones?

Sí, históricamente LangChain ha tenido breaking changes frecuentes. Desde la versión 0.2 (2024) se estabilizó con langchain-core como base estable. La recomendación: fija versiones en requirements.txt y actualiza con cautela.

Cuánto cuesta usar LangChain en producción?

LangChain es gratis. El coste viene del LLM. Un agente con Claude Sonnet que procesa 100 consultas/día con prompts de 2000 tokens cuesta aproximadamente 1-3 USD/día. Con modelos locales via Ollama, el coste es 0 (solo electricidad).

Puedo usar LangChain con modelos locales?

Sí. langchain-ollama conecta con cualquier modelo de Ollama. langchain-community incluye integraciones con vLLM, llama.cpp, y otros runtimes locales. El código es idéntico, solo cambias el import del modelo.