CubeLabs

1. ¿Qué es DeerFlow? — Arquitectura y filosofía

DeerFlow (Deep Exploration and Efficient Research Flow) nació como un framework de Deep Research y evolucionó hasta convertirse en un harness de SuperAgentes. La versión 2.0 es una reescritura completa que comparte cero código con v1.

La filosofía de DeerFlow es simple: proporcionar a los agentes de IA la infraestructura necesaria para hacer trabajo real. No es un chatbot con acceso a herramientas — es un agente con su propio ordenador: sistema de archivos, memoria persistente, habilidades extensibles y la capacidad de planificar y lanzar sub-agentes.

2. Instalación y configuración con Docker

La forma más rápida de empezar con DeerFlow es mediante Docker. El repositorio incluye un asistente de configuración interactivo que guía paso a paso.

git clone https://github.com/bytedance/deer-flow.git
cd deer-flow

make setup

make docker-init   # Descargar imagen sandbox (solo la primera vez)
make docker-start  # Iniciar servicios con hot-reload

3. Skills & Tools — El corazón extensible

Las Skills son el mecanismo principal para extender las capacidades de DeerFlow. Una Skill es un archivo Markdown que define un flujo de trabajo, mejores prácticas y referencias a recursos de soporte.

Skills incluidas por defecto

/mnt/skills/public/
├── research/SKILL.md          # Investigación profunda
├── report-generation/SKILL.md # Generación de informes
├── slide-creation/SKILL.md    # Creación de diapositivas
├── web-page/SKILL.md          # Generación de páginas web
└── image-generation/SKILL.md  # Generación de imágenes

Skills personalizadas

Puedes añadir tus propias skills en /mnt/skills/custom/. Cada skill vive en su propia carpeta con un SKILL.md que define su comportamiento.

Activación de Skills

Las skills se cargan progresivamente — solo cuando la tarea las necesita. Puedes activar una skill explícitamente para un turno empezando el mensaje con /nombre-skill:

/data-analysis analyze uploads/datos.csv

Herramientas (Tools)

DeerFlow incluye un conjunto básico de herramientas: búsqueda web, fetch de URLs, captura de pantalla renderizada, operaciones de archivo y ejecución bash. También soporta herramientas personalizadas mediante servidores MCP y funciones Python.

Integración con Claude Code

La skill claude-to-deerflow permite interactuar con DeerFlow desde Claude Code:

npx skills add https://github.com/bytedance/deer-flow --skill claude-to-deerflow

Una vez instalada, usa /claude-to-deerflow en Claude Code para enviar tareas, verificar estado y gestionar conversaciones.

4. Sub-Agentes — Orquestación de tareas complejas

Las tareas complejas rara vez caben en un solo paso. DeerFlow las descompone automáticamente.

El agente principal (lead agent) puede lanzar sub-agentes sobre la marcha, cada uno con su propio contexto aislado, herramientas y condiciones de terminación. Los sub-agentes se ejecutan en paralelo cuando es posible, reportan resultados estructurados y el agente principal sintetiza todo en una salida coherente.

Ejemplo de flujo: una tarea de investigación puede desplegarse en una docena de sub-agentes, cada uno explorando un ángulo diferente, para luego converger en un solo informe — o un sitio web — o una presentación con imágenes generadas.

5. Sandbox y sistema de archivos

DeerFlow no solo habla de hacer cosas — tiene su propio ordenador. Cada tarea obtiene un entorno de ejecución completo con vista del sistema de archivos: skills, espacio de trabajo, subidas y resultados.

Estructura del sandbox

/mnt/user-data/
├── uploads/          ← Tus archivos subidos
├── workspace/        ← Directorio de trabajo de los agentes
└── outputs/          ← Resultados finales

Modos de sandbox

El agente puede leer, escribir y editar archivos, ver imágenes y — cuando está configurado de forma segura — ejecutar comandos shell.

6. Context Engineering y Memoria a Largo Plazo

La mayoría de los agentes lo olvidan todo cuando termina la conversación. DeerFlow recuerda.

Context Engineering

Dentro de una sesión, DeerFlow gestiona el contexto de forma agresiva:

• Contexto aislado de sub-agentes: cada sub-agente corre en su propio contexto, sin ver el del agente principal
• Summarización: las subtareas completadas se resumen, los resultados intermedios se vuelcan al sistema de archivos
• Compresión: lo que ya no es relevante se comprime para no reventar la ventana de contexto
• Recuperación estricta de tool-calls: si un proveedor interrumpe un bucle de tool-calls, DeerFlow inyecta resultados placeholder para mantener la secuencia válida

Memoria a Largo Plazo

A través de sesiones, DeerFlow construye una memoria persistente de tu perfil, preferencias y conocimiento acumulado. Cuanto más lo usas, mejor te conoce: tu estilo de escritura, tu stack técnico, tus flujos de trabajo recurrentes. La memoria se almacena localmente y permanece bajo tu control.

Las actualizaciones de memoria evitan entradas duplicadas en tiempo de aplicación, por lo que las preferencias repetidas no se acumulan sin fin entre sesiones.

7. Servidor MCP y Canales de Mensajería

DeerFlow soporta servidores MCP configurables (Model Context Protocol) para extender sus capacidades, incluyendo flujos OAuth para servidores HTTP/SSE.

Canales IM compatibles

Configuración básica de Telegram en config.yaml

channels:
  telegram:
    enabled: true
    bot_token: $TELEGRAM_BOT_TOKEN
    allowed_users: []

Una vez conectado, los comandos disponibles desde el chat son:

8. Embedded Python Client

DeerFlow puede usarse como biblioteca Python embebida sin ejecutar servicios HTTP completos. El DeerFlowClient proporciona acceso directo en-proceso a todas las capacidades del agente.

from deerflow.client import DeerFlowClient

client = DeerFlowClient()

# Chat simple
response = client.chat("Analiza este informe para mí",
                        thread_id="mi-hilo")

# Streaming (protocolo SSE de LangGraph)
for event in client.stream("hola mundo"):
    if event.type == "messages-tuple" and event.data.get("type") == "ai":
        print(event.data["content"])

# Gestión de configuración
models = client.list_models()      # {"models": [...]}
skills = client.list_skills()      # {"skills": [...]}
client.update_skill("web-search", enabled=True)

# Subida de archivos
client.upload_files("thread-1", ["./reporte.pdf"])

Todos los métodos que devuelven diccionarios están validados contra los modelos Pydantic del Gateway en CI, asegurando que el cliente embebido se mantenga sincronizado con los esquemas de la API HTTP.

Instalación

uv pip install 'deerflow-harness'

9. Terminal Workbench (TUI)

deerflow es un workbench nativo de terminal para quienes viven en la shell. Se ejecuta embebido sobre DeerFlowClient — sin Gateway, frontend, nginx ni Docker requeridos — respetando la misma configuración que el resto de DeerFlow.

# Instalación con dependencia TUI
uv pip install 'deerflow-harness[tui]'

# Lanzar la interfaz de terminal
deerflow

# Reanudar el hilo más reciente
deerflow --continue

# Reanudar un hilo específico
deerflow --resume THREAD_ID

# Respuesta única (headless) a stdout
deerflow --print "resume este repositorio"

# Salida JSON para integraciones
deerflow --json "hola mundo"

Características de la TUI

• Chat con transcript en Markdown renderizado
• Tarjetas compactas de actividad de herramientas
• Paleta de comandos con /
• Selectores de /model y /threads
• Historial de entrada
• Esc / Ctrl+C para interrumpir

Las sesiones abiertas en la TUI también aparecen en la interfaz web — ambas comparten el mismo almacén de hilos bajo el usuario local por defecto.

10. Despliegue en producción y seguridad

DeerFlow tiene capacidades de alto privilegio: ejecución de comandos, operaciones de archivos e invocación de lógica de negocio. Está diseñado por defecto para entornos locales de confianza (accesible solo vía 127.0.0.1).

Despliegue en producción con Docker

# Construir imágenes y arrancar servicios
make up

# Solo construir
./scripts/deploy.sh build

# Solo arrancar
./scripts/deploy.sh start

# Detener
make down

Requisitos de hardware

Recomendaciones de seguridad

• Lista blanca de IPs: usa iptables o firewalls hardware con ACLs
• Gateway de autenticación: configura un proxy inverso (nginx) con autenticación fuerte
• Aislamiento de red: coloca DeerFlow y los dispositivos de confianza en la misma VLAN dedicada
• Worker único: el Gateway mantiene el estado en proceso — no uses múltiples workers sin un stream bridge compartido
• Seguir actualizaciones: mantente al día con las novedades de seguridad de DeerFlow