Python SDK is the Python face of DeepSeek Harness: it drives the bundled harness runtime as a subprocess over newline-delimited JSON-RPC on stdio, so Python code can run agent turns without system Node.js. It ships as two PyPI packages — the client deepseek-harness-sdk and the platform runtime carrier deepseek-harness-runtime-bin — and the wire protocol it speaks is the same one the TypeScript SDK uses.

Package	Dist / module	Role
python/sdk	deepseek-harness-sdk / deepseek_harness	High-level turns API and lower-level JSON-RPC client
python/sdk-runtime	deepseek-harness-runtime-bin / deepseek_harness_runtime	Bundled dsh CLI executable and native sidecars (wheels only)

The client package depends on the exact same-version runtime wheel for the current platform (deepseek-harness-sdk pins deepseek-harness-runtime-bin), so one pip install deepseek-harness-sdk brings both:

python -m pip install deepseek-harness-sdk

How it launches the runtime

The Python SDK has no separate application entrypoint. It starts the matching bundled dsh CLI with --profile sdk; the selected profile owns the JSON-RPC server, agent composition, credentials, persistence, tools, and shutdown behavior. Every launch requires an explicitly selected Harness home — pass dsh_home or provide a non-empty DSH_HOME in the child environment. Python never silently reads ~/.dsh; the runtime wheel's dsh command enforces the same rule and never falls back to ~/.dsh.

from deepseek_harness import DeepSeekHarness

with DeepSeekHarness(
    dsh_home="/absolute/path/to/isolated-dsh-home",
    cwd="/absolute/path/to/workspace",
    provider="deepseek-official",
    model="deepseek-v4-flash",
    reasoning_effort="max",
    max_tokens=49_152,
) as harness:
    result = harness.run("Say hi.", session_id="example-001")

print(result.final_response)

DeepSeekHarness starts lazily and reuses its runtime until close() or context-manager exit. cwd is the agent workspace; runtime_cwd independently selects the subprocess working directory; both become absolute before launch. provider, model, optional reasoning_effort, and optional positive max_tokens are sent during JSON-RPC initialization, while base_url and api_key explicitly override DEEPSEEK_BASE_URL and DEEPSEEK_API_KEY in the child environment. The initial profile handshake has an independent 30-second default bound (initialize_timeout_seconds); ordinary turns remain unbounded unless request_timeout_seconds is set.

The sdk profile and its bundle

Launching with --profile sdk loads @deepseek-ai/dsh-sdk-app (packages/bundle/sdk-app), the SDK stdio application as a profile bundle over dsh-base. Its patch sets the coding-agent persona, mounts an app-owned zero-option command provider, and starts dsh-sdk-jsonrpc-server only after that provider accepts the invocation — so dsh --profile sdk --help writes help and exits without claiming stdin or stdout. Stdout is reserved for newline-delimited JSON-RPC frames. Custom profiles selected by the client must retain @deepseek-ai/dsh-sdk-app or another dsh-sdk-jsonrpc-server row; a profile that omits the server fails initialization when no peer answers.

The shipped sdk-minimal variant (@deepseek-ai/dsh-sdk-minimal) is a standalone explicit tree rather than an overlay on dsh-base. It provides a persistent shell, the string-replace editor, local execution, and JSONL sessions; settings, managed credentials, telemetry, Web tools, and the full default tool roster remain available through the separate full sdk and web profiles. The runnable minimal example (python/sdk/examples/minimal.py) selects sdk-minimal by default.

Persistent customization belongs to a dsh profile — initialize the shipped profile and install an external bundle with the runtime wheel's dsh command; its $DSH_HOME/profiles/sdk/cordis.patch.yml is the persistent user patch. For an invocation-specific change, pass one or more patch files, which are forwarded in order after the profile and home patch layers.

Client modules

The deepseek_harness package is the import surface (python/sdk/src/deepseek_harness/):

Module	Contents
__init__.py	Re-exports the public API: DeepSeekHarness, DeepSeekHarnessConfig, Session, RunResult, HarnessClient, HarnessConfig
api.py	The high-level turns API — launching, profiles, patches, and the context-managed runtime
client.py	HarnessClient — the lower-level newline-delimited JSON-RPC client
models.py	Wire types such as RunResult, Session, and event/notification shapes
errors.py	Protocol and launch errors (e.g. SdkProtocolError for a malformed turn/end)

Session.run() owns an activity interval from its prompt's durable inbox receipt through the next whole-agent idle and returns RunResult(session_id, final_response, finish_reason, events, notifications). final_response is the last committed root-session assistant text in the interval; finish_reason is the kind of the last root-session turn/end, such as completed, max-tokens, or error, and is None when no turn ended. The protocol is the same newline-delimited JSON-RPC documented under SDK Protocol; a turn/end without a string data.reason.kind violates it and raises SdkProtocolError.

The runtime carrier: deepseek-harness-runtime-bin

The runtime wheel packages the normal dsh CLI and its closed Node dependency tree into a native executable, so SDK use requires no system Node.js; the dev-only node carrier is never selected automatically and is excluded from wheels and sdists. The wheel installs a dsh console command (dsh = "deepseek_harness_runtime:main" in python/sdk-runtime/pyproject.toml) plus the deepseek_harness_runtime Python module, whose API locates the bundled executable:

from deepseek_harness_runtime import (
    bundled_package_dir,      # installed module-data root, release metadata verified
    bundled_runtime_path,     # current-platform executable, sidecars verified
    resolve_bundled_launch_args,  # default argv; mode="node" selects the repo-only carrier
)

Production executables are named deepseek-harness-sdk-runtime-<platform>-<arch> under the module's runtime/ directory; Windows uses the .exe suffix. Linux x64, Linux arm64, macOS arm64, and Windows x64 are the published targets. Linux and macOS wheels include a target-native -rg sidecar, Windows includes -rg.exe, and macOS also includes -spawn-helper for node-pty. The workspace manifest is python/sdk-runtime — the dsh-python-runtime-closure deploy root in python/sdk-runtime/package.json defines the packaged dependency closure, and its pyproject.toml defines deepseek-harness-runtime-bin. There is no Python-specific Node application or checked-in default cordis.yml.

External profile management uses dsh plugin --profile <name> ..., which requires pnpm on PATH; ordinary SDK/profile execution does not.

Packages

Package
deepseek-harness-sdk (PyPI)
deepseek-harness-runtime-bin (PyPI)

Further reading

• python/README.md — the Python SDK overview and two-package split
• python/sdk/README.md — runtime selection, profiles, patches, and plugin management
• python/sdk-runtime/README.md — the runtime wheel, sidecars, and build/distribution
• SDK Protocol — the shared newline-delimited JSON-RPC wire protocol
• packages/bundle/sdk-app/README.md — the sdk profile bundle
• packages/bundle/sdk-minimal/README.md — the standalone sdk-minimal tree