Arquitectura DeepAgents: herramientas de planificación, subagentes y sistema de archivos

¿Por qué tu agente de IA se cae siempre en tareas complejas?

Le pides que investigue un tema técnico y, tras 20 pasos, la calidad empieza a bajar. Le encargas refactorizar un repositorio y, tras media hora de cambios, pierde funcionalidades que antes funcionaban. Le pides un informe largo y a mitad de camino repite lo mismo una y otra vez.

Yo caí en esa trampa. Usaba un agente tradicional para investigación profunda: quería que me ayudara a revisar las mejores prácticas de LangGraph. Al principio la salida era ordenada, pero tras más de treinta pasos empezó a «olvidar»: perdió material ya consultado, desordenó el marco de análisis y el informe final quedó incongruente y contradictorio.

Todas estas fallas tienen la misma raíz: los agentes tradicionales son «shallow». Solo reaccionan paso a paso, sin planificación, sin memoria y sin descomposición de subtareas. Es como pedirle a alguien un informe de 5000 palabras sin esquema: a mitad de camino se desvía.

Sin embargo, agentes como Claude Code, Deep Research y Manus completan tareas complejas: refactor de proyectos de miles de líneas, informes de investigación de decenas de páginas. ¿Qué hacen distinto?

La respuesta es la arquitectura Deep Agent. LangChain la empaquetó en la librería DeepAgents. Hoy desglosamos sus cuatro pilares: herramientas de planificación, subagentes, sistema de archivos y system prompts.

¿Por qué hacen falta los Deep Agents?

Primero un dato: en tareas de más de 10 pasos, la tasa de éxito de los agentes tradicionales cae más de la mitad.

No es una opinión. Los datos de Prompting Guide muestran que, cuando los pasos superan 10, la calidad de un Shallow Agent baja de forma clara. ¿Por qué? Porque no tiene «cerebro».

El diseño clásico es reactivo: recibe instrucción → llama herramientas → devuelve resultado. Cada paso es independiente, sin plan a largo plazo ni gestión de estado intermedio. Es como pedirle a alguien que limpie toda la casa sin orden ni registro de habitaciones ya hechas: puede dejar la cocina a medias, saltar al salón y olvidar que la cocina no terminó.

Tres escenarios típicos de colapso:

Investigación profunda. Pides investigar un tema, por ejemplo «mejores prácticas de LangGraph en producción». Busca, lee documentación y extrae información. Tras 20 pasos, lo ya consultado sale del context window y los nuevos resultados tapan el marco de análisis. El informe final no encaja.

Refactor de código. Pides refactorizar un proyecto de miles de líneas. Modifica un módulo y luego otro, pero olvida dependencias entre ellos. Al final, funcionalidades que antes corrían dejan de hacerlo.

Generación de contenido largo. Pides un artículo técnico de 5000 palabras. Hacia la palabra 2000 repite ideas anteriores o se desvía del tema.

El núcleo común es la pérdida de control del contexto.

Claude Code refactoriza proyectos enormes, Deep Research produce informes estructurados de decenas de páginas y Manus ejecuta tareas multi-paso complejas. No es magia: comparten una estructura, la arquitectura Deep Agent.

Un Deep Agent da «cerebro» al agente: planifica, divide tareas, gestiona memoria y revisa progreso. LangChain lo empaqueta en DeepAgents. Veamos el diseño concreto.

Los cuatro pilares de DeepAgents

La filosofía es clara: partir tareas complejas en unidades manejables, cada una con responsabilidad definida.

Los cuatro pilares cooperan: Planning Tools gestiona plan y seguimiento; Sub-agents aportan especialización y aislamiento de contexto; File System resuelve almacenamiento de memoria; System Prompts fijan límites de comportamiento. Como una orquesta: director (Planning), secciones (Sub-agents), partituras (File System) y reglas de interpretación (System Prompts).

Planning Tools: un «cerebro» para el agente

El núcleo de Planning Tools es todo_write.

Su funcionamiento es curioso: en esencia es un no-op (operación vacía). No ejecuta tareas reales; solo crea y actualiza listas de tareas. Esas listas viven en el context window como working memory, de modo que el agente «ve» plan y progreso durante toda la ejecución.

Railway - Plataforma de despliegue moderna, sin ops complejas, en producción en minutos

Empezar ahora →Anuncio

Ejemplo: le pides una investigación técnica. Primero usa todo_write para crear un plan:

- [ ] Buscar documentación oficial de LangGraph
- [ ] Leer el diseño de la máquina de estados de LangGraph
- [ ] Extraer casos de mejores prácticas
- [ ] Resumir patrones de diseño centrales
- [ ] Generar informe estructurado

Al completar cada tarea, actualiza la lista y cambia [ ] por [x]. Así, sin importar cuántos pasos lleve, el agente ve qué está hecho, qué falta y qué está en curso.

Resuelve un problema clave: coherencia del objetivo a largo plazo.

En el paso 20, un agente tradicional puede haber olvidado el objetivo del paso 1. La todo list del Deep Agent es como un recordatorio en la nevera: «¿qué estabas haciendo?».

"La planning tool de Claude Code y Manus sigue el mismo principio: usar el context window como working memory para que el agente no se pierda"

Sub-agents: especialización e aislamiento de contexto

Los subagentes son el segundo pilar.

La lógica: un orquestador principal planifica y reparte trabajo; subagentes especializados ejecutan tareas concretas. Cada subagente tiene su propio context window y, al terminar, solo devuelve el resultado final al orquestador.

Cuatro ventajas clave:

Context Preservation. El context window del orquestador no se contamina con pasos intermedios de los subagentes. Un agente tradicional mete en contexto búsquedas, HTML y extracciones. Un subagente devuelve algo limpio: «encontré esta información clave». El orquestador mantiene el contexto ligero.

Specialized Expertise. Cada subagente se centra en un dominio. research_subagent busca y extrae; writer_subagent organiza contenido; coder_subagent analiza código. La especialización mejora la calidad en cada área.

Reusability. Un mismo subagente puede usarse desde varios orquestadores. research_subagent sirve para investigación, redacción o análisis. Escríbelo una vez, reutilízalo.

Fine-Grained Permissions. Los subagentes pueden tener permisos distintos: solo lectura, solo escritura, acceso a red. Control fino que reduce riesgo.

"Recomiendan la arquitectura Orchestrator-Sub-agent, también Task Decomposition Pattern: dividir tareas complejas y delegar cada subtarea a una unidad especializada"

¿Cómo se implementa? DeepAgents ofrece una API sencilla:

from deepagents import create_deep_agent, create_subagent

# 定义子代理
research_subagent = create_subagent(
    name="research",
    tools=[internet_search, read_url],
    description="专门负责信息检索和提取"
)

writer_subagent = create_subagent(
    name="writer",
    tools=[write_file],
    description="专门负责内容组织和输出"
)

# 创建主 Agent
agent = create_deep_agent(
    subagents=[research_subagent, writer_subagent],
    tools=[todo_write, read_file, write_file]
)

Al invocar subagentes, DeepAgents gestiona el cambio de contexto y el paso de resultados.

File System: superar el límite del context window

Aquí está la solución central a la memoria en tareas largas.

El context window tiene tope. Claude ronda 200K tokens; GPT-4 unos 128K. Para tareas cortas basta; para miles de líneas de código o decenas de documentos, el espacio se agota rápido.

File System Backend usa una idea inteligente: referencias a archivos en lugar de cargar todo.

El agente no mete todo en contexto; guarda resultados intermedios en el sistema de archivos y usa read_file bajo demanda. Como en una investigación: no memorizas todas las referencias, las archivas y las abres cuando hace falta.

DeepAgents soporta tres backends:

StateBackend. Almacenamiento en memoria, ideal para pruebas y tareas cortas. Estado e intermedios viven en RAM y desaparecen al cerrar la sesión. Rápido, no persistente.

FilesystemBackend. Sistema de archivos local, para producción y persistencia. Los intermedios se escriben en disco y pueden leerse en la siguiente ejecución. Persistente, depende del almacenamiento local.

StoreBackend. Almacenamiento en la nube, para despliegue empresarial y auditoría. Estado en base de datos remota, con versionado y logs. Fiable, configuración más compleja.

La elección depende del escenario: pruebas rápidas → StateBackend; producción → FilesystemBackend; empresa con auditoría → StoreBackend.

La tabla de FlowHunt sobre estrategias de gestión de contexto lo resume bien:

DeepAgents usa por defecto modo Hybrid: información clave en contexto, volúmenes grandes en archivos.

System Prompts: el pilar subestimado

System Prompts es el más ignorado de los cuatro.

Muchos piensan que un system prompt son dos frases: «eres un asistente útil». En Deep Agent, los system prompts son documentos de ingeniería de cientos o miles de líneas.

El system prompt de Claude Code tiene cientos de líneas: reglas de herramientas, flujo de archivos, estilo de código. El de Deep Research supera el millar: metodología de investigación, extracción, plantillas de salida.

¿Por qué tanto detalle?

En tareas largas aparecen casos límite que instrucciones breves no cubren. Un system prompt detallado:

Alibaba Cloud - Opción preferida para desarrolladores, 15 % de descuento exclusivo en Lighthouse

Obtener 15% dto. →Anuncio

Define límites de comportamiento. Cuándo usar todo_write, cuándo delegar a un subagente, cuándo responder directamente. Reglas explícitas para decidir bien.

Normaliza llamadas a herramientas. Uso de cada tool, formato de parámetros y tratamiento de respuestas. Por ejemplo, si read_file recibe ruta o ID y devuelve contenido crudo o resumen.

Fija formatos de salida. Informes en Markdown, refactors en diff, generación con plantillas concretas.

La Middleware Architecture de DeepAgents inyecta system prompts automáticamente. No hace falta escribir miles de líneas a mano; el framework los genera según configuración. Pero conviene entender su papel: son la «constitución» del agente.

Con los cuatro pilares cubiertos, pasemos al código práctico.

Código práctico con DeepAgents

Ejemplo completo: un agente de investigación técnica.

from deepagents import create_deep_agent, create_subagent
from langchain_community.tools import TavilyInternetSearch

# 1. 定义工具
search_tool = TavilyInternetSearch(
    name="internet_search",
    description="搜索互联网获取信息"
)

# 2. 定义子代理
research_subagent = create_subagent(
    name="research",
    tools=[search_tool],
    system_prompt="你是信息检索专家。\
                   你的任务是搜索和提取关键信息。\
                   只返回结构化的研究结果，不要包含中间步骤。",
    description="负责信息检索的子代理"
)

writer_subagent = create_subagent(
    name="writer",
    tools=[],  # writer 不需要外部工具
    system_prompt="你是内容组织专家。\
                   你的任务是整理研究结果，输出结构化报告。\
                   使用 Markdown 格式，包含清晰的章节结构。",
    description="负责内容输出的子代理"
)

# 3. 创建 Deep Agent
agent = create_deep_agent(
    subagents=[research_subagent, writer_subagent],
    tools=[todo_write, read_file, write_file],
    backend="filesystem"  # 使用文件系统存储
)

# 4. 执行任务
result = agent.invoke(
    "调研 LangGraph 的最佳实践，\
     输出一份结构化的研究报告"
)

Flujo de ejecución:

Paso 1: Plan. El agente llama todo_write y crea la lista.

todo_write([
    "搜索 LangGraph 官方文档",
    "阅读核心架构设计",
    "提取最佳实践案例",
    "总结设计模式",
    "输出结构化报告"
])

Paso 2: Delegate. Invoca research_subagent para la búsqueda.

call_subagent("research", "搜索 LangGraph 最佳实践相关文档")

research_subagent usa internet_search, obtiene resultados, extrae lo clave y devuelve un resultado estructurado al orquestador. El context window del orquestador solo recibe un resumen como «aquí hay 5 mejores prácticas clave», no el HTML crudo de todas las búsquedas.

Paso 3: Update. Actualiza la todo list.

todo_write([
    "[x] 搜索 LangGraph 官方文档",
    "[x] 阅读核心架构设计",
    "[ ] 提取最佳实践案例",
    ...
])

Paso 4: Continuar. Llama writer_subagent y write_file para el informe final.

call_subagent("writer", "整理研究结果，输出报告")
write_file("langgraph_best_practices.md", report_content)

Un log típico:

[Step 1] todo_write: 创建 5 个任务项
[Step 2] call_subagent(research): 开始信息检索
[Step 3] internet_search: 搜索 "LangGraph best practices"
[Step 4] read_url: 读取 3 篇官方文档
[Step 5] subagent_complete: research 返回结构化结果
[Step 6] todo_write: 更新进度，完成 2 项
[Step 7] call_subagent(writer): 开始内容组织
[Step 8] subagent_complete: writer 返回 Markdown 报告
[Step 9] write_file: 输出报告到文件
[Step 10] todo_write: 全部任务完成

Durante todo el flujo, el context window del orquestador se mantiene limpio: lista de tareas y resúmenes de subagentes, sin ruido de pasos intermedios.

Esa es la fuerza del Deep Agent: flujo estructurado, gestión de contexto y especialización.

Comparación con otros frameworks de agentes

DeepAgents no es la única opción. También están LangGraph, AutoGen, CrewAI y SmolAgents, cada uno con enfoque distinto.

Tabla resumen:

Diferencias clave:

DeepAgents vs LangGraph. DeepAgents es capa superior sobre LangGraph, centrada en Deep Agent. Encapsula Planning Tools, File System Backend y gestión de subagentes. LangGraph es más bajo nivel: máquinas de estado y flujos personalizables, pero memoria y planificación las implementas tú.

En resumen: Deep Agent rápido → DeepAgents; personalización profunda → LangGraph.

DeepAgents vs AutoGen. AutoGen (Microsoft) orquesta diálogo multiagente y pipelines. Los agentes conversan, debaten y negocian. DeepAgents prioriza descomposición y ejecución; AutoGen, colaboración y comunicación.

En resumen: equipos que debaten → AutoGen; descomposición técnica → DeepAgents.

DeepAgents vs CrewAI. CrewAI enfatiza role-play: investigador, editor, programador con personalidad. Similar a subagentes de DeepAgents, pero CrewAI pone más peso en roles e interacción; DeepAgents, en división y aislamiento de tareas.

En resumen: simular un equipo → CrewAI; descomposición técnica → DeepAgents.

DeepAgents vs SmolAgents. SmolAgents (Hugging Face) es ligero y code-first: el agente escribe Python en lugar de solo llamar tools. Bueno para prototipos, poco para tareas largas y complejas.

En resumen: probar una idea simple → SmolAgents; tareas largas y complejas → DeepAgents.

"La elección depende del escenario. DeepAgents para razonamiento complejo, LangGraph para producción, AutoGen y CrewAI para colaboración multiagente, SmolAgents para validar ideas rápido. No hay framework universal, solo el adecuado"

Despliegue en producción y buenas prácticas

Para llevar DeepAgents a producción, ten en cuenta lo siguiente.

KiloClaw - OpenClaw gestionado para empresas: orquestación de agentes IA y enrutamiento inteligente

Empezar →Anuncio

Estrategia de elección de Backend

StateBackend: pruebas y tareas cortas. Ventaja: velocidad, todo en memoria sin latencia de I/O. Desventaja: no persiste; al reiniciar se pierde el estado. Ideal para tests unitarios, validación rápida.

FilesystemBackend: producción y persistencia. Ventaja: datos en disco, recuperables tras reinicio. Desventaja: costo de I/O. Para despliegue real, tareas largas y estado que deba sobrevivir.

StoreBackend: empresa y auditoría. Ventaja: base de datos en la nube, versionado y logs. Desventaja: configuración de conexión y permisos. Para compliance y trazabilidad.

Ejemplo de configuración:

from deepagents import create_deep_agent, FilesystemBackend

agent = create_deep_agent(
    subagents=[research_subagent, writer_subagent],
    backend=FilesystemBackend(
        base_path="/var/agent-state",  # 存储路径
        max_file_size=10 * 1024 * 1024,  # 单文件最大 10MB
        cleanup_after_days=30  # 30 天后清理旧文件
    )
)

Diseño de granularidad de subagentes

No dividas en exceso.

Algunos parten una investigación en 10 subagentes: search_google, search_bing, read_wikipedia, read_github, extract_summary… El orquestador invoca más tiempo del que tarda la tarea real.

Un diseño razonable son 3-5 subagentes centrales:

• research: toda búsqueda y extracción
• analysis: procesamiento y razonamiento
• writer: organización y salida de contenido
• reviewer: control de calidad (opcional)

Cada uno con límites claros. research no redacta informes; writer no hace búsquedas web.

Optimización de rendimiento

Dos puntos clave:

Lectura bajo demanda. No hagas read_file de todos los intermedios de golpe. Lee según la tarea actual. Las referencias a archivos guardan rutas en contexto y cargan contenido solo cuando hace falta.

Context Summarization con criterio. En tareas largas el contexto se llena. DeepAgents puede resumir pasos intermedios en descripciones breves. Ahorra tokens, pero cuida no perder información crítica.

agent = create_deep_agent(
    ...,
    context_management={
        "summarization_threshold": 50000,  # 50K tokens 时触发摘要
        "preserve_last_n_steps": 5  # 保留最近 5 步的详细记录
    }
)

Manejo de errores y validación

Los flujos largos fallan más. Planifica recuperación:

LLM-as-a-Judge. Otro LLM revisa la salida. Por ejemplo, reviewer_subagent comprueba huecos lógicos o datos faltantes en el informe de writer_subagent.

Puntos de intervención humana. Pausa en decisiones críticas. Tras la investigación, confirma con el usuario la dirección antes de seguir.

agent = create_deep_agent(
    ...,
    verification={
        "auto_verify": True,  # 启用自动验证
        "human_checkpoint": "before_output"  # 输出前人工确认
    }
)

Resumen

Repaso de los cuatro pilares de DeepAgents:

Planning Tools dan capacidad de planificación; todo_write usa el context window como working memory para mantener el objetivo a largo plazo.

Sub-agents aportan especialización y aislamiento; el orquestador conserva contexto limpio sin pasos intermedios.

File System supera el límite del context window con referencias a archivos y lectura bajo demanda.

System Prompts definen límites de comportamiento con documentación de ingeniería que cubre casos límite.

Los cuatro pilares convierten al agente de ejecución reactiva en razonamiento estructurado. Claude Code, Deep Research y Manus demuestran que la arquitectura funciona.

Próximos pasos:

• Construye tu primer agente de tarea larga con DeepAgents. El repositorio oficial en GitHub incluye ejemplos completos: langchain-ai/deepagents.
• Profundiza en la documentación de LangChain en docs.langchain.com/oss/python/deepagents.
• Sigue la serie de desarrollo con IA: próximos temas incluyen diseño de máquinas de estado en LangGraph y optimización de sistemas de memoria para agentes.