DeepSeek Harness Architecture Deep Dive

In the evolution of autonomous agent infrastructure and engineering adoption, DeepSeek established its foundational engineering formula:

$$\text{Agent} = \text{Model} + \text{Harness}$$

Why Agent = Model + Harness?#

In agent engineering practice, we clearly separate the boundaries of the reasoning brain and the execution scaffolding:

1. Model (Reasoning Brain): Responsible for cognitive understanding, logical deduction, and token generation. The model is the soul of an Agent, but a raw LLM is essentially a floating brain unable to interact directly with local filesystems, execute Shell commands, or catch compiler errors.
2. Harness (Engineering Scaffolding & Limbs): The system engineering architecture wrapping around the model. It grants the Agent the ability to understand environments, manipulate tools, persist state memory, and work continuously in real-world production environments.
3. Agent (Autonomous System): The production-grade automated system produced by combining high-performance Models with decoupled Harness scaffolding.

graph TD
    subgraph ModelLayer["Model Layer (Reasoner & Brain)"]
        LLM[Base DeepSeek LLM]
    end

    subgraph CordisKernel["Cordis Kernel (Plugin & Dependency Router)"]
        Kernel[Cordis Core Engine]
    end

    subgraph CapabilityPlugins["Capability Plugins (Fully Decoupled)"]
        ModelPlugin[Model Interface Plugin]
        ToolPlugin[Tool & Skill Plugins]
        LogPlugin[Trajectory & Log Plugins]
        SandboxPlugin[Sandbox & Execution Plugins]
        UIPlugin[Web UI & Scheduler Plugins]
    end

    ModelLayer <---> ModelPlugin
    CordisKernel ---> CapabilityPlugins
    CapabilityPlugins ===> Agent[DeepSeek Harness Agent System]

Core Design Philosophy: Everything is a Plugin#

DeepSeek Harness is built on the Cordis plugin framework:

• Lightweight Cordis Kernel: Focuses purely on plugin loading, unloading, lifecycle callbacks, and service dependency injection without hardcoding specific business logic.
• Capabilities as Plugins: Model interfaces, toolsets, Skill libraries, session logs, sandboxes, storage, loops, scheduling, and Web UI are all pluggable components.
• Services & Event Buses: Plugins communicate and collaborate seamlessly via standardized Cordis service interfaces and event buses.
• Compose in Configuration: Select, replace, or extend capabilities in configuration files without modifying DeepSeek Harness source code.

Three Engineering Highlights#

1. Fully Decoupled Cordis Plugin Architecture

Eliminates legacy frameworks that hardcode multi-step flows into Python scripts. All capabilities are decoupled into standardized plugins, enabling teams to rapidly integrate custom toolchains or new model endpoints.

2. Traceable Runs (Trajectory Tracking)

Everything seen and executed by the model—system prompts, thought chains <think>, tool call commands and return values, sub-agent dispatches, and context injections—is recorded in an append-only session log.

• Trajectory View: Inspect inputs, outputs, and context injections clearly organized by source.
• Shared Event Stream: Restoration, forking, semantic searching, and replaying share the exact same event stream, guaranteeing high debug transparency and reproducibility.

sequenceDiagram
    autonumber
    participant User as User / Web UI
    participant Harness as Cordis Harness Engine
    participant Model as LLM (Reasoner)
    participant Log as Trajectory Append-Only Log
    participant Sandbox as Execution Sandbox

    User->>Harness: Submit Task Goal
    Harness->>Log: Append User Prompt Event
    Harness->>Model: Request Context & Prompts
    Model-->>Harness: Return Thought Stream & Tool Call Command
    Harness->>Log: Append Model Response & CoT Event
    Harness->>Sandbox: Dispatch Tool Command to Sandbox
    Sandbox-->>Harness: Return Shell/Edit Execution Result
    Harness->>Log: Append Tool Result Event
    Harness-->>User: Render Trajectory View

3. Multiple Preset Running Modes (4 Preset Modes)

1. Standard Mode: Full-featured coding agent supporting file edits, Shell commands, file & web search, Skills, plans, and sub-agent workflows.
2. PTC Mode (Programmatic Tool Calling Mode): Presents tools via Code Mode SDK, allowing models to write a TypeScript program to combine multi-step tool invocations and conditional loops.
3. Minimal Mode: Dual-tool agent (bash + str_replace_editor) designed for minimal model benchmark testing.
4. Creative Mode: Experiment with Cordis plugins in memory to inspect the runtime and author custom agent presets.

Quickstart & Developer Guide#

1. Launch Web UI via npx

With Node.js installed, run the following command to open the browser Web UI in seconds:

npx @deepseek-ai/dsh web

2. Clone Source & Developer Environment (git clone)

# Clone official GitHub repository
git clone https://github.com/deepseek-ai/deepseek-harness

# Change directory
cd deepseek-harness

• Official Developer Docs: https://deepseek-harness.github.io/deepseek-harness/guide/quickstart
• Community Plugins Topic: https://github.com/topics/dsh-plugin
• License: MIT License, © 2026 Hangzhou DeepSeek AI Co., Ltd.