DeepSeek Harness SDK: Python, HTTP API and gateway

DeepSeek Harness has three developer entry points: Python SDK, Typert gateway, and CLI calls. They target different callers; choosing wrong means writing code where a command would do, or assembling commands where structured results are needed.

Who each entry serves

Decide by the caller and the result you need.

The SDK is for programmatic use, the gateway is for plugin internals, and the CLI is for one-off actions. Create sessions, send messages, and read results from Python (source). The gateway exposes host methods to client code and is not a public HTTP API; you meet it when writing plugin UI. The CLI handles install, start, plugin management, and commands, so scripts depend on it least.

Python SDK: minimal working example

The SDK's value is structure, not replacing the CLI.

1. Install the SDK: pip install deepseek-harness-sdk.
2. Prepare the environment and a writable DSH_HOME.
3. Start the sdk-minimal profile with the DeepSeekHarness context manager.
4. Create a session and send one test message.
5. Read the result and confirm JSONL logs under DSH_HOME/sessions.

sdk-minimal is deliberately small. It reduces plugin and tool dependencies for scripted calls; switch to a fuller profile when needed.

Logs are the first diagnostic entry. If a request does not return or the result is incomplete, read the JSONL before adding prints.

Typert gateway: plugin communication

The gateway is an internal bridge, not a public interface.

1. Add @Remote or @RemoteScope to host service methods to select exposure.
2. Declare object and wire-identity relationships with TypertLookupMap.
3. Call through the generated client entry; do not hand-write the protocol.
4. Expose only necessary methods; a wider surface increases permission and security risk.
5. Use logs to confirm whether a call reached the host.

@Remote controls whether a method can be called; @RemoteScope controls where it is visible (source).

Do not treat it as REST. It has no public HTTP paths or status-code semantics; understanding it as a plugin mechanism avoids fragile code.

CLI: scripts and CI

The most stable script pattern is command plus exit code.

1. Confirm the environment with dsh --version.
2. Confirm plugin state with dsh plugin --profile web list.
3. Call the target command and capture the exit code.
4. Parse standard output or switch to the SDK when structure is needed.
5. Pin versions in CI to avoid pulling a different build each run.

Avoid interactive prompts in CI. Add non-interactive flags; otherwise the pipeline waits for input.

The exit code is the contract. Zero and non-zero mean success and failure; do not match output text, which changes between versions.

Authentication and timeouts

Each entry authenticates differently and needs its own timeout policy.

1. SDK: provide model keys through environment variables or configuration, never hard-coded.
2. Gateway: uses host permissions; no extra token, but limit exposed methods.
3. CLI: reuses local configuration and login state; inject env vars in CI.
4. Timeouts: request-level for SDK, process-level for CLI, call-level for the gateway.
5. Retries: only for retryable errors, with a cap.

Keys do not belong in code; timeouts must be layered. Environment variables, secret managers, and CI secrets beat plaintext. Set request, task, and process limits separately; one layer alone kills long tasks.

Errors and logs

The three entries fail differently, but diagnosis starts with logs.

Separate "not called" from "call failed." The first checks entry configuration, the second checks the error; mixing them changes the wrong place.

Logs need context. Session ID, profile, and version make reproduction possible; "it failed" does not.

Selection table

Choose by caller, result, and dependency tolerance.

If the CLI solves it, do not add the SDK. More code means more maintenance; use the SDK for structure and reuse.

Write plugins only with the gateway. It is not an external integration entry; treating internal mechanisms as public APIs creates fragile integrations.

Next steps

Pick the entry, then write the minimal example. For Python SDK configuration, read How to call DeepSeek Harness from Python. For @Remote, read What the DeepSeek Harness API gateway is. To write a first plugin, read Write your first DSH plugin.

Sources: DeepSeek Harness docs, dsh CLI README, deepseek-harness repository