DeepSeek Harness Python SDK
Connect DeepSeek Harness Python SDK to the DeepSeek API
The official deepseek-harness-sdk package embeds DeepSeek Harness behind a Python API. It is the programmatic alternative to the Web UI: your application chooses a composition, workspace, model and session, sends a task, then receives the final response while Harness retains its normal tool loop and event log.
This guide follows the official Python SDK documentation for the current developer preview.
Requirements
- Python 3.10 or newer
- Linux x64, Linux arm64, or Apple-silicon macOS 14+
- A DeepSeek-compatible endpoint and credential
- A dedicated workspace the agent is allowed to modify
The wheel includes a matching Harness runtime. A machine using the SDK does not need a separate system Node.js installation.
Install
Use a virtual environment so the SDK and its bundled runtime stay isolated:
python -m venv .venv
. .venv/bin/activate
python -m pip install deepseek-harness-sdk
For the official checked-in example and composition, clone the Harness repository too:
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
Minimal agent run
from pathlib import Path
from deepseek_harness import DeepSeekHarness
config = Path("examples/jsonrpc-agent/minimal.cordis.yml").resolve()
workspace = Path("./agent-workspace").resolve()
sessions = Path("./agent-sessions").resolve()
with DeepSeekHarness(
provider="deepseek-official",
model="deepseek-v4-flash",
max_tokens=49_152,
cwd=str(workspace),
session_root=str(sessions),
cordis=str(config),
) as harness:
result = harness.run(
"Inspect this project and summarize its architecture.",
session_id="demo-001",
)
print(result.final_response)
Provide DEEPSEEK_API_KEY in the process environment. Set DEEPSEEK_BASE_URL when using a compatible gateway rather than the default endpoint.
What each path controls
| Value | Purpose |
|---|---|
cordis | The checked-in agent composition and visible tool surface |
cwd | The workspace tools can inspect or modify |
session_root | Durable JSONL session records |
session_id | Identity used to start or continue one conversation |
These paths should be explicit and separate. Do not point an experimental agent at a broad home directory.
Continue a session
Reuse both the same session_root and session_id when a later prompt should continue the earlier conversation. The reused Harness process also preserves the session-owned shell state, including working directory, exported variables and shell functions.
Use a new session id for unrelated work. Accidentally reusing an id mixes context and may give the next task access to assumptions or shell state from the previous one.
SDK versus other DSH surfaces
| Surface | Best for |
|---|---|
| Web UI | Interactive human use and visual trajectory inspection |
| Headless CLI | One task from a shell or CI step |
| Python SDK | Product integration, evaluation runners and controlled automation |
| JSON-RPC SDK | Non-Python processes that want the same host protocol |
| ACP server | Agent-client interoperability |
Operational cautions
- Pin the SDK version for reproducible deployments; the project is still a developer preview.
- Give each tenant or job an isolated workspace and session root.
- Treat the selected Cordis composition as executable authority, not harmless configuration.
- Bound task duration and output in the calling service.
- Keep credentials in the environment or a secret manager, never in prompts or session fixtures.
FAQ
Does the Python SDK require Node.js?
No separate system Node.js is required for supported wheels; the package carries its matching runtime.
Does reusing a session id preserve context?
Yes, when the same session root is used. It preserves the durable conversation and session-owned shell state.
Can I use a custom OpenAI-compatible gateway?
Yes. Set the compatible base URL and select the provider/model expected by the composition.