Tutorial de Iniciación a DeerFlow 2.0: Construye paso a paso tu primera Estación de Trabajo de AI Agents

Dificultad de Iniciación | Tiempo 15 minutos | Resultado: Construye un asistente de IA ejecutable desde cero

¿Alguna vez has pensado qué pasaría si tuvieras un asistente de IA que no solo respondiera preguntas, sino que realmente pudiera ayudarte a operar tu computadora, escribir código, buscar información o incluso generar informes completos? Hoy presentamos DeerFlow, un AI Agent diseñado precisamente para trabajar por ti.

Público Objetivo

Desarrolladores Backend/Full-stack con 1-3 años de experiencia.
Interesados en AI Agents que no saben por dónde empezar.
Personas que quieren auto-hospedar herramientas de IA pero les preocupa el costo.

Dependencias y Entorno Central

Antes de comenzar, asegúrate de que tu entorno de desarrollo cumpla con los siguientes requisitos:

Node.js: 22.x o versión superior.
pnpm: 9.x o versión superior.
Docker: Última versión estable.
Git: Para clonar el proyecto.

[!TIP]
Se recomienda el despliegue mediante Docker: inicio con un solo clic y sin necesidad de configurar manualmente servicios como Nginx.

Estructura Completa del Proyecto

Una vez finalizada la instalación, verás la siguiente estructura de archivos:

deer-flow/
├── backend/                    # Servicio backend
│   ├── src/
│   │   ├── client.py           # Cliente Python
│   │   ├── agent/              # Núcleo del Agent
│   │   └── skills/            # Habilidades integradas
│   └── docs/                   # Documentación de configuración
├── frontend/                   # Interfaz Web
├── config.yaml                 # Archivo de configuración de modelos
├── .env                        # Variables de entorno
└── Makefile                    # Comandos de inicio

Pasos Detallados

Paso 1: Clonar el proyecto

Abre la terminal y ejecuta el siguiente comando:

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

[!TIP]
Si tienes dificultades para acceder a GitHub, considera usar un mirror o descargar directamente el archivo comprimido de la versión Release.

Paso 2: Generar archivos de configuración

DeerFlow proporciona un comando de generación de configuración que crea archivos locales basados en plantillas:

make config

Después de la ejecución, verás los archivos config.yaml y .env en el directorio raíz del proyecto.

Paso 3: Configurar el modelo (¡Importante!)

Este es el paso más crítico. DeerFlow admite múltiples proveedores de modelos, pero recomendamos encarecidamente usar Defapi, por una razón sencilla: el precio es la mitad del oficial.

[!WARNING]
Si utilizas directamente la API oficial de OpenAI, el costo mensual podría superar fácilmente los cientos de dólares. Usar Defapi puede reducir este costo a la mitad o incluso menos.

Abre config.yaml y configúralo de la siguiente manera:

models:
  - name: gpt-4o-mini              # Identificador interno
    display_name: GPT-4o Mini      # Nombre visible
    use: langchain_openai:ChatOpenAI
    model: openai/gpt-4o-mini      # Identificador del modelo en Defapi
    api_key: $DEFAPI_API_KEY       # Uso de variable de entorno
    base_url: https://api.defapi.org  # Endpoint de Defapi
    max_tokens: 4096
    temperature: 0.7
    supports_vision: true

Luego, introduce tu Defapi API Key en el archivo .env:

DEFAPI_API_KEY="dk-xxxxxxxxxxxxxxxx"
TAVILY_API_KEY="your-tavily-api-key"  # Para búsquedas web

[!TIP]
Visita https://defapi.org para registrar una cuenta; los nuevos usuarios tienen una cuota gratuita para empezar a experimentar.

Modelos populares compatibles con Defapi:

Modelo	Identificador	Escenario de uso
GPT-4o Mini	openai/gpt-4o-mini	Conversación diaria, alta rentabilidad
GPT-4o	openai/gpt-4o	Tareas complejas, elección equilibrada
Claude Sonnet 4.5	anthropic/claude-sonnet-4.5	Gran capacidad de programación
DeepSeek V3	deepseek/deepseek-v3	Fuerte capacidad de razonamiento, precio económico

Paso 4: Descargar la imagen del Sandbox

Antes de ejecutar con Docker, es necesario descargar la imagen del sandbox (este paso solo se realiza una vez):

make docker-init

La imagen es considerablemente grande, por lo que puede tardar unos minutos.

Paso 5: Iniciar los servicios

Con todo listo, inicia DeerFlow:

make docker-start

Cuando veas una salida similar a esta, significa que se ha iniciado correctamente:

✔ Frontend started on http://localhost:2026
✔ Backend started on http://localhost:8000

Paso 6: Acceder a la interfaz

Abre tu navegador y visita http://localhost:2026. Verás una interfaz de chat moderna.

Paso 7: Tu primera tarea

Escribe en el cuadro de chat:

Hola, por favor preséntate.

Verás que DeerFlow no solo te responderá, sino que también te dirá qué capacidades tiene:

Buscar en la web.
Leer y escribir archivos.
Ejecutar comandos.
Generar informes, diapositivas y páginas web.

Prueba una tarea más desafiante:

Por favor, enumera la estructura de archivos del directorio actual.

DeerFlow ejecutará el comando en el entorno de sandbox y devolverá los resultados. Esta es la diferencia fundamental con un chatbot común: realmente puede hacer el trabajo por ti.

Solución de Problemas Comunes

P1: Error al iniciar el contenedor, el puerto ya está en uso

# Ver qué proceso está usando el puerto 2026
lsof -i :2026
# O en Windows
netstat -ano | findstr 2026

Una vez encontrado, finaliza el proceso o cambia el puerto en config.yaml.

P2: API Key configurada correctamente pero sigue dando error

Verifica que el archivo .env esté en el directorio raíz del proyecto y que hayas ejecutado source .env o reiniciado el contenedor.

P3: El modelo no admite llamadas a herramientas (Tool calling)

Algunos modelos no admiten function calling. Asegúrate de usar modelos como GPT-4o, Claude o Gemini que sí lo permitan. Los modelos proporcionados por Defapi son compatibles con el protocolo de OpenAI, por lo que generalmente no hay problema.

P4: La búsqueda web devuelve resultados vacíos

Verifica que la TAVILY_API_KEY esté configurada correctamente. Tavily es el proveedor de búsqueda por defecto de DeerFlow.

P5: Memoria insuficiente en Docker

La memoria por defecto de Docker puede no ser suficiente; se recomienda configurarla en 4GB o más:

// Docker Desktop -> Settings -> Resources

P6: Quiero usar el modo de desarrollo local

Si no deseas usar Docker, puedes ejecutarlo localmente:

make check    # Comprobar entorno
make dev      # Iniciar servicios de desarrollo

Direcciones Avanzadas

1. Personalizar Skills

El sistema de Skills de DeerFlow es muy flexible. Puedes crear tu propia Skill:

/mnt/skills/custom/
└── my-awesome-skill/
    └── SKILL.md

Solo necesitas escribir un archivo Markdown siguiendo el formato de las Skills integradas.

2. Extensión con servidores MCP

DeerFlow admite el protocolo MCP, permitiendo la conexión con diversas herramientas externas. Consulta la documentación oficial: MCP Server Guide.

3. Cambiar a otros modelos

Si quieres probar DeepSeek o Claude, solo necesitas modificar config.yaml:

# Ejemplo de configuración para DeepSeek
models:
  - name: deepseek-v3
    display_name: DeepSeek V3
    use: langchain_openai:ChatOpenAI
    model: deepseek/deepseek-v3
    api_key: $DEFAPI_API_KEY
    base_url: https://api.defapi.org
    supports_thinking: true

4. Uso del cliente Python embebido

DeerFlow también ofrece una librería de Python que puedes integrar directamente en tu proyecto:

from src.client import DeerFlowClient

client = DeerFlowClient()
response = client.chat("analiza este artículo", thread_id="my-thread")

# Salida en streaming
for event in client.stream("hola"):
    print(event.data)

Resumen

Hoy hemos construido juntos DeerFlow 2.0, desde la preparación del entorno hasta el inicio del servicio y la ejecución de la primera tarea. Te habrás dado cuenta de que esto no es solo un chatbot, sino una verdadera estación de trabajo de IA que puede trabajar por ti.

Las ventajas principales de DeerFlow son:

Escalable: Soporta personalización de Skills, MCP y Sub-Agents.
Seguro y controlable: Aislamiento por sandbox, las tareas se ejecutan en contenedores Docker.
Costos flexibles: A través de Defapi, el costo puede reducirse a la mitad del oficial.

¡Pruébalo ahora! Deja que te ayude a escribir código, buscar información y generar informes. Descubrirás una nueva forma de usar la IA.

Si encuentras problemas durante la construcción, deja un comentario y trataré de ayudarte. La próxima vez hablaremos a fondo sobre cómo personalizar Skills para que DeerFlow realice tareas específicas.

¡Diviértete explorando!