Módulo 11: Deep Agents

Introducción: El Nivel Más Alto de Abstracción

Siguiente →

Descripción

Has llegado al Módulo 11. A lo largo de esta guía construiste todo manualmente: tools desde cero (M2), agentes con loops ReAct (M3), grafos con nodos y edges (M5-M7), persistencia con checkpointers (M8), interrupts para supervisión humana (M9), y sistemas multi-agente con supervisors, handoffs y subagents (M10). Entiendes las tripas de cada pieza porque las armaste tú.

Ahora vas a ver qué pasa cuando alguien empaqueta todo eso en un framework que lo hace por ti.

Deep Agents es la capa más alta de abstracción en el ecosistema LangChain. Es un harness que incluye planning automático (write_todos), un virtual filesystem para leer y escribir archivos, subagent spawning para delegar tareas on-demand, y long-term memory con backends intercambiables — todo out-of-the-box, sin que tengas que construir la infraestructura.

El valor de este módulo no es aprender "la forma correcta." Deep Agents no es mejor que LangGraph — es más conveniente para ciertos casos de uso y menos configurable para otros. El valor es que ahora tienes criterio para elegir: ya sabes qué hace cada pieza por dentro, así que puedes evaluar cuándo te conviene dejar que el framework lo haga por ti y cuándo necesitas control manual.

¿Dónde estamos en la guía?

Este es el Módulo 11 de la guía LangChain & LangGraph: From Chains to Agents. Es el primer módulo del Bloque 4 (Producción).

Bloque 1: LangChain Core (Módulos 1-4)           ✅ Completado
Bloque 2: LangGraph Fundamentals (Módulos 5-7)   ✅ Completado
Bloque 3: LangGraph Avanzado (Módulos 8-10)      ✅ Completado
Bloque 4: Producción (Módulos 11-12)              ← ESTÁS AQUÍ (Módulo 11)

Tu progreso:

Bloque 1 — LangChain Core                   ✅ Completado
    │
    │  Módulo 1: Modelos y Proveedores       ✅
    │  Módulo 2: Tools y Tool Calling        ✅
    │  Módulo 3: Agents (create_agent)       ✅
    │  Módulo 4: Middleware y Customización   ✅
    │
    ▼
Bloque 2 — LangGraph Fundamentals           ✅ Completado
    │
    │  Módulo 5: Introducción a LangGraph    ✅
    │  Módulo 6: Functional API              ✅
    │  Módulo 7: Flujos Avanzados            ✅
    │
    ▼
Bloque 3 — LangGraph Avanzado               ✅ Completado
    │
    │  Módulo 8: Memoria y Persistencia      ✅
    │  Módulo 9: Human-in-the-Loop           ✅
    │  Módulo 10: Multi-Agent Systems        ✅
    │
    ▼
Bloque 4 — Producción
    │
    │  Módulo 11: Deep Agents                ← ESTÁS AQUÍ
    │  Módulo 12: LangSmith y Producción     🔒 Siguiente

El Bloque 3 te dio las capacidades avanzadas: persistencia, supervisión humana, y multi-agente. El Bloque 4 te lleva a producción: primero con la capa batteries-included (este módulo), luego con observabilidad y deployment (M12).

Los tres niveles de abstracción

Todo lo que aprendiste en esta guía se organiza en tres niveles. Entender estos niveles es el framework de decisión más importante que te llevas de este módulo.

Nivel 1: create_agent — simple, 80% de los casos

from langchain.agents import create_agent

agent = create_agent(
    "openai:gpt-4.1-mini",
    tools=[web_search, calculator],
    prompt="Eres un asistente de investigación.",
)

result = agent.invoke({"messages": [{"role": "user", "content": "¿Cuánto es 2+2?"}]})
  • ✅ Una función, listo
  • ✅ Tool calling automático con loop ReAct
  • ✅ Suficiente para chatbots, asistentes simples, Q&A
  • ❌ Sin control sobre el flujo de decisiones
  • ❌ Sin persistencia built-in (necesitas agregar checkpointer)
  • ❌ Sin multi-agente

Nivel 2: LangGraph — custom workflows, control total

from langgraph.graph import StateGraph, START, END

builder = StateGraph(ResearchState)
builder.add_node("search", search_node)
builder.add_node("analyze", analyze_node)
builder.add_node("report", report_node)
builder.add_edge(START, "search")
builder.add_conditional_edges("search", route_by_quality)
builder.add_edge("analyze", "report")
builder.add_edge("report", END)

graph = builder.compile(checkpointer=MemorySaver())
  • ✅ Control total sobre nodos, edges, y flujo
  • ✅ Persistencia, HITL, multi-agente — todo configurable
  • ✅ Retry, branching, error handling a tu medida
  • ❌ Más código: tú diseñas cada decisión
  • ❌ Planning, filesystem, subagent spawning — los construyes manualmente

Nivel 3: Deep Agents — autónomo, batteries-included

from deep_agents import create_deep_agent

agent = create_deep_agent(
    "openai:gpt-4.1",
    tools=[web_search],
    name="Research Assistant",
    instructions="Investiga temas complejos. Descompone la tarea en pasos, "
                 "escribe los resultados en archivos, y delega subtareas "
                 "a subagentes especializados cuando sea necesario.",
)

result = agent.run("Investiga el estado de AI safety en 2025 y genera un reporte")
  • ✅ Planning automático: el agente descompone tareas con write_todos
  • ✅ Virtual filesystem: escribe y lee archivos sin llenar el context window
  • ✅ Subagent spawning: crea agentes especializados on-demand
  • ✅ Long-term memory con backends intercambiables
  • ❌ Menos control: el framework decide gran parte del flujo
  • ❌ Más opaco: no ves cada decisión del grafo
  • ❌ Overhead para tareas simples

La metáfora

Nivel 1 — create_agent:    Conducir un auto automático
                            Simple, rápido, funciona para el 80% de los viajes

Nivel 2 — LangGraph:       Conducir un auto manual
                            Más control, mejor para situaciones específicas,
                            requiere más habilidad

Nivel 3 — Deep Agents:     Subirse a un taxi autónomo
                            Le dices el destino, él decide la ruta, los desvíos,
                            y las paradas. Tú llegas. Pero no controlas el volante.

La pregunta no es "¿cuál es mejor?" — es "¿cuál necesito para esta tarea?"

El puente: de manual a batteries-included

Lo que construiste manualmente

En los módulos 6-10, tu Research Assistant creció pieza por pieza:

M6:  Research Agent v1 — búsqueda básica con Functional API
M7:  Research Agent v2 — retry, branching, error handling
M8:  Research Agent v3 — checkpointing, crash recovery, memoria
M9:  Research Agent v4 — HITL, approvals antes de acciones costosas
M10: Research Agent v5 — multi-agente con supervisor y subagents

Cada versión agregó una capacidad que tuviste que diseñar e implementar: el retry con backoff lo escribiste tú, la persistencia la configuraste tú, los subagents los orquestaste tú. Aproximadamente 150+ líneas de código para el sistema completo.

Lo que Deep Agents provee out-of-the-box

Deep Agents toma esas mismas capacidades y las empaqueta:

CapacidadLo que construisteLo que Deep Agents provee
PlanningDiseñaste el workflow en M6-M10: qué nodo va después de cuál, qué condiciones evaluarwrite_todos: el agente descompone la tarea solo, trackea progreso, re-planifica
PersistenciaConfiguraste checkpointers en M8: MemorySaver, PostgresSaver, thread_idVirtual filesystem: el agente escribe outputs a archivos, lee solo lo que necesita
Multi-agenteImplementaste supervisor, handoffs, subagents en M10Subagent spawning: el agente decide cuándo y qué delegar en runtime
MemoriaInMemoryStore, namespaces, cross-session en M8Long-term memory con backends pluggable (filesystem, LangGraph Store)

La conexión es directa:

  • write_todos abstrae el planning que hiciste en M6-M10 — en lugar de diseñar el flujo de trabajo, el agente lo diseña él mismo
  • El virtual filesystem abstrae la persistencia de M8 — en lugar de configurar checkpointers, el agente escribe a archivos
  • El subagent spawning abstrae el multi-agente de M10 — en lugar de diseñar quién hace qué en build time, el agente decide en runtime

Esa es la razón por la que este módulo viene después de 10 módulos de construcción manual. Sin haber construido cada pieza, no podrías evaluar qué ganas y qué pierdes cuando el framework lo hace por ti.

Cuándo usar Deep Agents

Casos ideales

  • ✅ Tareas de larga duración: investigación que toma minutos, generación de reportes multi-fuente, análisis complejos que requieren múltiples pasos
  • ✅ Investigación autónoma: el agente necesita planear, buscar, analizar, y sintetizar sin intervención constante
  • ✅ Generación de código: proyectos donde el agente escribe múltiples archivos, los prueba, y los corrige
  • ✅ Análisis complejos: comparativas, due diligence, market research donde hay múltiples dimensiones que explorar
  • ✅ Prototipos rápidos: quieres un agente autónomo funcional sin construir toda la infraestructura

Cuándo NO usar Deep Agents

  • ❌ Q&A simple: preguntas-respuestas no necesitan planning ni filesystem — usa create_agent
  • ❌ Control fino necesario: si necesitas decidir exactamente qué nodo ejecutar en cada paso — usa LangGraph
  • ❌ Workflows custom: flujos con reglas de negocio específicas, approvals en puntos exactos — usa LangGraph
  • ❌ Latencia sensible: Deep Agents tiene overhead de planning; si necesitas respuestas en <2s — usa create_agent
  • ❌ Presupuesto limitado: planning y subagent spawning implican más llamadas al LLM = más costo

Árbol de decisión

¿Tu tarea es simple (Q&A, búsqueda directa)?
  └─ SÍ → create_agent
  └─ NO ↓

¿Necesitas control total sobre el flujo de decisiones?
  └─ SÍ → LangGraph (StateGraph o Functional API)
  └─ NO ↓

¿La tarea es autónoma, de larga duración, multi-paso?
  └─ SÍ → Deep Agents
  └─ NO → LangGraph (más flexible sin overhead)

Qué incluye Deep Agents

1. Planning con write_todos

El agente recibe una tarea compleja — "Investiga AI safety y genera un reporte" — y la descompone en pasos manejables:

1. [pending]     Definir alcance de la investigación
2. [pending]     Buscar papers académicos recientes
3. [pending]     Buscar reportes de la industria
4. [pending]     Analizar y sintetizar hallazgos
5. [pending]     Generar reporte final

Conforme avanza, actualiza el progreso. Si descubre algo inesperado, re-planifica: agrega, elimina, o reordena pasos. Cápsula 02 lo cubre en detalle.

2. Virtual Filesystem

En lugar de meter toda la investigación en el context window (caro, limitado a 128K tokens), el agente escribe outputs a archivos:

workspace/
├── research/
│   ├── papers.md          ← Resultados de búsqueda académica
│   └── industry_reports.md ← Reportes de la industria
├── analysis/
│   └── synthesis.md       ← Análisis cruzado
└── output/
    └── report.md          ← Reporte final

El context window se mantiene lean: el agente lee solo el archivo que necesita para el paso actual. Cápsula 03 lo cubre en detalle.

3. Subagent Spawning

El agente principal puede crear subagentes especializados on-demand:

Main Agent: "Necesito buscar papers sobre RAG"
  └─ spawn: paper_researcher("Find papers about RAG in 2025")
       └─ Ejecuta en contexto aislado
       └─ Retorna: "Encontré 5 papers relevantes..."

Main Agent: "Ahora necesito analizar estos papers"
  └─ spawn: analysis_agent("Compare these 5 papers and rank by relevance")
       └─ Ejecuta en contexto aislado
       └─ Retorna: "Ranking: 1) Paper X, 2) Paper Y..."

A diferencia del M10 donde tú diseñaste la estructura multi-agente, aquí el agente decide qué subagentes crear en runtime. Cápsula 04 lo cubre en detalle.

4. Long-term Memory

Backends intercambiables para persistir información entre sesiones:

  • Filesystem backend: archivos en disco, simple, sin dependencias externas
  • LangGraph Store backend: usa el sistema de Store de LangGraph para consistencia con el ecosistema
  • Composite backends: combina múltiples backends

Se cubre en cápsulas posteriores del módulo.

Mapa del módulo

#CápsulaQué aprenderásTipo
01Introducción (esta)Los tres niveles de abstracción, cuándo usar Deep Agents, setupIntro
02Planning con write_todosDescomponer tareas, trackear progreso, re-planificación dinámicaTécnica
03Virtual FilesystemContext offloading, leer/escribir archivos, organización de outputsTécnica
04Subagent Spawning y DelegaciónCrear subagentes on-demand, contexto aislado, límites y controlesTécnica
05Long-term MemoryBackends de memoria, filesystem vs LangGraph Store, compositeTécnica
06Deep Agents CLIAgentes autónomos desde la terminal, configuración, uso diarioTécnica
07Árbol de decisión: create_agent vs LangGraph vs Deep AgentsFramework de decisión completo, trade-offs, cuándo usar quéTécnica
08Proyecto: Research Assistant como Deep AgentReimplementar el Research Assistant, comparación side-by-sideProyecto

Flujo de aprendizaje

Empiezas con planning (cápsula 02) — la capacidad más fundamental: cómo el agente descompone tareas complejas. Luego aprendes el virtual filesystem (cápsula 03) — cómo el agente maneja información sin llenar el context window. Agregas subagent spawning (cápsula 04) — delegación autónoma de subtareas. Con esas tres piezas, entiendes el core de Deep Agents. Las cápsulas 05-06 agregan long-term memory y CLI. La cápsula 07 consolida todo en un árbol de decisión completo. Y la cápsula 08 integra todo en el proyecto final del módulo.

La progresión es: planning → filesystem → delegación → memoria → CLI → framework de decisión → proyecto.

Conexión con el proyecto

Research Assistant: de ~150 líneas a ~40 líneas

En el Módulo 10, tu Research Assistant tiene aproximadamente 150 líneas de código: definición de estado, nodos, edges, condicionales, checkpointer, tools, supervisors, subagents. Funciona, es robusto, y tienes control total.

En este módulo, lo reimplementas como Deep Agent:

from dotenv import load_dotenv
load_dotenv()

from deep_agents import create_deep_agent
from langchain_community.tools import TavilySearchResults

web_search = TavilySearchResults(max_results=5)

agent = create_deep_agent(
    "openai:gpt-4.1",
    tools=[web_search],
    name="Research Assistant",
    instructions=(
        "Eres un asistente de investigación. "
        "Para cada tema, descompone la investigación en pasos con write_todos. "
        "Escribe los hallazgos de cada fuente en archivos separados. "
        "Delega subtareas especializadas a subagentes cuando sea necesario. "
        "Genera un reporte final consolidado."
    ),
)

result = agent.run("Investiga el estado de AI agents en producción en 2025")

print(f"Archivos generados: {list(result.files.keys())}")
print(f"Todos completados: {sum(1 for t in result.todos if t['status'] == 'completed')}/{len(result.todos)}")
print(f"Subagentes usados: {len(result.subagents_spawned)}")
# Output esperado (varía según el modelo):
# Archivos generados: ['research/web_search.md', 'analysis/synthesis.md', 'output/report.md']
# Todos completados: 5/5
# Subagentes usados: 2

~40 líneas. El mismo resultado. Pero con un trade-off claro: perdiste el control sobre cada decisión. El agente decidió cómo descomponer la tarea, qué archivos crear, y cuándo delegar. Si eso está bien para tu caso de uso, Deep Agents ahorra tiempo. Si necesitas control, LangGraph es la opción.

El momento pedagógico más importante de este módulo es esa comparación side-by-side. Llegarás a él en la cápsula 08.

Conexión con el Módulo 12: LangSmith y Producción

Deep Agents genera muchas llamadas al LLM: planning, ejecución de cada paso, subagent spawning, filesystem operations. Sin observabilidad, no tienes visibilidad sobre qué está haciendo el agente, cuánto está costando, o por qué tomó una decisión.

El Módulo 12 agrega LangSmith a cualquiera de tus agentes — ya sea la versión LangGraph o la versión Deep Agents:

M11: Deep Agents (el agente hace más por ti)
  ↓
M12: LangSmith (ves todo lo que el agente hace)
  ↓
  Resultado: un agente autónomo que puedes observar, evaluar, y deployar

La combinación de Deep Agents + LangSmith es potente: el agente opera autónomamente mientras tú monitoreas costos, calidad, y comportamiento en producción.

Setup técnico

Prerequisitos

  • ✅ Módulo 10 completado — tienes un Research Assistant multi-agente funcional
  • ✅ Python 3.11+ instalado
  • ✅ Al menos una API key de un proveedor (OpenAI recomendado, GPT-4.1 para mejores resultados con planning)

Instalación

pip install deep-agents langchain-openai python-dotenv

Deep Agents instala LangGraph como dependencia transitiva. Si ya tienes LangGraph instalado, no hay conflicto.

Verifica la instalación:

import deep_agents
print(f"deep-agents version: {deep_agents.__version__}")
# Output esperado:
# deep-agents version: 0.2.x

Variables de entorno

Tu .env de módulos anteriores sigue funcionando:

# .env
OPENAI_API_KEY=sk-...

# Opcional: para búsqueda web en los ejercicios
TAVILY_API_KEY=tvly-...

Verificación rápida

from dotenv import load_dotenv
load_dotenv()

from deep_agents import create_deep_agent

agent = create_deep_agent(
    "openai:gpt-4.1-mini",
    tools=[],
    name="test-agent",
    instructions="Responde preguntas simples.",
)

result = agent.run("¿Cuál es la capital de Francia?")
print(result.output)
# Output esperado (varía según el modelo):
# La capital de Francia es París.

Si ves una respuesta coherente, el setup está listo.

Qué NO cubre este módulo

  • ❌ Construir tu propio framework de agentes — no estás recreando Deep Agents, estás usándolo. Si quieres construir algo similar, los módulos 5-10 te dieron las herramientas
  • ❌ RAG y vector stores — el virtual filesystem almacena outputs del agente, no knowledge bases indexadas
  • ❌ Fine-tuning de modelos — Deep Agents funciona con modelos de propósito general vía API
  • ❌ Deployment en la nube — cómo desplegar tu agente se cubre en el Módulo 12 con LangSmith

Evidencia de éxito

Al terminar este módulo, sabrás que tuviste éxito si:

  • ✅ Puedes crear un Deep Agent con planning, filesystem, y subagent spawning habilitados
  • ✅ Entiendes qué hace write_todos internamente: descomposición, tracking, re-planning
  • ✅ Puedes explicar por qué el virtual filesystem reduce costos: context offloading
  • ✅ Sabes cuándo el subagent spawning es útil y cuándo es overkill
  • ✅ Tienes un árbol de decisión claro: create_agent vs LangGraph vs Deep Agents
  • ✅ Reimplementaste tu Research Assistant como Deep Agent y puedes articular los trade-offs
  • ✅ Puedes usar Deep Agents CLI para ejecutar agentes desde la terminal

Test de autoevaluación

Si puedes responder estas preguntas, vas por buen camino:

  1. ¿Cuáles son los tres niveles de abstracción en el ecosistema LangChain y cuándo usarías cada uno?
  2. ¿Qué hace write_todos que va más allá de una simple lista de tareas?
  3. ¿Por qué el virtual filesystem reduce costos comparado con meter todo en el context window?
  4. ¿Cuál es la diferencia entre diseñar multi-agente en M10 y subagent spawning en Deep Agents?
  5. ¿Qué pierdes cuando usas Deep Agents en lugar de LangGraph?

Resumen

  • Estás en el Módulo 11, Bloque 4 (Producción). Construiste todo manualmente en los módulos 1-10: tools, grafos, persistencia, HITL, multi-agente. Ahora ves la capa batteries-included
  • El ecosistema tiene tres niveles de abstracción: create_agent (simple, 80% de casos), LangGraph (control total, custom workflows), y Deep Agents (autónomo, batteries-included). No hay "mejor" — hay "adecuado para tu caso"
  • Deep Agents incluye cuatro capacidades principales: planning con write_todos, virtual filesystem para context offloading, subagent spawning para delegación autónoma, y long-term memory con backends intercambiables
  • Las abstracciones de Deep Agents mapean directamente a lo que construiste: write_todos = planning de M6-M10, filesystem = persistencia de M8, subagent spawning = multi-agente de M10. Ahora que conoces las tripas, puedes apreciar cuánto hace el framework por ti
  • Cuándo usar Deep Agents: tareas autónomas de larga duración, investigación, generación de código, análisis complejos. Cuándo NO: Q&A simple, control fino necesario, latencia sensible
  • El proyecto del módulo es reimplementar el Research Assistant como Deep Agent: ~150 líneas → ~40 líneas, con trade-offs explícitos que podrás articular

Recursos adicionales

  1. Deep Agents — Documentation — Documentación oficial, API reference, y ejemplos
  2. LangChain — Agent Architectures — Visión general de las diferentes arquitecturas de agentes en el ecosistema
  3. LangGraph — Overview — Documentación de LangGraph para comparar con Deep Agents
  4. Building Autonomous Agents — LangChain Blog — Artículo sobre el diseño de agentes autónomos y cuándo usar cada nivel de abstracción
  5. Cognitive Architectures for Language Agents — Paper académico sobre arquitecturas cognitivas para agentes (planning, memory, tool use)
  6. The Landscape of Emerging AI Agent Architectures — LangChain — Panorama de arquitecturas de agentes y dónde encaja cada abstracción

Módulo 11 — LangChain & LangGraph: From Chains to Agents

Siguiente cápsula: Planning con write_todos — aprenderás cómo el agente descompone tareas complejas en pasos, trackea progreso, y re-planifica dinámicamente cuando los resultados cambian.

← AnteriorProyecto Evolutivo: Sistema Multi-Agente (v5)Siguiente →Planning con write_todos