From Web UI to Python: Orchestrating DeepSeek Harness Agents with the Python SDK

Problem

Web UI is convenient for manual interaction, but when a script needs to schedule tasks, batch‑process workspaces, or integrate Harness agents into CI/CD pipelines, clicking buttons in a browser becomes a bottleneck because the UI cannot be called directly from code.

Python SDK capabilities

Start an Agent session from a Python script

Specify workspace directory and session identifier

Run a single task and retrieve final_response Invoke the Harness Agent Runtime instead of a plain model API

The SDK uses the Cordis composition under the hood; a user can start without deep Cordis knowledge, but extending tools or adjusting agent behavior later requires editing the Cordis configuration file.

Installation

Create an isolated Python virtual environment, clone the repository, and install the SDK:

# Clone repository (required to run examples)
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
# Create virtual environment (Python 3.10+ recommended)
python3 -m venv .venv
# Activate environment (macOS/Linux)
. .venv/bin/activate
# Or Windows: .venv\Scripts\activate
# Install SDK and matching runtime
python3 -m pip install deepseek-harness-sdk

If creating the venv fails with permission errors, do not use sudo . Ensure the current directory is writable or create the environment in a directory you own, otherwise the .venv directory may become owned by root and later installations will fail.

Credential configuration

Export environment variables for the model you intend to use before running any script:

# DeepSeek official endpoint
export DEEPSEEK_API_KEY=sk-your-key-here
# Optional: OpenAI‑compatible gateway
# export DEEPSEEK_BASE_URL=http://127.0.0.1:8000/v1
# Optional model and system prompt
export DSH_MODEL=deepseek-v4-flash
export DSH_SYSTEM_PROMPT='You are a helpful software engineer assistant.'

Running the built‑in example

The repository includes a minimal Python example at examples/jsonrpc-agent/minimal.py. Define a workspace directory and execute the script:

# Define workspace path
export WORKSPACE=/absolute/path/to/workspace
python examples/jsonrpc-agent/minimal.py \
  --workspace "$WORKSPACE" \
  --session-root "$WORKSPACE/.dsh-sessions" \
  --session-id example-001 \
  "Inspect the repository and fix the failing tests."

The script prints the final response only after the Agent finishes. For quick verification, use a simple prompt such as "Say hi.", which returns instantly because no tool calls are required.

Custom automation example – reviewing a Markdown article

The following script shows how to let an Agent read a Markdown file, check its structure, verify technical facts and links, and output revision suggestions:

import sys
from pathlib import Path
from deepseek_harness import DeepSeekHarness

CONFIG = Path("/Users/XXX/deepseek-harness/examples/jsonrpc-agent/minimal.cordis.yml").resolve()
WORKSPACE = Path("/Users/XXX/Claude Code/微信公众号").resolve()
SESSIONS = WORKSPACE / ".dsh-sessions"

def main() -> None:
    with DeepSeekHarness(
        provider="deepseek-official",
        model="deepseek-v4-flash",
        max_tokens=49_152,
        cwd=str(WORKSPACE),
        session_root=str(SESSIONS),
        cordis=str(CONFIG),
        request_timeout_seconds=300,
        shutdown_timeout_seconds=3,
    ) as harness:
        def on_notification(n):
            if n.method != "session.event":
                return
            event = n.payload.get("event", {})
            if event.get("type") != "assistant/chunk":
                return
            chunk = event.get("data", {}).get("chunk", {})
            ctype = chunk.get("type", "")
            if ctype == "text":
                text = chunk.get("text", "")
                if text:
                    print(text, end="", flush=True)
            elif ctype == "tool_use":
                target = (
                    chunk.get("input", {}).get("command")
                    or chunk.get("input", {}).get("path")
                    or ""
                )
                print(f"
[Tool Call] {chunk.get('name')}: {str(target)[:200]}
", flush=True)
        result = harness.run(
            "帮我审查文章 2026/8月/2026-08-19-DeepSeek-Harness入门四-Python SDK/",
            "DeepSeek-Harness入门（四）：用 Python 驱动 Harness——SDK 快速上手.md",
            session_id="wechat-review-001",
            on_notification=on_notification,
        )
        print("
" + "="*60)
        print(f"Finish reason: {result.finish_reason}")
        print(f"Session root: {result.session_root}")

if __name__ == "__main__":
    try:
        main()
    except KeyboardInterrupt:
        print("
Interrupted")
        sys.exit(130)

Running the script prints the Agent’s step‑by‑step actions (18 commands in this demo) and finally writes a JSONL log under the session root, recording model requests, tool calls, and responses.

Key configuration parameters

provider

: model provider (e.g., deepseek-official) model: model name (e.g., deepseek-v4-flash) max_tokens: maximum output tokens cwd: workspace directory accessible to the Agent session_root: directory where JSONL logs and session state are stored cordis: path to the Cordis composition file (e.g., minimal.cordis.yml) session_id: identifier for the current session; reusing the same ID preserves the Bash process

The runtime permission policy danger-full-access grants the Agent unrestricted file‑system access. Use it only in disposable checkouts or containers; never in production.

Important considerations

The SDK does not require Node.js; the runtime is bundled. Building from source still needs pnpm.

Each session_id represents a distinct conversation. Persist session_root to keep state across runs.

Because danger-full-access lets Bash and editors modify any path, run the SDK only in throw‑away environments.

Supported platforms: Python 3.10+, Linux x64/arm64, macOS 14+ arm64. Windows cannot run the provided minimal.py directly; use WSL if needed.

Logs are saved as uncompressed JSONL for easy debugging.

Both the Web UI and the Python SDK use the same Agent runtime; the SDK enables automation such as scheduled jobs, batch code reviews, CI/CD integration, and data pipelines.

Quick start checklist

Clone the repository and run examples/jsonrpc-agent/minimal.py to familiarize yourself with the flow.

Modify minimal.cordis.yml to add tools or change configurations.

Read the Python SDK quick‑start guide at https://deepseek-harness.github.io/deepseek-harness/guide/python-sdk for details on lifecycle, results, notifications, and runtime selection.