Guía inicial de DeepSeek Harness: de cero a tu primer agente de IA

Qué cubre este tutorial

DeepSeek Harness (dsh) es una plataforma de agentes de IA de código abierto creada por DeepSeek sobre el sistema de plugins Cordis. En palabras sencillas: te permite dirigir una IA para que lea y modifique archivos de tu ordenador, ejecute comandos y trabaje en proyectos reales, todo guiado por ti.

Este tutorial parte de la base de que no sabes nada: ni terminales, ni Node.js, ni agentes de IA. Explicamos cada concepto antes de usarlo. Al final tendrás el Web UI en marcha, tu modelo configurado y tu primera tarea de agente completada. También cubrimos el modo de línea de comandos (CLI) y el SDK de Python para uso avanzado.

¿Qué versión? Cubre el avance público para desarrolladores lanzado en agosto de 2026 (0.1.0-rc.5) — el mismo código que deepseek.com/harness y el paquete npm @deepseek-ai/dsh.

Tiempo: 30–45 minutos   Dificultad: Principiante

Antes de empezar

¿Cuánto cuesta? El software es gratis y de código abierto (licencia MIT). Solo pagas al proveedor del modelo por el uso de IA, medido por token (un token es aproximadamente una fracción de palabra).

¿Qué es "un agente de IA"?

Un chatbot normal: preguntas, responde. Un agente va más lejos — puede *hacer* cosas: leer archivos, editarlos, ejecutar comandos, buscar en la web y encadenar muchos pasos para lograr el objetivo que describes en lenguaje natural. DeepSeek Harness es el "cuerpo" que da manos al modelo; el modelo es el "cerebro".

¿Qué es "un modelo"?

El "cerebro" de la IA se llama modelo. Los modelos de DeepSeek los fabrica la misma empresa que hizo este harness. Para usar un modelo necesitas dos cosas: un endpoint de API (la "dirección" con la que habla el software) y una clave de API (tu "contraseña personal" para esa dirección, vinculada a tu cuenta de facturación).

¿Qué es "una terminal"?

La terminal (llamada PowerShell en Windows, Terminal en macOS, y Konsole/GNOME Terminal etc. en Linux) es una ventana donde escribes comandos en lugar de hacer clic en botones. Todos los pasos de instalación de este tutorial ocurren ahí. Si nunca la has usado, sigue la sección de abajo.

Cómo abrir una terminal (paso a paso)

Paso 1 — Comprueba Node.js e instálalo si hace falta

La forma más rápida de instalar DeepSeek Harness usa un comando llamado npx, que viene con Node.js. Veamos si Node.js ya está instalado.

En tu terminal, escribe esto y pulsa Enter:

node --version

• Si ves algo como v20.x.x o v22.x.x — Node.js está instalado. Salta al Paso 2.
• Si ves command not found (o node is not recognized en Windows) — no está instalado. Continúa abajo.

Instalar Node.js

Ve a nodejs.org y descarga la versión LTS (la de "soporte a largo plazo" — la opción segura y recomendada). Instálala como cualquier programa: abre el archivo descargado y ve pulsando, manteniendo las opciones por defecto. Tras instalar, cierra y vuelve a abrir tu terminal para que recoja el nuevo software, y ejecuta node --version de nuevo para confirmar.

¿Qué es Node.js? Es un runtime gratuito que permite ejecutar programas de JavaScript en tu ordenador. Muchas herramientas de desarrollo como Harness se distribuyen a través de su gestor de paquetes, npm. No necesitas aprender JavaScript para este tutorial — Node.js simplemente alimenta las herramientas en segundo plano.

Paso 2 — Instala y lanza el Web UI

La línea mágica. En tu terminal, ejecuta:

npx @deepseek-ai/dsh web

¿Qué es `npx`? Cuando ejecutas npx <paquete>, descarga ese paquete (tarda uno o dos minutos la primera vez) y lo ejecuta. Así que esta línea descarga DeepSeek Harness y lo inicia.

Qué debería pasar: verás texto de registro, y una línea que dice algo como:

DeepSeek Harness is running at: http://127.0.0.1:3080

Ese http://127.0.0.1:3080 es la dirección del Web UI de Harness en tu propio ordenador. Mantén abierta esta ventana de terminal — el servidor sigue corriendo mientras esté abierta.

Ahora abre tu navegador (Chrome, Edge, Safari…) y ve a esa dirección: http://127.0.0.1:3080. Verás la pantalla de bienvenida de DeepSeek Harness.

¿Qué significa `127.0.0.1`? Es la dirección universal de "este ordenador" — como un número de teléfono para tu propia máquina. La parte :3080 es el puerto, como una extensión. Esta dirección solo funciona en tu máquina; nadie más puede alcanzarla.

Alternativa: ejecutar desde el código fuente

Si prefieres el código más reciente, clona el repositorio y construye (requiere pnpm, el hermano rápido de npm):

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

Paso 3 — Consigue una clave de API de DeepSeek (si no tienes)

Para que Harness hable con un modelo real necesitas una clave. Una clave es una cadena secreta larga — piensa en ella como una contraseña para el uso de IA.

1. 1Ve a platform.deepseek.com (la plataforma de desarrolladores de DeepSeek) e inicia sesión o crea una cuenta.
2. 2Encuentra la página API Keys en tu cuenta.
3. 3Haz clic en Create API key (o similar), copia la clave y guárdala en un sitio seguro — no podrás verla completa de nuevo tras salir de la página.

Mantén esta clave privada. Quienquiera que la tenga puede gastar tu cuota (y en la mayoría de casos, tu dinero).

Paso 4 — Configura el modelo en el Web UI

El Web UI inicia sin ningún modelo configurado. Los cambios de modelo surten efecto en la siguiente solicitud — sin reiniciar el servidor.

1. 1En el Web UI de Harness (http://127.0.0.1:3080), abre Configuración → Modelos.
2. 2Encuentra la tarjeta DeepSeek y pega tu clave de API de DeepSeek.
3. 3Haz clic en Guardar.

La ruta DeepSeek queda disponible inmediatamente.

Por seguridad, la clave se almacena de solo escritura: tras guardar, el UI solo muestra un descriptor enmascarado, y el secreto real vive en $DSH_HOME/.credentials.yaml (un archivo privado en tu directorio de inicio).

Añadir otros proveedores

También puedes usar modelos de otras empresas — por ejemplo Anthropic u OpenAI:

• Proveedores de catálogo — haz clic en Añadir proveedor y elige Anthropic, OpenAI u otro del catálogo instalado. Endpoint, protocolo y lista de modelos vienen preconfigurados.
• Proveedores personalizados — haz clic en Añadir un proveedor personalizado para una pasarela corporativa, servidor autohospedado o endpoint compatible con OpenAI. Proporciona un Provider ID en minúsculas (permanente), URL base, protocolo API, una credencial y al menos un modelo. Usa Obtener modelos disponibles para sondear el endpoint antes de guardar.

Proveedores de credencial nativa — Bedrock, Vertex, Azure y Codex necesitan sus propias credenciales nativas (clave AWS + región, proyecto ADC, api-version, OAuth). Solo escribir una clave en el campo genérico no los configura.

Modelos de visión en un proveedor personalizado

Un modelo introducido a mano se trata como solo texto hasta que diga lo contrario. Para declarar soporte de imagen en un proveedor personalizado, edita $DSH_HOME/settings.yaml:

llm-pi-ai:
  providers:
    my-gateway:
      apiKeyEnv: GATEWAY_API_KEY
      api: openai-completions
      baseURL: https://gateway.example/v1
      models:
        - id: legacy-chat
        - id: vision-preview
          input: [text, image]

input acepta text y image y se aplica solo a ese modelo. Para un fallback de toda la ruta, usa defaultInput: [text, image] a nivel de proveedor. La ruta chat-completions de DeepSeek es solo texto y no puede configurarse de otro modo.

Paso 5 — Elige un espacio de trabajo

Un Web UI nuevo inicia sin espacio de trabajo seleccionado — hasta que elijas uno, la caja donde escribes tu tarea está desactivada.

¿Qué es un "espacio de trabajo"? Es la carpeta de tu ordenador que el agente puede tocar. Todo lo que hay dentro — archivos, código, documentos — puede leerse, editarse o ejecutarse. Mantenlo en una carpeta de proyecto de confianza, no en todo tu ordenador.

1. 1Haz clic en Elegir espacio de trabajo en el UI.
2. 2Añade el directorio del proyecto donde lanzaste dsh.
3. 3Selecciónalo.

Ahora la caja de entrada se ilumina y estás listo.

Paso 6 — Ejecuta tu primera tarea de agente

1. 1Haz clic en Iniciar sesión (o usa la caja de mensajes directamente).
2. 2Envía un prompt. Una buena primera tarea para una carpeta nueva:

> Summarize this repository and identify its main packages.

(Si tu carpeta está vacía o no es un proyecto, prueba algo como: *Crea un archivo llamado hello.txt con "Hello from DeepSeek Harness!" dentro.*)

1. 1Observa al agente trabajar. Puede:

• Leer y editar archivos del espacio de trabajo
• Ejecutar comandos de shell (con un proceso Bash persistente)
• Delegar trabajo a sub-agentes
• Mantener un plan conforme avanza

Bajo la política de permisos activa, el Web UI pedirá aprobación antes de cualquier operación que lo requiera — borrar un archivo, instalar un paquete, etc. Esto es normal y deliberado; ve aprobando una a una.

Los cuatro modos de agente

Usa el selector de modos del editor de sesión:

La vista Trajectory

Cada interacción del modelo — prompt del sistema, pensamiento, llamadas de herramientas, resultados, despacho de sub-agentes, inyecciones de contexto — se registra como una corriente de eventos de solo añadido en el registro de sesión. La vista Trajectory te permite inspeccionarla por fuente, y el mismo registro impulsa la recuperación, bifurcación, búsqueda y repetición completa. Perfecta para saber exactamente qué hizo el agente y por qué.

Paso 7 — Ir más lejos: CLI headless

Además del Web UI, dsh expone un modo de entrada headless para scripting y CI — un comando que ejecuta una tarea de principio a fin sin navegador, imprime la respuesta final y sale:

dsh --profile headless "Inspect the repository and fix the failing tests."

El perfil headless se auto-inicializa al primer uso desde la plantilla incluida.

El lanzador soporta cuatro modos de entrada:

¿Qué es un "perfil"? Una configuración con nombre: qué plugins, modelos y ajustes usar. El directorio de perfil contiene un package.json (con dependencias de plugin fuera de árbol y el manifiesto dsh.profile) y un cordis.patch.yml (tu propia capa de parche). El árbol compuesto fusiona, en orden:

1. 1el parche de cada bundle en el orden de dsh.profile.bundles
2. 2el cordis.patch.yml del perfil
3. 3el $DSH_HOME/cordis.patch.yml de nivel de home
4. 4las superposiciones --patch

Usa --dump-default-config y --dump-config para inspeccionar el árbol sin arrancarlo.

Paso 8 — SDK de Python (para programadores)

Si escribes Python y quieres incrustar un agente en tu propio programa, DeepSeek publica un SDK oficial.

Requisitos previos

• Python 3.10 o superior
• Linux x64/arm64 o macOS 14+ en arm64
• Git (para obtener el ejemplo)

Instalar

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
python -m venv .venv
. .venv/bin/activate
python -m pip install deepseek-harness-sdk

El runtime instalado incluye su propio Node.js — sin necesidad de Node.js de sistema.

Configurar credenciales

export DEEPSEEK_API_KEY="sk-…"
# export DEEPSEEK_BASE_URL=http://127.0.0.1:8000/v1     # con un proxy
# export DSH_MODEL=deepseek-v4-flash
# export DSH_SYSTEM_PROMPT='You are a helpful software engineer assistant.'

Ejecutar el ejemplo incluido

python examples/jsonrpc-agent/minimal.py \
  --workspace /absolute/path/to/workspace \
  --session-root /absolute/path/to/sessions \
  --session-id example-001 \
  "Inspect the repository and fix the failing tests."

El script imprime la respuesta final. El session-root recibe un registro JSONL con las solicitudes de modelo y llamadas de herramientas.

Usar el SDK en tu propio programa

from pathlib import Path
from deepseek_harness import DeepSeekHarness

config    = Path("examples/jsonrpc-agent/minimal.cordis.yml").resolve()
workspace = Path("/absolute/path/to/workspace").resolve()
sessions  = Path("/absolute/path/to/sessions").resolve()

with DeepSeekHarness(
    provider     = "deepseek-official",
    model        = "deepseek-v4-flash",
    max_tokens   = 49_152,
    cwd          = str(workspace),
    session_root = str(sessions),
    cordis       = str(config),
) as harness:
    result = harness.run(
        "Inspect the repository and fix the failing tests.",
        session_id="example-001",
    )

print(result.final_response)

DeepSeekHarness inicia el runtime incluido de forma perezosa y lo reutiliza hasta que el gestor de contexto sale. Reutilizar el mismo harness y el mismo session id preserva el proceso Bash de la sesión, su directorio de trabajo, variables exportadas y funciones de shell. Usa un session id nuevo para tareas independientes; reutiliza un id solo para continuar la misma conversación duradera.

Entender la composición del ejemplo

Nota: esta composición omite la identidad del harness, el texto de prompt del espacio de trabajo, las habilidades, Bash de un solo uso, herramientas de tarea, compresión y todos los demás plugins frente al modelo. Usa danger-full-access, así que ejecútalo solo en un clon desechable o contenedor. El backend PTY persistente requiere un sustrato de terminal POSIX, por lo que esta composición no soporta agentes de Windows.

Solución de problemas

Siguientes pasos

• Añade más proveedores — Bedrock, Vertex, Azure, Codex y cualquier pasarela compatible con OpenAI vía Configuración → Modelos
• Desarrolla un plugin — la documentación de docs/user/develop/basic/ te guía para crear tu propio plugin Cordis
• Referencia del SDK de Python — python/sdk/README.md cubre ciclo de vida, resultados, notificaciones, selección de runtime y configuración
• Cordis primer — docs/cordis-primer.md explica la sintaxis de composición en el corazón de Harness

Resumen

Pasaste de cero a tener tu propio agente de IA en marcha. En esta guía:

1. 1Aprendiste qué son de verdad una terminal, Node.js, una clave de API, un modelo y un agente
2. 2Instalaste dsh vía npx (o desde el código fuente)
3. 3Creaste una clave de API de DeepSeek y la configuraste en Configuración → Modelos
4. 4Elegiste un espacio de trabajo para tu agente
5. 5Ejecutaste tu primera tarea de agente en una sesión
6. 6Exploraste los cuatro modos y la vista Trajectory
7. 7Ejecutaste una sesión headless vía CLI
8. 8Instalaste y usaste el SDK de Python

Todo en DeepSeek Harness es un plugin — y todo es MIT y gratis. Bienvenido al mundo de los agentes.