deepseek-harness/docs/user/guide/python-sdk.md

Get started with the Python SDK

English | 中文

This tutorial installs the published Python SDK, runs the shipped standalone minimal profile, and shows how to customize the same dsh profile from your own program.

Prerequisites

• Python 3.10 or newer
• Git
• Linux x64, Linux arm64, macOS 14 or newer on arm64, or Windows x64
• A DeepSeek-compatible API endpoint and credential
• An isolated workspace and an isolated Harness home

Install the SDK

::: code-group

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

git clone https://github.com/deepseek-ai/deepseek-harness.git
Set-Location deepseek-harness
py -3.10 -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install deepseek-harness-sdk

:::

The installation includes a matching native runtime wheel and the dsh command. Normal SDK execution needs no system Node.js. Repository contributors who build the artifacts should use the Python contributor workflow.

Run the checked-in example

Export the credential and, when needed, a compatible proxy endpoint:

::: code-group

export DEEPSEEK_API_KEY=sk-your-key-here
# export DEEPSEEK_BASE_URL=http://127.0.0.1:8000/v1

$env:DEEPSEEK_API_KEY = "sk-your-key-here"
# $env:DEEPSEEK_BASE_URL = "http://127.0.0.1:8000/v1"

:::

Run one task with explicit workspace and home paths:

::: code-group

python python/sdk/examples/minimal.py \
  --workspace /absolute/path/to/disposable-workspace \
  --dsh-home /absolute/path/to/example-dsh-home \
  --session-id example-001 \
  "Inspect the repository and fix the failing tests."

python python/sdk/examples/minimal.py `
  --workspace C:\work\disposable-workspace `
  --dsh-home C:\work\example-dsh-home `
  --session-id example-001 `
  "Inspect the repository and fix the failing tests."

:::

The script prints the final assistant response or the command result supplied by the selected profile. The selected home receives the generated sdk-minimal profile, installed plugins, and uncompressed JSONL session logs under sessions/. The example and SDK never silently read ~/.dsh.

Use the SDK in your program

from pathlib import Path

from deepseek_harness import DeepSeekHarness

workspace = Path("/absolute/path/to/disposable-workspace").resolve()
dsh_home = Path("/absolute/path/to/example-dsh-home").resolve()
with DeepSeekHarness(
    provider="deepseek-official",
    model="deepseek-v4-flash",
    max_tokens=49_152,
    cwd=str(workspace),
    dsh_home=str(dsh_home),
    profile="sdk-minimal",
) as harness:
    result = harness.run(
        "Inspect the repository and fix the failing tests.",
        session_id="example-001",
    )

print(result.final_response)

The SDK starts the bundled dsh --profile sdk-minimal process lazily and reuses it until context-manager exit. The profile, its persistent patch, the home patch, and any ordered patches tuple form the application configuration. There is no separate Python runtime bin or complete-config option.

Install or define plugins

Use dsh plugin for dependencies and bundle layers that should persist in this home:

::: code-group

export DSH_HOME=/absolute/path/to/example-dsh-home
dsh --profile sdk-minimal --dump-default-config >/dev/null
dsh plugin --profile sdk-minimal add file:/absolute/path/to/my-plugin-bundle

$env:DSH_HOME = "C:\work\example-dsh-home"
dsh --profile sdk-minimal --dump-default-config | Out-Null
dsh plugin --profile sdk-minimal add file:C:/work/my-plugin-bundle

:::

The first command initializes the shipped standalone profile. The second forwards package management to pnpm, then records any installed package that exports a dsh.bundle layer. Install pnpm only for this management command; launching the installed SDK does not need it. Edit $DSH_HOME/profiles/sdk-minimal/cordis.patch.yml for persistent row changes, or pass patch files from Python for per-launch changes.

Another profile is valid when it includes @deepseek-ai/dsh-sdk-app or another JSON-RPC server row. Missing server rows, unresolved plugins, and invalid patches fail during startup instead of falling back to another composition.

Opt in to str_replace_editor

The bundled runtime includes str_replace_editor, but sdk-minimal omits it from the default Cordis tree. To use it, save this configuration as editor.patch.yml; insert adds the editor using the existing filesystem provider:

- insert:
    - id: tool-str-replace-editor
      name: '@deepseek-ai/dsh-tool-str-replace-editor'

Pass patches=("/absolute/path/to/editor.patch.yml",) when constructing DeepSeekHarness(profile="sdk-minimal", ...), or put the patch in $DSH_HOME/profiles/sdk-minimal/cordis.patch.yml for persistent configuration. On the next runtime launch, model requests include str_replace_editor beside the default tools. The local filesystem provider uses the runtime working directory for relative paths; like the minimal shell, it does not confine access to that directory. The same patch works with the standard sdk profile.

Enable Team mode

Use the standard sdk profile for Agent Teams; sdk-minimal does not include subagents or Team services. Save the Team patch as team-mode.yml:

- id: agent-team
  config:
    defaultEnabled: true

Pass its absolute path in the SDK's patches option with profile="sdk". Python uses patches=("/absolute/path/to/team-mode.yml",); TypeScript uses patches: ["/absolute/path/to/team-mode.yml"]. The patch replaces the agent-team row's whole configuration, so include any custom maxTasks limit in the same mapping.

Create a new root Session and ask it to create and list a shared task. Its first model request includes the Team tools and collaboration guidance. The root saves its mode, and subagents share it. Resuming an existing Session preserves its mode, even if it was explicitly turned off or never enabled; changing or removing this patch does not override saved selections. See the Team service reference for mode and task semantics.

Understand the minimal profile

Property	Value
System prompt	DSH_SYSTEM_PROMPT, falling back to You are a helpful software engineer assistant.
Model in minimal.py	--model, then DSH_MODEL, then deepseek-v4-flash
Model-facing tools	Persistent bash on Linux/macOS or pwsh on Windows, read_image, and working_directory
Shell timeout	300 seconds
Optional runtime context	Absent
Context compaction	Automatic; summarizes older history through an additional model request
Session persistence	Uncompressed JSONL under <dsh_home>/sessions

The profile's sole bundle inserts the complete tree over an empty root and does not include dsh-base; later base-profile tools therefore cannot appear implicitly. It contains the SDK protocol, one environment-configured DeepSeek adapter, local execution, and persistence, while text file tools, settings, managed credentials, OTel telemetry, Web tools, subagents, and local instruction discovery are absent. The DeepSeek session-log contributor uploads unaccepted log events with DeepSeek requests by default, at most maxBytes (8 MiB) per request; set session-log-deepseek.enabled: false in a profile patch to disable it. It pins danger-full-access, so the platform-selected persistent shell can modify any path visible to the runtime; use a disposable checkout or container.

Image reading requires an image-capable route. Automatic compaction preserves the complete Session log; see the bundle reference for model and storage effects. In this sdk-minimal composition, unsupported slash input remains ordinary prompt text.

The installed wheel still packages the full web profile and frontend assets. Run dsh web against an explicit DSH_HOME when a Python SDK deployment also needs the browser application; web is a separate CLI application and cannot serve a Python SDK client.

Use a fresh home when profiles, plugins, credentials, settings, and sessions must be isolated. Use a fresh session id for independent work; reuse a harness, home, and id only to continue the same durable conversation and session-owned resources.

The bundle reference owns the exact tree, and the example reference owns the runnable program. The Python SDK reference covers lifecycle, results, notifications, and low-level behavior; the dsh CLI reference covers profile layering.