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.

DependenciaRequisito
Python3.10 o superior
GitInstalado
Sistema operativoLinux x64, Linux arm64, o arm64 de macOS 14+
Endpoint de APIEndpoint de API compatible con DeepSeek y credenciales
Espacio de trabajoUn 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

# Equivalente al archivo: examples/jsonrpc-agent/minimal.py
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

# Primera llamada: exporta una variable en ejemplo-workspace
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.

AtributoValor
Mensaje de sistemaDSH_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 modeloSolo bash persistente y str_replace_editor
Tiempo de espera de Bash300 segundos
Límite de salida del editor16,000 caracteres
Compresión de contextoDesactivada
Sistema de archivosBackend local puro; el editor utiliza rutas absolutas y puede acceder a cualquier ruta visible para el proceso del runtime
Persistencia de sesiónJSONL 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.

Python SDK 调用流程图


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.

  1. ¿Qué se conserva al reutilizar el mismo session id?
  2. ¿En qué casos se debe usar un session id nuevo?
  3. ¿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