Deep Agents CLI

Descripción de la cápsula

Deep Agents CLI te permite ejecutar agentes autónomos desde la terminal. No es un wrapper de desarrollo ni un entorno de testing — es una herramienta de productividad. Le das una tarea, el agente planifica, ejecuta, escribe archivos, y te entrega el resultado. Tú vuelves cuando termina.

En el Módulo 6 construiste un CLI para tu agente manualmente: argparse, loop de ejecución, manejo de errores, output formateado. Funcionó, pero cada nuevo agente requería reconstruir esa capa. Deep Agents CLI te da todo eso out-of-the-box con un solo comando.

La diferencia con las cápsulas anteriores: en 02-05 aprendiste las capacidades de Deep Agents como APIs de Python. En esta cápsula, esas mismas capacidades las invocas desde la terminal sin escribir código.

Instalación y configuración

Instalar el CLI

Si instalaste deep-agents en la cápsula 01, el CLI ya está disponible:

pip install deep-agents

Verifica que funciona:

deep-agent --version
# Output esperado:
# deep-agent 0.2.x

Configurar API keys

El CLI lee variables de entorno. Si ya tienes un .env, configura que se cargue en tu shell:

export OPENAI_API_KEY=sk-...

O usa un archivo .env en el directorio de trabajo:

# .env
OPENAI_API_KEY=sk-...
TAVILY_API_KEY=tvly-...

El CLI carga automáticamente .env del directorio actual.

Verificación rápida

deep-agent "¿Cuál es la capital de Francia?"
# Output esperado:
# [Planning] Task is simple, executing directly...
# [Result] La capital de Francia es París.

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

Uso básico: una tarea, un resultado

Comando directo

deep-agent "Investiga las tendencias actuales en RAG y escribe un resumen en output/rag-trends.md"

Lo que sucede internamente:

1. [Planning]     write_todos: descompone "investigar RAG" en pasos
2. [Executing]    Paso 1: Buscar fuentes sobre RAG 2025
3. [Filesystem]   Escribir hallazgos en research/web_results.md
4. [Executing]    Paso 2: Analizar y sintetizar
5. [Filesystem]   Escribir análisis en analysis/synthesis.md
6. [Executing]    Paso 3: Generar resumen final
7. [Filesystem]   Escribir reporte en output/rag-trends.md
8. [Complete]     3/3 todos completados. Archivo: output/rag-trends.md

El archivo output/rag-trends.md queda en tu directorio de trabajo. Lo abres, lo revisas, lo usas.

Ejemplo con output real

deep-agent "Crea una comparativa de 3 frameworks de AI agents (LangGraph, CrewAI, AutoGen). Incluye pros, contras y casos de uso. Escribe el resultado en output/frameworks-comparison.md"

# Output esperado (streaming):
# ─── Deep Agent: Research Assistant ───
# [Plan] Creating task breakdown...
#   1. [pending] Search for LangGraph features and use cases
#   2. [pending] Search for CrewAI features and use cases
#   3. [pending] Search for AutoGen features and use cases
#   4. [pending] Compare and analyze frameworks
#   5. [pending] Write comparison report
#
# [Step 1/5] Searching LangGraph...
#   ✅ Found 8 relevant sources
#   → Saved to research/langgraph.md
#
# [Step 2/5] Searching CrewAI...
#   ✅ Found 6 relevant sources
#   → Saved to research/crewai.md
#
# [Step 3/5] Searching AutoGen...
#   ✅ Found 7 relevant sources
#   → Saved to research/autogen.md
#
# [Step 4/5] Analyzing frameworks...
#   → Saved to analysis/comparison.md
#
# [Step 5/5] Writing final report...
#   → Saved to output/frameworks-comparison.md
#
# ─── Complete ───
# Files generated: 5
# Todos: 5/5 completed
# Total tokens: ~12,400
# Estimated cost: $0.03

Modo interactivo: conversación con el agente

El modo interactivo te permite supervisar y redirigir al agente mientras trabaja.

Iniciar modo interactivo

deep-agent --interactive

# Output esperado:
# ─── Deep Agent Interactive Mode ───
# Type your task, or 'quit' to exit.
#
# > Investiga el estado de AI safety en 2025
#
# [Plan] Creating task breakdown...
#   1. [pending] Define scope of AI safety research
#   2. [pending] Search academic papers
#   3. [pending] Search industry reports
#   4. [pending] Synthesize findings
#   5. [pending] Write report
#
# [Step 1/5] Defining scope...
#   → Focus: alignment, governance, technical safety
#
# > Enfócate más en governance y regulación, menos en alignment técnico
#
# [Replanning] Adjusting focus...
#   1. [completed] Define scope → UPDATED to governance focus
#   2. [pending] Search EU AI Act and regulations
#   3. [pending] Search US executive orders on AI
#   4. [pending] Search industry self-regulation
#   5. [pending] Synthesize governance landscape
#   6. [pending] Write report
#
# [Step 2/6] Searching EU AI Act...

El punto clave: puedes redirigir la investigación en cualquier momento sin reiniciar. El agente re-planifica dinámicamente.

Comandos en modo interactivo

Comandos disponibles en modo interactivo:

> [texto]           Envía instrucciones al agente
> /status           Muestra el progreso actual de los todos
> /files            Lista los archivos generados
> /read [path]      Muestra el contenido de un archivo generado
> /cost             Muestra tokens usados y costo estimado
> /pause            Pausa la ejecución actual
> /resume           Reanuda la ejecución
> /quit             Termina la sesión

Ejemplo: verificar progreso y leer archivos

# Dentro del modo interactivo:

> /status
# Output esperado:
# Todos:
#   1. [completed] Define scope
#   2. [completed] Search EU AI Act
#   3. [in_progress] Search US executive orders
#   4. [pending] Search industry self-regulation
#   5. [pending] Synthesize governance landscape
#   6. [pending] Write report
# Progress: 2/6 (33%)

> /files
# Output esperado:
# Files generated:
#   research/eu_ai_act.md      (2.4 KB)
#   research/us_executive.md   (1.8 KB)

> /read research/eu_ai_act.md
# Output esperado:
# --- research/eu_ai_act.md ---
# # EU AI Act: Key Provisions
#
# ## Classification System
# The EU AI Act categorizes AI systems into risk levels...
# ...

> /cost
# Output esperado:
# Tokens used: 8,420 (input: 6,100, output: 2,320)
# Estimated cost: $0.02
# Model: gpt-4.1-mini

Opciones de configuración

Selección de modelo

deep-agent --model openai:gpt-4.1 "Analiza este dataset y genera insights"

deep-agent --model openai:gpt-4.1-mini "Resume este artículo"

Usa gpt-4.1 para tareas complejas que requieren razonamiento profundo. Usa gpt-4.1-mini para tareas más simples donde velocidad y costo importan más.

Permisos de herramientas

deep-agent --tools web_search,file_write "Investiga X y escribe el reporte"

deep-agent --tools all "Investiga X, corre código, y genera gráficos"

deep-agent --tools none "Solo responde con lo que sabes, sin buscar"

Memory backend

deep-agent --memory filesystem:./agent_memory "Recuerda mis preferencias"

deep-agent --memory postgres:postgresql://user:pass@localhost/db "Recuerda mis preferencias"

deep-agent --memory none "No recuerdes nada de esta sesión"

Límite de iteraciones

deep-agent --max-iterations 10 "Investiga exhaustivamente el tema X"

deep-agent --max-iterations 3 "Dame un resumen rápido de Y"

max-iterations controla cuántos pasos de planning-ejecución puede hacer el agente. Más iteraciones = más profundo pero más costoso.

Directorio de salida

deep-agent --output-dir ./reports "Genera un reporte sobre AI agents"

El agente escribe todos los archivos dentro de ./reports/ en lugar del directorio actual.

Combinando opciones

deep-agent \
  --model openai:gpt-4.1 \
  --tools web_search,file_write \
  --memory filesystem:./memory \
  --max-iterations 15 \
  --output-dir ./research-output \
  "Investiga el impacto de LLMs en educación superior. Busca papers académicos, reportes de universidades, y datos estadísticos. Genera un reporte de 3 secciones con fuentes."

Shell commands: ejecución de comandos del sistema

Deep Agents CLI puede ejecutar comandos del sistema como parte de su flujo de trabajo. Esto lo hace potente para tareas de desarrollo.

Habilitación (con controles de seguridad)

deep-agent --tools shell "Lista los archivos Python en src/ y analiza la estructura del proyecto"

# Output esperado:
# [Plan] Creating task breakdown...
#   1. [pending] List Python files in src/
#   2. [pending] Analyze project structure
#   3. [pending] Write analysis
#
# [Step 1/3] Running shell command...
#   $ find src/ -name "*.py" -type f
#   ✅ Found 23 files
#
# [Step 2/3] Analyzing structure...
#   → Project follows domain-driven design
#   → 4 main modules: api/, core/, models/, utils/
#
# [Step 3/3] Writing analysis...
#   → Saved to output/project-analysis.md

Controles de seguridad

El CLI tiene restricciones por defecto para evitar operaciones destructivas:

Permitido por defecto:
  ✅ Lectura: ls, cat, head, find, grep, wc
  ✅ Análisis: python script.py (sin flags destructivos)
  ✅ Info del sistema: uname, whoami, pwd

Requiere confirmación (--shell-confirm):
  ⚠️ Escritura: mkdir, cp, mv
  ⚠️ Instalación: pip install, npm install
  ⚠️ Git: git add, git commit

Bloqueado siempre:
  ❌ Destructivos: rm -rf, drop database
  ❌ Sistema: sudo, chmod 777
  ❌ Red: curl con POST, wget

deep-agent --tools shell --shell-confirm "Reorganiza los archivos en src/ por dominio"

Con --shell-confirm, el agente te pide aprobación antes de ejecutar comandos que modifican el filesystem.

Casos de uso prácticos

1. Automatización de investigación

deep-agent \
  --tools web_search,file_write \
  --output-dir ./research \
  "Investiga el estado actual de vector databases en 2025. Compara Pinecone, Weaviate, Qdrant y Chroma. Incluye: features, pricing, performance benchmarks, y casos de uso ideales. Genera un reporte detallado con tabla comparativa."

Resultado: un reporte de 3-5 páginas en ./research/output/report.md con tabla comparativa, fuentes citadas, y conclusiones.

2. Code review automatizado

deep-agent \
  --tools shell,file_write \
  --output-dir ./review \
  "Revisa el código en src/api/ y src/models/. Analiza: naming conventions, error handling, type hints, docstrings, y posibles bugs. Genera un reporte con sugerencias de mejora priorizadas por severidad."

El agente lee tu código, lo analiza, y genera un reporte detallado sin modificar nada.

3. Análisis de datos

deep-agent \
  --tools shell,file_write \
  --model openai:gpt-4.1 \
  "Analiza el archivo data/sales_2025.csv. Identifica tendencias, outliers, y correlaciones. Genera visualizaciones en output/charts/ y un resumen ejecutivo en output/analysis.md"

4. Generación de documentación

deep-agent \
  --tools shell,file_write \
  "Lee el código en src/ y genera documentación técnica. Para cada módulo, incluye: descripción, funciones principales, parámetros, y ejemplos de uso. Escribe la documentación en docs/"

5. Preparación de entrevistas

deep-agent \
  --tools web_search,file_write \
  --memory filesystem:./interview-prep \
  "Prepárame para una entrevista de AI Engineer. Investiga las preguntas más comunes en 2025, crea 20 preguntas con respuestas modelo, y agrupa por categoría: LLMs, agents, RAG, MLOps, system design."

Configuración por proyecto

Archivo de configuración .deep-agent.yaml

En lugar de pasar opciones en cada comando, crea un archivo de configuración en la raíz del proyecto:

# .deep-agent.yaml
model: openai:gpt-4.1-mini
tools:
  - web_search
  - file_write
  - shell
memory:
  backend: filesystem
  path: ./.agent_memory
max_iterations: 10
output_dir: ./agent_output
shell:
  confirm: true
  blocked_commands:
    - rm -rf
    - drop
    - sudo
instructions: |
  Eres un asistente de desarrollo para el proyecto Atlas.
  El proyecto usa Python 3.12, FastAPI, y PostgreSQL.
  Siempre sigue las convenciones del proyecto en CONTRIBUTING.md.

Con esta configuración, puedes ejecutar:

deep-agent "Agrega validación de input al endpoint POST /users"

Y el agente ya sabe el contexto del proyecto, qué herramientas tiene, y cuáles son las convenciones.

Verificar configuración

deep-agent --show-config

# Output esperado:
# ─── Configuration ───
# Source: .deep-agent.yaml
# Model: openai:gpt-4.1-mini
# Tools: web_search, file_write, shell
# Memory: filesystem (./.agent_memory)
# Max iterations: 10
# Output dir: ./agent_output
# Shell confirm: true
# Custom instructions: Yes (3 lines)

Configuración personalizada con prompts

# .deep-agent.yaml para un proyecto de investigación
model: openai:gpt-4.1
tools:
  - web_search
  - file_write
memory:
  backend: filesystem
  path: ./.research_memory
max_iterations: 20
output_dir: ./research
instructions: |
  Eres un asistente de investigación académica.
  Prioriza papers de arxiv, ACL, NeurIPS, y ICML.
  Siempre incluye citas en formato APA.
  Los reportes deben tener: Abstract, Metodología, Hallazgos, Discusión, Referencias.

Monitorear la ejecución en tiempo real

Output en streaming

Por defecto, el CLI muestra el progreso en tiempo real:

deep-agent "Investiga X" --verbose

# Output con --verbose:
# [10:30:01] Starting Deep Agent...
# [10:30:01] Model: gpt-4.1-mini
# [10:30:01] Tools: web_search, file_write
# [10:30:02] [Planning] Analyzing task...
# [10:30:03] [Planning] Created 5 todos
# [10:30:03] [Todo 1] "Define scope" → in_progress
# [10:30:05] [Todo 1] "Define scope" → completed
# [10:30:05] [Tool] web_search("RAG techniques 2025")
# [10:30:08] [Tool] web_search returned 5 results
# [10:30:08] [Filesystem] Writing research/web_results.md (2.1 KB)
# [10:30:08] [Todo 2] "Search academic papers" → completed
# ...
# [10:30:45] [Complete] 5/5 todos completed
# [10:30:45] Files: 4 generated
# [10:30:45] Tokens: 15,230 (cost: ~$0.04)
# [10:30:45] Duration: 43 seconds

Output silencioso

deep-agent "Investiga X" --quiet
# Solo muestra el resultado final, sin progreso intermedio

Log a archivo

deep-agent "Investiga X" --log ./agent.log

El log captura todo: planning, tool calls, filesystem operations, tokens, y timing. Útil para debugging post-ejecución.

Comparación: CLI manual (M6) vs Deep Agents CLI

En el Módulo 6, si querías un agente que corriera desde terminal, construías la interfaz:

M6: CLI construido manualmente

import argparse
from dotenv import load_dotenv
load_dotenv()

from langchain_openai import ChatOpenAI
from langgraph.graph import StateGraph, START, END
from langgraph.checkpoint.memory import MemorySaver
from typing import TypedDict, Annotated
import operator

class State(TypedDict):
    messages: Annotated[list, operator.add]
    query: str

def search_node(state):
    query = state["query"]
    return {"messages": [{"role": "assistant", "content": f"Resultados para: {query}"}]}

def report_node(state):
    return {"messages": [{"role": "assistant", "content": "Reporte generado."}]}

builder = StateGraph(State)
builder.add_node("search", search_node)
builder.add_node("report", report_node)
builder.add_edge(START, "search")
builder.add_edge("search", "report")
builder.add_edge("report", END)

graph = builder.compile(checkpointer=MemorySaver())

parser = argparse.ArgumentParser(description="Research Agent CLI")
parser.add_argument("query", help="Research topic")
parser.add_argument("--model", default="gpt-4.1-mini")
parser.add_argument("--max-sources", type=int, default=5)
parser.add_argument("--output", default="output/report.md")

args = parser.parse_args()

result = graph.invoke(
    {"messages": [], "query": args.query},
    config={"configurable": {"thread_id": "cli-session"}}
)

print(f"Query: {args.query}")
print(f"Model: {args.model}")
print(f"Output: {args.output}")
# Output esperado (cuando se ejecuta con: python cli.py "AI agents"):
# Query: AI agents
# Model: gpt-4.1-mini
# Output: output/report.md

~40 líneas solo para la interfaz CLI, sin contar el agente real.

Deep Agents CLI: cero código

deep-agent --model openai:gpt-4.1-mini --output-dir ./output "AI agents"

Una línea. El CLI, el planning, el filesystem, el output — todo incluido.

Tabla comparativa

El trade-off es el mismo de siempre: conveniencia vs control. El CLI manual te da exactamente la interfaz que quieres. Deep Agents CLI te da una interfaz completa sin escribir código.

Troubleshooting

1. deep-agent: command not found

Causa: El paquete no se instaló globalmente o no está en el PATH.

Solución:

pip install deep-agents
# O si usas pipx:
pipx install deep-agents

# Verifica:
which deep-agent
# Output esperado: /usr/local/bin/deep-agent o similar

2. El agente no termina (se queda en loop)

Causa: No configuraste max-iterations y la tarea es ambigua.

Solución:

deep-agent --max-iterations 10 "Tu tarea aquí"

Si el agente alcanza el límite, se detiene y entrega lo que tenga hasta ese punto.

3. No encuentra la API key

Causa: La variable de entorno no está configurada o el .env no está en el directorio actual.

Solución:

echo $OPENAI_API_KEY
# Si está vacío:
export OPENAI_API_KEY=sk-...

# O verifica el .env:
cat .env | head -1
# Debe mostrar: OPENAI_API_KEY=sk-...

4. Los archivos no se generan en el directorio esperado

Causa: No especificaste --output-dir y el agente usa un directorio interno.

Solución:

deep-agent --output-dir ./mi-directorio "Tu tarea"
# Los archivos quedan en ./mi-directorio/

5. El modo interactivo no acepta input

Causa: Estás ejecutando en un entorno sin TTY (pipe, script, CI).

Solución: El modo interactivo requiere una terminal real. Para scripts, usa el modo directo:

# En un script (no interactivo):
deep-agent "Tarea directa sin interacción"

# Para interactivo, ejecuta en terminal directa:
deep-agent --interactive

Ejercicios

Ejercicio 1: Primera ejecución CLI

Ejecuta un comando simple con Deep Agents CLI: pide que investigue un tema corto y escriba el resultado en un archivo. Verifica que el archivo se creó y contiene contenido relevante.

deep-agent --output-dir ./ex1 "¿Cuáles son las 3 mejores prácticas de prompt engineering en 2025? Escribe el resultado en output/best-practices.md"

ls ./ex1/output/
# Output esperado:
# best-practices.md

cat ./ex1/output/best-practices.md | head -20
# Output esperado:
# # Mejores Prácticas de Prompt Engineering (2025)
#
# ## 1. Structured Prompts
# ...

Ejercicio 2: Modo interactivo con redirección

Inicia el modo interactivo. Pide una investigación sobre un tema. A mitad del proceso, redirige el enfoque. Verifica que el agente re-planificó.

deep-agent --interactive --output-dir ./ex2

> Investiga frameworks de AI agents en 2025

# Espera a que complete el paso 1-2...

> Enfócate solo en frameworks open-source, ignora soluciones enterprise

# Verifica:
> /status
# Debería mostrar un plan actualizado que filtra enterprise solutions

> /files
# Verifica que los archivos reflejan el nuevo enfoque

> /quit

Ejercicio 3: Configuración por proyecto

Crea un archivo .deep-agent.yaml para un proyecto ficticio. Configura: modelo, tools, memory, y instructions. Ejecuta una tarea y verifica que la configuración se aplica.

model: openai:gpt-4.1-mini
tools:
  - web_search
  - file_write
memory:
  backend: filesystem
  path: ./.agent_memory
max_iterations: 5
output_dir: ./project_output
instructions: |
  Eres un asistente de desarrollo para un proyecto Python.
  Siempre sugiere code con type hints.
  Los reportes deben ser concisos (máximo 500 palabras).

deep-agent --show-config
# Debe mostrar la configuración del archivo

deep-agent "¿Cuáles son las mejores prácticas para FastAPI en 2025?"
# El reporte debe ser conciso (<500 palabras) y mencionar type hints

Ejercicio 4: Automatización de research con output estructurado

Usa el CLI para investigar 3 temas relacionados, cada uno en su propio archivo. Verifica que el agente organiza los archivos correctamente.

deep-agent \
  --tools web_search,file_write \
  --output-dir ./ex4 \
  --max-iterations 15 \
  "Investiga 3 temas: (1) RAG techniques, (2) AI agent architectures, (3) LLM evaluation methods. Para cada tema, escribe un resumen en un archivo separado: output/rag.md, output/agents.md, output/evaluation.md. Al final, genera output/summary.md con un resumen ejecutivo que conecte los 3 temas."

ls ./ex4/output/
# Output esperado:
# rag.md  agents.md  evaluation.md  summary.md

wc -l ./ex4/output/*.md
# Verifica que cada archivo tiene contenido sustancial

Ejercicio 5: Code review con shell

Usa el CLI con herramienta shell para analizar un directorio de código y generar un reporte de calidad.

deep-agent \
  --tools shell,file_write \
  --shell-confirm \
  --output-dir ./ex5 \
  "Analiza los archivos Python en el directorio actual. Lista todos los archivos .py, cuenta las líneas de código, identifica imports no usados si es posible, y verifica si hay docstrings en las funciones públicas. Genera un reporte en output/code-review.md"

cat ./ex5/output/code-review.md
# Debe contener: lista de archivos, conteo de líneas, observaciones sobre calidad

Ejercicio 6: Comparación de costos CLI vs API (Avanzado)

Ejecuta la misma tarea con CLI y con la API de Python. Compara: tokens usados, archivos generados, y tiempo de ejecución.

time deep-agent \
  --model openai:gpt-4.1-mini \
  --tools web_search,file_write \
  --output-dir ./ex6_cli \
  --verbose \
  "Investiga las tendencias de AI agents en 2025 y genera un resumen"

import time
from dotenv import load_dotenv
load_dotenv()

from deep_agents import create_deep_agent
from langchain_community.tools import TavilySearchResults

start = time.time()

agent = create_deep_agent(
    "openai:gpt-4.1-mini",
    tools=[TavilySearchResults(max_results=3)],
    name="assistant",
    instructions="Investiga las tendencias de AI agents en 2025 y genera un resumen.",
)

result = agent.run("Investiga las tendencias de AI agents en 2025 y genera un resumen")

elapsed = time.time() - start

print(f"API - Tiempo: {elapsed:.1f}s")
print(f"API - Archivos: {len(result.files)}")
print(f"API - Todos completados: {sum(1 for t in result.todos if t['status'] == 'completed')}")
# Output esperado (comparar con CLI):
# API - Tiempo: ~35-50s
# API - Archivos: 3-4
# API - Todos completados: 4-5

Resumen

• Deep Agents CLI ejecuta agentes autónomos desde la terminal — una herramienta de productividad, no un entorno de desarrollo
• Uso básico: deep-agent "tu tarea" — el agente planifica, ejecuta, y entrega archivos con resultados
• Modo interactivo (--interactive) permite supervisar y redirigir al agente en tiempo real, con comandos como /status, /files, /read, y /cost
• Opciones de configuración: --model, --tools, --memory, --max-iterations, --output-dir controlan el comportamiento desde la línea de comandos
• Shell commands permiten que el agente ejecute comandos del sistema con controles de seguridad (--shell-confirm para aprobación, comandos destructivos bloqueados)
• Configuración por proyecto vía .deep-agent.yaml elimina la necesidad de pasar opciones en cada comando
• Comparación con M6: construir un CLI manual toma ~40 líneas solo para la interfaz. Deep Agents CLI provee todo sin código, con el trade-off de menos personalización

Próxima cápsula: Árbol de decisión — create_agent vs LangGraph vs Deep Agents. La cápsula más importante del módulo: un framework de decisión definitivo para elegir el nivel de abstracción correcto.

Recursos adicionales

1. Deep Agents CLI — Documentation — Referencia completa de comandos y opciones del CLI
2. Deep Agents Configuration — Formato de .deep-agent.yaml y opciones disponibles
3. Click (Python CLI Framework) — Si necesitas construir un CLI custom más allá de lo que Deep Agents provee
4. Rich (Terminal Formatting) — Librería para output formateado en terminal, usada internamente por Deep Agents CLI
5. Autonomous Agent Patterns — Patrones de agentes autónomos y cómo el CLI los implementa

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