Tutorial de DeepSeek Harness: primeros pasos con el agente de IA de código abierto más popular

¿Por qué es popular DeepSeek Harness?

DeepSeek Harness ha ganado tracción muy rápido, superando las 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 largas con agentes.

Otra razón es su autonomía y flexibilidad. Los usuarios comentan que Harness puede avanzar en tareas de varios pasos, recuperarse de errores, gestionar contextos largos y continuar sin intervención constante. Además, su diseño basado en plugins facilita cambiar de modelo, añadir herramientas y personalizar el flujo del agente en lugar de quedar atado a una configuración única.

Si estás comparando Harness con las herramientas a las que pretende plantar cara, nuestra guía de alternativas a Claude Code compara, una a una, 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 las 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 para 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 automatizaciones en Python.

• Múltiples 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.

• Llamada a herramientas: los agentes pueden llamar a herramientas para realizar acciones en lugar de 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 viene incluido 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 lo que 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 reutilizarlas en diferentes sesiones.

• Estadísticas de sesión: Harness registra información útil 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 más complejos.

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

• Licencia MIT: DeepSeek Harness es de código abierto y se publica bajo la permisiva licencia MIT.

La gran ventaja es que no quedas atado a un único modelo, un único conjunto de herramientas o un único tipo de agente. Puedes empezar con la configuración por defecto e ir añadiendo o sustituyendo componentes a medida que experimentas con distintos flujos.

¿Cómo configuro DeepSeek Harness?

Empecemos instalando DeepSeek Harness y preparando todo lo que necesitaremos 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 usar 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 tanto Node.js como npm funcionan:

node --version
npm --version

En mi equipo obtuve:

v24.19.0
11.17.0

No necesitas tener exactamente las mismas versiones. Mientras uses una versión de Node.js lo bastante reciente, todo debería ir bien.

Instala DeepSeek Harness

A continuación, instalemos el propio DeepSeek Harness.

La guía rápida oficial usa npx, pero prefiero instalarlo globalmente para poder usar el comando dsh durante toda la guía.

Ejecuta:

npm install -g @deepseek-ai/dsh

Luego verifica que se instaló correctamente:

dsh --version

Cuando probé esta guía, estaba usando:

0.1.0-rc.7

Instala pnpm

También necesitamos pnpm. DeepSeek Harness lo utiliza 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.

Configuraremos ahora la clave de DeepSeek, ya que es todo lo que necesitamos para programar y buscar en la web, y añadiremos la clave de Gemini más tarde cuando activemos la 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 sobrar para probar los ejemplos sin tener que ingresar una cantidad grande al principio.

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"

Algo conveniente 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 adelante desde Settings → Models dentro de la Web UI.

¿Cómo inicio DeepSeek Harness?

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

Verás la UI cuando abras la dirección http://127.0.0.1:3080 en tu navegador.

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

Con la sesión lista, podemos empezar a probar la programación, la búsqueda web, la visión y el soporte de modelos de terceros.

Cómo usar DeepSeek Harness para programar

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

Create a simple Python calculator with a command-line interface.

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.

Al terminar 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 de la API de DeepSeek V4 repasa los modos de razonamiento de V4 y los parámetros de la API en Python.

Cómo usar DeepSeek Harness para buscar en la web

Ahora probemos la búsqueda web. No hace falta configuración adicional porque DeepSeek Harness ya incluye el proveedor de búsqueda web de DeepSeek.

Prueba con un prompt como:

Search the web for the latest open-source AI model releases and summarize the top three as of August 18, 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 realmente está usando la herramienta de búsqueda web en lugar de basarse solo en el conocimiento previo del modelo. Por defecto, esta búsqueda la gestiona el proveedor deepseek-official y usa 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 entender 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 capacidad 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 razone 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 de modelo te permiten subir imágenes manteniendo DeepSeek como modelo principal de razonamiento.

Registra tu backend de visión

Para esta guía usaremos la API de Gemini como backend de visión, así que necesitamos una clave de API de Gemini. Puedes empezar con el Free Tier de la API de Gemini. Google ofrece acceso gratuito a los modelos compatibles dentro de los límites del Free Tier, así 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

Ahora, 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 luego pide: Explain what is shown in this image.

Como ves en el ejemplo, DeepSeek ya puede describir y razonar sobre la imagen subida.

Por detrás, ModLens envía la imagen a Gemini para la comprensión visual y devuelve la información extraída a DeepSeek. Esto nos permite mantener DeepSeek como modelo principal de razonamiento y usar Gemini solo para la parte de 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 de modelos compatible usando tus propias credenciales de API.

También puedes añadir un proveedor personalizado si quieres conectar un modelo autoalojado u otro endpoint compatible. Esto te permite configurar detalles como 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 este prompt:

Create a Python command-line to-do app that lets users add, list, complete, and delete tasks, with tasks saved locally in a JSON file.

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

Puedes cambiar entre los modelos configurados directamente desde el selector; los cambios se aplican a tu siguiente solicitud 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 extensiones y dar capacidades extra a tu agente de código según lo que necesites. Esa flexibilidad es útil, pero en mis pruebas sigo sin entender del todo el revuelo en torno a DeepSeek Harness. La experiencia general me pareció bastante normal comparada con otros agentes de código que ya he usado.

También me topé con algunos problemas frustrantes. A veces el agente se detenía a mitad de una tarea sin decir por qué y tenía que escribir continue para que siguiera. Instalar y configurar plugins fue otro punto débil. Puede ser bastante difícil 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é construyendo un harness que funcione especialmente bien con sus propios modelos, y eso podría explicar parte de la emoción.