Llamada al SDK de Python de DeepSeek Harness
La interfaz web es adecuada para que una persona la observe, pero cuando necesitas llamarla desde un programadshlo que necesitas es el SDK.
Este capítulo presenta el SDK de Python: cómo instalarlo, cómo ejecutar el ejemplo incluido en el repositorio y cómo llamarlo desde tu propio programa.
¿Qué problema resuelve el SDK de Python?
El SDK convierte dsh en una llamada dentro de tu programa, en lugar de una página en el navegador.
DeepSeekHarnesses la clase central del SDK de Python y utiliza un administrador de contexto para gestionar el ciclo de vida del runtime.
Al entrar en el bloque with, inicia el runtime integrado de forma diferida; al salir, lo libera automáticamente; en el medio, se puede llamar a run repetidamente.
Escenarios adecuados: tareas por lotes, integrar dsh en tu propio producto y controlar al Agent en pruebas.
Una vez instalado el SDK, el runtime no requiere que el sistema proporcione Node.js; el propio proceso de Python lleva una copia consigo.
Requisitos previos
El SDK tiene requisitos claros para el sistema; verifícalos primero.
| Dependencia | Requisito |
|---|---|
| Python | 3.10 o superior |
| Git | Instalado |
| Sistema operativo | Linux x64, Linux arm64, o arm64 de macOS 14+ |
| Endpoint de API | Endpoint de API compatible con DeepSeek y credenciales |
| Espacio de trabajo | Un workspace aislado que el agent puede modificar |
Instalación del SDK
Clona el repositorio para obtener los ejemplos ejecutables, crea un entorno virtual y luego instala el SDK junto con el runtime integrado de la misma versión.
$ 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 entorno virtual aísla el SDK de los demás paquetes de Python del sistema; es el enfoque recomendado oficialmente.
El runtime instalado no requiere que el sistema proporcione Node.js.
Ejecutar el ejemplo incluido en el repositorio
El repositorio incluye un ejemplo minimal.py; ejecutarlo correctamente equivale a validar toda la cadena del SDK.

Primero, establece las credenciales en el entorno.
$ export DEEPSEEK_API_KEY=sk-your-key-here # export DEEPSEEK_BASE_URL=http://127.0.0.1:8000/v1 # export DSH_MODEL=deepseek-v4-flash # export DSH_SYSTEM_PROMPT='You are a helpful software engineer assistant.'
Si el modelo no lo proporciona el endpoint predeterminado de DeepSeek, sino un proxy compatible con OpenAI, también debes configurar DEEPSEEK_BASE_URL.
Luego, ejecuta una tarea sobre el workspace aislado y el directorio de sesión.
$ 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 imprimirá la respuesta final del assistant.
El directorio de sesión recibirá registros JSONL que contienen las solicitudes de modelo ensambladas y las llamadas a herramientas.
Usar el SDK en tu propio programa
El ejemplo incluido en el repositorio es en realidad un envoltorio ligero de la siguiente llamada al SDK; el núcleo solo tiene dos pasos.
Ejemplo
from pathlib import Path
from deepseek_harness import DeepSeekHarness
# Ruta absoluta del archivo de configuración de la combinación de ejemplo (.cordis.yml describe qué plugins iniciar)
config = Path("examples/jsonrpc-agent/minimal.cordis.yml").resolve()
# El workspace accesible para el agent; debe ser una ruta absoluta
workspace = Path("/absolute/path/to/workspace").resolve()
# Directorio donde se guardan los registros y el estado de la sesión; debe ser una ruta absoluta
sessions = Path("/absolute/path/to/sessions").resolve()
# Administrador de contexto: inicia el runtime integrado de forma diferida al entrar y lo libera automáticamente al salir
with DeepSeekHarness(
provider="deepseek-official", # Utiliza el proveedor oficial de DeepSeek
model="deepseek-v4-flash", # Nombre del modelo; también es el predeterminado del SDK
max_tokens=49_152, # Número máximo de tokens para una sola respuesta
cwd=str(workspace), # Establece el workspace como directorio de trabajo del agent
session_root=str(sessions), # Dónde se escriben los registros de sesión
cordis=str(config), # Con qué configuración de combinación iniciar
) as harness:
# Envía una tarea; session_id se utiliza para identificar esta conversación persistente
result = harness.run(
"Inspect the ejemplo-demo repository and fix the failing tests.",
session_id="example-001",
)
# Imprime la respuesta final del assistant
print(result.final_response)
DeepSeekHarness inicia el runtime integrado de forma diferida y lo reutiliza continuamente hasta salir del administrador de contexto.
El mismo harness puede llamar a run varias veces dentro del bloque with; el runtime solo se inicia una vez.
Reutilizar el session id: conservar el proceso de Bash
Esta es la regla del SDK que más se pasa por alto y, a la vez, la más útil.
Reutilizar el mismo harness y session id conservará el proceso de Bash que posee esa sesión.
Incluyendo su directorio de trabajo, las variables exportadas y las funciones de shell; todo se mantiene para la siguiente llamada.
Ejemplo
result = harness.run(
"Run `cd /repo && export EJEMPLO_MODE=dev` and confirm.",
session_id="ejemplo-session",
)
print(result.final_response)
# Segunda llamada: al reutilizar el mismo session id, la variable exportada sigue ahí
result = harness.run(
"Print the value of EJEMPLO_MODE.",
session_id="ejemplo-session",
)
print(result.final_response)
Las tareas independientes deben usar un session id nuevo; solo reutiliza el id original cuando la siguiente llamada necesite continuar la misma conversación persistente.
Resumen de la combinación de ejemplo
La combinación de ejemplo detrás de minimal.py es una configuración deliberadamente reducida; veamos elemento por elemento qué hace.
| Atributo | Valor |
|---|---|
| Mensaje de sistema | DSH_SYSTEM_PROMPT; si no se configura, se utiliza "You are a helpful software engineer assistant." |
| Modelo utilizado por minimal.py | --model, luego DSH_MODEL y, por último, deepseek-v4-flash |
| Herramientas disponibles para el modelo | Solo bash persistente y str_replace_editor |
| Tiempo de espera de Bash | 300 segundos |
| Límite de salida del editor | 16,000 caracteres |
| Compresión de contexto | Desactivada |
| Sistema de archivos | Backend local puro; el editor utiliza rutas absolutas y puede acceder a cualquier ruta visible para el proceso del runtime |
| Persistencia de sesión | JSONL sin comprimir en DSH_SESSION_ROOT |
Esta combinación omite plugins como la identidad del harness, el texto de mensaje del workspace, skill, Bash desechable, herramientas de tarea y compresión de contexto.
El flujo de llamada general es el siguiente.
Los límites de danger-full-access
Esta combinación de ejemplo usa el ajuste preestablecido de permisos danger-full-access; debes tener claros sus límites.
danger-full-access solo puede ejecutarse dentro de un checkout o contenedor desechable.
Bash y el editor pueden modificar cualquier ruta a la que el proceso del runtime tenga acceso; no hay sandbox como respaldo.
El backend PTY persistente requiere un entorno de terminal POSIX, por lo que esta combinación no admite agent de Windows.
En otras palabras, antes de usarlo con un proyecto real, asegúrate de que no te importe si este entorno se daña.
Resumen y autoevaluación
Resumen en una frase: el SDK de Python envuelve el runtime con el administrador de contexto DeepSeekHarness y envía tareas con run(prompt, session_id).
Verifica tu comprensión con tres pequeñas preguntas.
- ¿Qué se conserva al reutilizar el mismo session id?
- ¿En qué casos se debe usar un session id nuevo?
- ¿Qué herramientas expone minimal.py al modelo de forma predeterminada?
Respuesta de referencia: se conserva el proceso de Bash de esa sesión, incluidos el directorio de trabajo, las variables exportadas y las funciones de shell.
Las tareas independientes usan un id nuevo; solo se reutiliza cuando se necesita continuar la misma conversación persistente.
Solo las dos herramientas: bash persistente y str_replace_editor.
Otras extensiones