Tutorial de DeepSeek Harness: primeros pasos con el agente de IA open source más popular

¿Por qué es popular DeepSeek Harness?

DeepSeek Harness ha ganado tracción muy rápido, superando los 160.000 estrellas en GitHub y 18.000 forks en el momento de publicar este artículo.

Una de las razones es que los desarrolladores están logrando buenos resultados con distintos modelos, no solo con DeepSeek. En Reddit, muchos comentan que les funciona bien con modelos como Qwen3.8-27b, especialmente para programar y para tareas agentivas largas.

Otra razón es su autonomía y flexibilidad. Los usuarios comentan que Harness es capaz de completar tareas de varios pasos, recuperarse de errores, gestionar contextos largos y seguir sin necesitar intervención constante. Su diseño basado en plugins también facilita cambiar de modelo, añadir herramientas y personalizar el flujo del agente en lugar de quedar atado a una configuración fija.

Si estás comparando Harness con las herramientas a las que pretende competir, nuestra guía de alternativas a Claude Code pone frente a frente siete de las opciones principales.

Funciones clave de DeepSeek Harness

Estas son algunas de las funciones principales:

• Arquitectura basada en plugins: la mayoría de partes del agente se pueden ampliar o sustituir mediante plugins, lo que facilita personalizar tu configuración.

• Web UI local: al ejecutar dsh web obtienes una interfaz en el navegador donde gestionar modelos, sesiones, espacios de trabajo, ajustes y agentes.

• SDK de Python: deepseek-harness-sdk te permite ejecutar agentes de Harness directamente desde aplicaciones, scripts, tests y flujos de automatización en Python.

• Varios proveedores de modelos: no estás limitado a los modelos de DeepSeek. Puedes usar proveedores como OpenAI y Anthropic o conectar tu propio endpoint compatible.

• Llamadas a herramientas: los agentes pueden llamar a herramientas para realizar acciones, no solo generar texto.

• Herramientas de archivos y terminal: Harness incluye herramientas para leer, buscar y editar archivos, además de Bash en Linux y macOS y PowerShell en Windows.

• Búsqueda web integrada: el proveedor de búsqueda web de DeepSeek está incluido en la configuración por defecto y usa la misma clave de la API de DeepSeek que el modelo.

• Code Mode: Harness puede exponer herramientas mediante un modo de ejecución basado en código, dando al agente más control sobre cómo combina y ejecuta llamadas a herramientas.

• Trajectory: la vista Trajectory te permite inspeccionar paso a paso qué hace el agente, incluidas respuestas del modelo, llamadas a herramientas, actividad anidada, tiempos y uso de tokens.

• Preajustes de agente: puedes crear distintas configuraciones de agente con sus propias herramientas y prompts y usarlas en diferentes sesiones.

• Estadísticas de sesión: Harness registra datos útiles como turnos, pasos, tiempo de modelo, tiempo de herramientas, tiempo hasta el primer token y tiempo de decodificación.

• Subagentes: un agente principal puede delegar partes de una tarea en agentes hijos, útil para flujos de trabajo más complejos.

• Plugins de la comunidad: los plugins de terceros pueden añadir capacidades que no están en el modelo base. En esta guía usamos ModLens para añadir visión.

• Licencia MIT: DeepSeek Harness es open source y se publica bajo la permisiva licencia MIT.

La gran ventaja es que no te ata a un modelo, un conjunto de herramientas o un tipo de agente. Puedes empezar con la configuración por defecto e ir añadiendo o sustituyendo componentes a medida que pruebes distintos flujos de trabajo.

¿Cómo configuro DeepSeek Harness?

Empecemos instalando DeepSeek Harness y preparando todo lo necesario para el resto de la guía. Instalaremos Node.js, DeepSeek Harness y pnpm y después añadiremos nuestras claves de API.

Instala Node.js

DeepSeek Harness se ejecuta sobre Node.js. Como más adelante usaremos ModLens para visión, te recomiendo Node.js 22.19 o superior.

Si usas Ubuntu o Debian, puedes instalar Node.js con:

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - && sudo apt-get install -y nodejs

Una vez instalado, comprueba que Node.js y npm funcionan:

node --version
npm --version

En mi equipo obtuve:

v24.19.0
11.17.0

No hace falta que tengas exactamente las mismas versiones. Mientras uses una versión reciente de Node.js, te servirá.

Instala DeepSeek Harness

A continuación, instalemos el propio DeepSeek Harness.

El inicio rápido oficial usa npx, pero yo prefiero instalarlo globalmente para poder usar el comando dsh en toda la guía.

Ejecuta:

npm install -g @deepseek-ai/dsh

Luego, comprueba que se ha instalado correctamente:

dsh --version

En el momento de probar esta guía, usaba:

0.1.0-rc.7

Instala pnpm

También necesitamos pnpm. DeepSeek Harness lo usa cuando añadimos o quitamos plugins. Instálalo globalmente:

npm install -g pnpm

Configura las claves de API

Para este tutorial, solo necesitamos dos claves de API:

• Clave de la API de DeepSeek: se usa para el modelo de DeepSeek y su búsqueda web integrada.
• Clave de la API de Gemini: la usa ModLens para comprender imágenes.

Ahora configuraremos la clave de DeepSeek, que es lo único necesario para programar y buscar en la web, y más tarde añadiremos la clave de Gemini cuando integremos visión con ModLens.

Para DeepSeek, tendrás que crear una cuenta, generar una clave de API y añadir saldo. Para esta guía, te recomiendo añadir al menos 2 $ de crédito; debería ser más que suficiente para probar los ejemplos sin adelantar una gran cantidad.

Cuando tengas la clave de API, añádela a tu entorno.

En Linux o macOS:

export DEEPSEEK_API_KEY="your_deepseek_api_key"

En Windows PowerShell:

$env:DEEPSEEK_API_KEY="your_deepseek_api_key"

Una ventaja de esta configuración es que no necesitamos una API de búsqueda web aparte. DeepSeek Harness ya incluye el proveedor de búsqueda web de DeepSeek y usa la misma DEEPSEEK_API_KEY.

También puedes añadir tu clave de la API de DeepSeek más tarde desde Settings → Models en la Web UI.

¿Cómo arranco DeepSeek Harness?

Ahora que está todo configurado, podemos iniciar DeepSeek Harness y abrir la Web UI. Simplemente ejecuta dsh web, que arranca la interfaz del navegador en el puerto 3080 por defecto.

Verás la interfaz al abrir la dirección http://127.0.0.1:3080 en tu navegador.

Desde ahí, crea un nuevo espacio de trabajo o selecciona uno existente, inicia una sesión nueva y elige el modelo de DeepSeek que quieras usar.

Cuando la sesión esté lista, podremos empezar a probar programación, búsqueda web, visión y compatibilidad con modelos de terceros.

Cómo usar DeepSeek Harness para programar

Ahora que DeepSeek Harness está en marcha, probemos las capacidades principales de nuestra configuración. Empecemos con una tarea sencilla de código:

Crea una calculadora sencilla en Python con interfaz de línea de comandos.

DeepSeek Harness puede trabajar directamente con archivos y con el terminal, así que puede crear el archivo de Python, editar el código y ejecutar comandos dentro del espacio de trabajo.

Cuando termine la tarea, deberías ver el archivo generado y las instrucciones para ejecutarlo.

Para sacarle más partido a los modelos de DeepSeek que impulsan Harness, nuestro tutorial del DeepSeek V4 API repasa los modos de razonamiento V4 y los parámetros de la API en Python.

Cómo usar DeepSeek Harness para búsqueda web

Ahora probemos la búsqueda web. No hace falta configurar nada más porque DeepSeek Harness ya incluye el proveedor de búsqueda web de DeepSeek.

Prueba con un prompt como:

Busca en la web los últimos lanzamientos de modelos de IA open source y resume los tres principales a fecha de 18 de agosto de 2026.

El agente debería buscar en la web y devolver un resumen con fuentes.

Mientras trabaja, abre la pestaña Trajectory. Deberías ver llamadas a herramientas como SUBTOOL: web_search.

Esto muestra que el agente está usando realmente la herramienta de búsqueda web en lugar de apoyarse solo en el conocimiento previo del modelo. Por defecto, esta búsqueda la gestiona el proveedor deepseek-official y utiliza la misma DEEPSEEK_API_KEY que configuramos antes.

Cómo usar DeepSeek para tareas de visión

El modelo de chat de DeepSeek en Harness es solo de texto, así que no puede comprender imágenes subidas por sí mismo. Para añadir soporte de visión, usaremos ModLens, que actúa como puente entre DeepSeek y un modelo con capacidades de visión.

Instala el plugin ModLens

Cuando subes una imagen, ModLens la procesa con un modelo de visión, extrae la información visual útil y se la devuelve a DeepSeek para que pueda razonar sobre ella.

Empieza instalando el plugin ModLens en el perfil web:

dsh plugin --profile web add @liustack/modlens@3.20.0

Una vez instalado, ModLens añade la herramienta modlens_read_image y crea opciones de modelo como ``DeepSeek-V4-Flash (modlens vision)`.

Estas variantes te permiten subir imágenes manteniendo DeepSeek como modelo principal de razonamiento.

Registra tu backend de visión

En esta guía usaremos la API de Gemini como backend de visión, así que necesitamos una clave de la API de Gemini. Puedes empezar con el Free Tier de Gemini. Google ofrece acceso gratuito a los modelos compatibles dentro de los límites del Free Tier, por lo que no necesitas añadir un método de pago solo para probar la configuración de visión de esta guía.

Cuando tengas tu clave, añádela a tu entorno.

En Linux o macOS:

export GEMINI_API_KEY="your_gemini_api_key"

En Windows PowerShell:

$env:GEMINI_API_KEY="your_gemini_api_key"

Instala y configura la CLI de ModLens

Después, instala la CLI de ModLens:

npm install -g @liustack/modlens

Luego configúrala usando la clave de la API de Gemini.

En Linux o macOS:

modlens config set gemini-api.apiKey "$GEMINI_API_KEY"
modlens config set provider gemini-api

En Windows PowerShell:

modlens config set gemini-api.apiKey "$env:GEMINI_API_KEY"
modlens config set provider gemini-api

Por último, comprueba que todo funciona:

modlens doctor

Deberías ver gemini-api seleccionado como proveedor y en estado listo.

Probar DeepSeek Harness con ModLens

Ahora probemos la comprensión de imágenes.

En el selector de modelos, elige uno de los que incluyen (modlens vision) en el nombre, por ejemplo, DeepSeek-V4-Flash (modlens vision).

Pega o sube una imagen y pregunta: Explica qué se muestra en esta imagen.

Como se ve en el ejemplo, ahora DeepSeek puede describir y razonar sobre la imagen subida.

Detrás de escena, ModLens envía la imagen a Gemini para la parte visual y devuelve a DeepSeek la información extraída. Así mantenemos DeepSeek como modelo principal de razonamiento y usamos Gemini solo para visión.

Cómo usar DeepSeek Harness con un modelo de terceros

Por último, probemos un modelo de otro proveedor. Abre Settings → Models.

Desde aquí, puedes añadir proveedores como OpenAI y Anthropic, o configurar otro proveedor compatible usando tus credenciales de API.

También puedes añadir un proveedor personalizado si quieres conectar un modelo autoalojado u otro endpoint compatible. Esto te permite definir el ID del proveedor, la URL base, el tipo de API, las credenciales y el nombre del modelo.

Una vez añadido el proveedor, vuelve a tu sesión y selecciona el nuevo modelo en el selector.

Por ejemplo, prueba con este prompt:

Crea una app de tareas en la línea de comandos con Python que permita añadir, listar, completar y borrar tareas, guardándolas localmente en un archivo JSON.

El ejemplo anterior usa un modelo de terceros Kimi-K3 para completar la tarea de programación, demostrando que DeepSeek Harness no se limita a los modelos de DeepSeek.

Puedes cambiar entre los modelos configurados directamente desde el selector, y los cambios se aplican a tu siguiente petición sin reiniciar el servidor de Harness.

Reflexiones finales

Tras probar DeepSeek Harness, sigo prefiriendo Pi Coding Agent y OpenCode para mis propios flujos.

DeepSeek Harness me recuerda mucho a Pi Coding Agent porque ambos se basan en un ecosistema de plugins. Puedes instalar distintas extensiones y darle a tu agente de código capacidades extra según lo que necesites. Esa flexibilidad es útil, pero en mis pruebas sigo sin entender del todo el hype en torno a DeepSeek Harness. La experiencia general me pareció bastante normal en comparación con otros agentes de código que ya he usado.

También me encontré con varios detalles frustrantes. A veces el agente se detenía a mitad de una tarea sin explicar por qué y tenía que escribir continue para que siguiera. Instalar y configurar plugins fue otro punto débil: puede ser complicado si no sabes exactamente lo que haces, y la documentación por ahora no ayuda mucho.

Dicho esto, DeepSeek Harness sigue siendo un producto muy nuevo, así que es comprensible. Espero que la experiencia, la documentación y el ecosistema de plugins mejoren bastante con el tiempo. También es posible que DeepSeek esté creando un harness que encaje especialmente bien con sus propios modelos, y eso podría explicar parte del entusiasmo.