- Resolver fallos comunes sin ampliar permisos.
- Diseñar logs útiles y minimizados.
- Definir criterios de parada y rollback.
Diagnóstico ordenado
Cuando una sesión falla, no aumentes el modelo, el contexto y los permisos a la vez. Aísla una variable: configuración, proveedor, herramienta, permisos, prompt o datos de entrada.
- El agente no encuentra archivos: revisa la ruta y el workspace.
- Da respuestas pobres: reduce la tarea, aporta contexto verificable y compara modelo.
- Falla una herramienta: ejecuta su versión manual antes de delegarla.
- Se bloquea o repite: define límite de turnos y condición de salida.
SDK Python para uso programático
La guía oficial presenta el SDK como alternativa programática a la Web UI. Instala `deepseek-harness-sdk`, ejecuta un ejemplo versionado y guarda la sesión en JSONL.
El SDK inicia el runtime empaquetado de forma perezosa y lo reutiliza hasta salir del context manager. Reusar el mismo `session_id` conserva conversación y estado de shell; usa uno nuevo para tareas independientes.
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 export DEEPSEEK_API_KEY=sk-your-key-here 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."
Composición mínima del SDK
El ejemplo JSON-RPC usa `DeepSeekHarness` con provider, modelo, cwd, session_root y un archivo Cordis. La composición mínima documentada expone bash persistente y `str_replace_editor`, desactiva compaction y guarda logs sin comprimir.
Ojo: el ejemplo oficial usa `danger-full-access` dentro de su composición. Ejecútalo solo en un checkout desechable o contenedor, especialmente si la tarea puede escribir archivos.
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',
cwd=str(workspace),
session_root=str(sessions),
cordis=str(config),
) as harness:
result = harness.run('Inspect the repository.', session_id='example-001')
print(result.final_response)Operación mínima
Registra lo necesario para reproducir una decisión sin copiar información sensible. Programa revisiones y conserva un interruptor para desactivar automatizaciones.
Registro mínimo: - versión de perfil y modelo - objetivo y resultado - herramientas invocadas - aprobaciones humanas - error y recuperación - referencia al diff o artefacto - fecha de revisión