LangChain Deep Agents: Planificación, archivos y subagentes integrados.

Los equipos que se toman en serio el uso de agentes suelen seguir el mismo camino. Comienzan con las cadenas de LangChain, que manejan bien los pipelines simples. Luego la tarea se vuelve más compleja: requiere llamadas a herramientas, bucles y resultados de longitud impredecible. Las cadenas ya no son suficientes, así que pasan a LangGraph, donde ahora escriben esquemas de estado, aristas condicionales y código de compilación de grafos antes incluso de abordar el problema real.

LangGraph no es el problema. Es potente. Pero se trata de un entorno de ejecución, una primitiva de bajo nivel, y la gente a menudo lo trata como un framework de aplicaciones. deepagents es la respuesta de LangChain a esta discrepancia.

Qué es

“Agentes profundos” podría significar casi cualquier cosa, así que para ser precisos: deepagents es un paquete independiente de Python, que se instala con pip install deepagents, y se basa en LangChain y LangGraph. La documentación de LangChain lo denomina un mecanismo para agentes. Funciona con el mismo ciclo de llamada a herramientas que otros frameworks, pero incluye capacidades adicionales integradas, por lo que no es necesario volver a crearlas cada vez.

El punto de entrada es create_deep_agent(). Primero hay que importarlo:

from deepagents import create_deep_agent

Luego, ingrese una herramienta y una instrucción:

def get_weather(city: str) -> str:
    """Get weather for a given city."""
    return f"It's always sunny in {city}!"
agent = create_deep_agent(
    tools=[get_weather],
    system_prompt="You are a helpful assistant",
)
agent.invoke(
    {"messages": [{"role": "user", "content": "What is the weather in Mumbai?"}]}
)

Eso es todo. La biblioteca se encarga del grafo LangGraph, del estado, de la transmisión en tiempo real y de la gestión de la ventana de contexto, y usted nunca tiene que intervenir en nada de eso. Lo más interesante es lo que viene incluido.

Cinco capacidades integradas

Planificación mediante write_todos

Cada agente avanzado recibe automáticamente una herramienta write_todos. Ante una tarea complicada, divide el trabajo en pasos, marca cada uno como pendiente, en curso o completado, y revisa el plan a medida que las circunstancias cambian. Esto no es un truco con los prompts; la lista se encuentra en el estado del agente, por lo que este puede volver a ella, actualizarla y hacer referencia a ella durante toda la sesión. Nadie tiene que indicarle al modelo que piense paso a paso, ya que la estructura forma parte del sistema.

Un sistema de archivos virtual

Este podría ser la mayor sorpresa. Por defecto, el agente cuenta con ls, read_file, write_file, edit_file, glob y grep. ¿Por qué necesitaría un agente archivos? Para la gestión del contexto.

Las ventanas de contexto son finitas, y las búsquedas prolongadas, la ejecución de código o los resultados de herramientas voluminosas hacen que el historial crezca rápidamente. Los agentes avanzados almacenan contenido pesado en el sistema de archivos virtual en lugar de mantenerlo todo en el prompt. Cuando el resultado de una herramienta supera los 20,000 tokens, la biblioteca lo guarda en el backend configurado y deja en el contexto la ruta del archivo junto con una vista previa de 10 líneas. Cuando el agente necesita el contenido completo, llama a read_file o grep. Esto no es ni fragmentación ni truncamiento, sino una descarga deliberada con recuperación bajo demanda.

El backend del sistema de archivos es intercambiable: por defecto, estado en memoria, disco local, LangGraph Store para la persistencia entre hilos, o entornos aislados como Modal y Daytona.

Subagentes

Una herramienta task integrada permite al agente principal crear subagentes especializados para tareas secundarias aisladas. Esto es más importante de lo que parece. En un trabajo de investigación prolongado, un solo agente que maneja todo llena su contexto con pasos intermedios, resultados de búsqueda y salidas parciales. Con subagentes, el agente principal asigna una tarea secundaria a una instancia nueva con un contexto limpio. Esa instancia trabaja por sí sola, finaliza y envía un resumen, de modo que el contexto del agente principal permanece ordenado.

Puedes definir subagentes personalizados con sus propias herramientas y prompts del sistema. Comienza con la importación:

from deepagents import create_deep_agent, Subagent

Luego defina un revisor y átelo:

code_reviewer = Subagent(
    name="code-reviewer",
    system_prompt="You are an expert code reviewer. Analyze code for bugs, style, and performance.",
    tools=[read_file_tool],
)
agent = create_deep_agent(
    tools=[internet_search],
    subagents=[code_reviewer],
    system_prompt="You are a research and engineering assistant.",
)

Un subagente de uso general con herramientas de sistema de archivos está siempre disponible sin necesidad de configuración alguna.

Resumen automático

En tareas largas, aquí es donde la biblioteca demuestra su utilidad. Una vez que el contexto alcanza el 85% del límite del modelo y no queda nada más que transferir a archivos, el sistema activa el proceso de resumen. Un LLM escribe un resumen estructurado que abarca la intención de la sesión, los artefactos creados y los próximos pasos, y ese resumen reemplaza el historial completo en la memoria de trabajo. Los mensajes originales se guardan en el sistema de archivos como registro canónico, para que se puedan recuperar los detalles más tarde. En efecto, los agentes avanzados pueden continuar con tareas complejas sin llegar a los límites de contexto, algo que de lo contrario tendría que configurarse manualmente en LangGraph puro.

Memoria a lo largo de las conversaciones

Normalmente, el estado permanece dentro de un hilo. Sin embargo, al configurar un CompositeBackend con un LangGraph Store, el agente puede conservar la memoria a lo largo de las sesiones y los hilos. Los archivos almacenados en la ruta /memories/, o en cualquier ruta que elijas, sobreviven a los reinicios y pueden ser leídos desde cualquier conversación. Úsalo para que el agente recuerde tus preferencias, los hábitos de programación de tu repositorio o dónde quedó un trabajo de investigación que abarcó varios días. Primero, las importaciones:

from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend
from langgraph.store.memory import InMemoryStore

Luego, el cableado:

store = InMemoryStore()
backend = CompositeBackend(
    routes={"/memories/": StoreBackend(store=store)},
    default=StateBackend(),
)
agent = create_deep_agent(
    tools=[...],
    backend=backend,
    memory=["path/to/AGENTS.md"],  # persistent context file
)

Cómo se relacionan las piezas

La gente las confunde, así que vale la pena ser explícito.

• LangChain proporciona los componentes básicos: modelos, herramientas, prompts y cadenas. Es la base.
• LangGraph es un entorno de ejecución para operaciones duraderas y basadas en grafos, que gestiona la persistencia, la transmisión de datos en tiempo real, las interrupciones y flujos condicionales complejos. Es el motor.
• Deep Agents es una capa que integra ambos. No reemplaza a LangGraph; utiliza LangGraph para todo y agrega una API de nivel superior con valores predeterminados bien definidos, de modo que no es necesario crear uno mismo el planificador, la capa de sistema de archivos, la compresión de contexto ni la infraestructura de subagentes.

Una forma de imaginarlo: LangGraph te da un motor y una transmisión, mientras que Deep Agents te entrega un coche completo.

Para agentes simples, create_agent de LangChain probablemente sea suficiente. Cuando las tareas son complejas, requieren mucho tiempo de ejecución y necesitan mucho contexto, ahí es donde deepagents compensa su costo de abstracción.

Una guía de inicio rápida realista: un agente de investigación

Aquí hay un agente de investigación que busca en la web y escribe un informe estructurado. Primero se realiza la configuración:

import os
from typing import Literal
from tavily import TavilyClient
from deepagents import create_deep_agent

Luego, la herramienta, las instrucciones y el propio agente:

tavily_client = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])
def internet_search(
    query: str,
    max_results: int = 5,
    topic: Literal["general", "news", "finance"] = "general",
    include_raw_content: bool = False,
):
    """Run a web search and return results."""
    return tavily_client.search(
        query,
        max_results=max_results,
        include_raw_content=include_raw_content,
        topic=topic,
    )
research_instructions = """You are an expert researcher.
Your job is to conduct thorough research and then write a polished report.
Use internet_search to gather information.
Write your findings to files as you go to avoid losing context.
Use write_todos to plan your research steps before starting.
"""
agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",  # default model
    tools=[internet_search],
    system_prompt=research_instructions,
)
result = agent.invoke({
    "messages": [{
        "role": "user",
        "content": "Research the current state of agentic AI frameworks in 2025 and write a structured report."
    }]
})
print(result["messages"][-1].content)

Al ejecutarlo se inicia una secuencia. El agente llama a write_todos para planificar la investigación. Realiza búsquedas y descarga automáticamente los resultados grandes al sistema de archivos virtual. Si el trabajo es extenso, inicia un subagente para cada sección. Lee los archivos cuando es necesario y reúne todo en un informe final. Durante todo este proceso, el framework gestiona el contexto para que el modelo nunca supere su límite de tiempo de ejecución. Usted no escribió ninguna parte de esa infraestructura, ya que viene incluida con el framework.

El agente de línea de comandos

El paquete también incluye un agente de terminal desarrollado con el mismo SDK:

pip install deepagents
deepagents  # launches the interactive CLI agent

Es un agente de programación similar a Claude Code o Aider, pero que funciona con el SDK de Deep Agents. Ofrece un modo interactivo, un modo no interactivo tipo tubería para scripting (la bandera -n), habilidades personalizadas y memoria persistente. Enséñale las convenciones de tu proyecto y él las recordará de una sesión a otra. Así, el SDK que impulsa a un agente de investigación en producción también te proporciona de inmediato una herramienta útil para desarrolladores.

Cuándo usarlo

deepagents es adecuado para ti cuando:

• La tarea requiere planificación y muchos pasos.
• Los resultados de las herramientas son extensos y deben gestionarse a lo largo de una sesión larga.
• Deseas delegar tareas a subagentes sin tener que crear la infraestructura necesaria.
• Necesitas una memoria que persista a través de diferentes hilos de conversación.
• Estás creando un agente de programación o un sistema de investigación autónomo.

Quédese con create_agent o con LangGraph puro cuando:

• El agente es simple, con una o dos llamadas a herramientas y respuestas cortas.
• Necesita un control preciso sobre la topología del grafo.
• Ya está muy avanzado en un flujo de trabajo personalizado de LangGraph y no desea valores predeterminados rígidos.

Los propios documentos lo indican claramente: los agentes simples requieren herramientas simples.

Por qué es importante

El momento actual dice algo al respecto. Los patrones básicos de agentes, las llamadas a herramientas, los bucles ReAct y los sistemas RAG simples ya son bien comprendidos. Lo que el campo aún está intentando resolver es la fiabilidad en tareas a largo plazo que requieren planificación, un contexto amplio, persistencia y delegación. Cada equipo que desarrolla agentes en producción ha tenido que abordar esos mismos problemas desde cero, y las estrategias de contexto, los patrones de subagentes y los diseños de memoria siguen siendo reinventados en formas ligeramente diferentes.

deepagents representa la apuesta de LangChain de que esas soluciones son lo suficientemente comunes como para estandarizarse. Un framework con valores predeterminados definidos, infraestructura integrada y backends conectables intenta desplazar la pregunta de “¿cómo construimos la infraestructura necesaria?” a “¿qué debería hacer realmente el agente?”. Su éxito depende de que los valores predeterminados sobrevivan en entornos de producción. Sin embargo, como dirección, tiene sentido.

Comenzando

Instale el paquete y el cliente de búsqueda:

pip install deepagents tavily-python

Luego establezca sus claves:

export ANTHROPIC_API_KEY="your-key"
export TAVILY_API_KEY="your-key"
export LANGSMITH_TRACING=true  # optional, for debugging
export LANGSMITH_API_KEY="your-key"

La descripción general de los Deep Agents en la documentación de LangChain abarca los servidores backend, los subagentes, los entornos de pruebas aislados, el modelo con intervención humana y la interfaz de línea de comandos. Si estás desarrollando algo serio con agentes, dedica una tarde a averiguar cómo encaja en tu stack tecnológico, incluso si no lo adoptas de inmediato.