Troubleshooting and production operation

Diagnose in order

When a session fails, do not increase model size, context and permissions at the same time. Isolate one variable: configuration, provider, tool, permission, prompt or input data.

• Cannot find files: check the path and workspace.
• Weak answers: narrow the task, add verifiable context and compare models.
• Tool failure: run its manual version before delegating it.
• Loops: set a turn limit and an exit condition.

Python SDK for programmatic use

The official guide presents the SDK as the programmatic alternative to the Web UI. It installs `deepseek-harness-sdk`, runs a checked-in example and stores the session as JSONL.

The SDK starts the bundled runtime lazily and reuses it until the context manager exits. Reusing the same `session_id` preserves conversation and shell state; use a new id for independent tasks.

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."

Minimum SDK composition

The JSON-RPC example uses `DeepSeekHarness` with provider, model, cwd, session_root and a Cordis file. The documented minimal composition exposes persistent bash and `str_replace_editor`, disables compaction and stores uncompressed logs.

Careful: the official example uses `danger-full-access` inside its composition. Run it only in a disposable checkout or container, especially if the task can write files.

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)

Minimum operation

Record enough to reproduce a decision without copying sensitive data. Schedule reviews and keep a kill switch for automations.

Minimum log:
- profile and model version
- objective and outcome
- invoked tools
- human approvals
- error and recovery
- diff or artifact reference
- review date