DeepSeek Harness Plugin Guide: Build AI Agents

DeepSeek Harness, also known as dsh, is an open‑source Agent Harness released by DeepSeek AI. Built upon the Cordis plugin system, it modularizes large‑model instances, tool functions, dialogue sessions, sandboxes, persistent storage and UI components into interchangeable building blocks. Developers can reconstruct executable Agent workflows purely through configuration files. The project remains in Developer Preview status. Public GitHub metrics show roughly 209.6 k stars and 24.5 k forks. After local installation, developers launch the web UI with default address http://127.0.0.1:3080.

This guide covers core concepts, three‑layer plugin architecture, minimal plugin development, custom tool implementation, schema‑driven configuration, local installation workflow, bundling for distribution, applicable scenarios and common troubleshooting. Where multi‑model API routing is required within Agent deployments, Treerouter can serve as an API gateway to unify access for heterogeneous model endpoints.

Core Background and Key Facts

DeepSeek Harness is not a ready‑to‑use chat application. Instead, it provides a runtime foundation for assembling custom Agent systems. All capabilities are injected externally via plugins rather than being hard‑coded inside the core binary. Its core value lies in three fundamental replaceable dimensions: model switching, tool switching, and workflow switching. Developers are assembling an Agent system instead of tuning a closed‑source black‑box service.

Key operational commands for plugin management:

• Install plugins: dsh plugin --profile <name> add …
• Dump runtime composition for debugging: dsh --profile <name> --dump‑config
• Register tool plugins: call ctx.tools.register(defineTool(...)) inside plugin logic; parameters, output schema and execute callback handle argument parsing, return‑value formatting and business execution respectively.
• Configuration is governed by cordis.yml and Schema‑based schemas. Configuration edits trigger hot‑reload without full service restart.

Applicable scenarios include plugin development, custom Agent workflow definition, local agent runtime execution and tool‑chain orchestration. It is not intended for casual end‑users who only want simple chat interaction and prefer zero‑configuration tools.

Three‑Layer Plugin Architecture: Bundle, Profile and Plugin‑Module

DeepSeek Harness organises plugins into three distinct conceptual layers, which many new developers confuse. Understanding these layers is critical for development, testing and publishing.

Simplified mental model:

1. Bundle: answers “what to ship” — the distributable artifact.
2. Profile: answers “how to assemble” — runtime combination of multiple bundles.
3. Plugin‑module: answers “what concrete logic runs” — source‑level implementation.

When installing, you add bundles into a profile; the profile resolves and loads individual plugin‑modules at startup.

Writing Your First Minimal Plugin

A minimal valid plugin only exports two constants: name and an apply() entry‑point function. The apply function runs when the plugin gets loaded into the Harness runtime.

export const name = "hello‑plugin";

export function apply() {
  console.log("[hello‑plugin] loaded");
}

If you intend to package this as an installable bundle for distribution, you must add a package.json manifest alongside cordis.patch.yml. The dsh.bundle flag inside package.json marks the package as a Harness bundle. Without this marker, the package will be treated as an ordinary Node dependency and will not be activated as a plugin.

Building Tool‑Based Plugins

Most practical extensions for Harness are tool plugins. Tools let Agent instances invoke external logic, run local computations, call external APIs or interact with local files. The tool registration flow is: custom plugin → dsh plugin --profile demo add → profile bundles collection → final runtime configuration.

import type { Context } from "@deepseek‑ai/cordis";
import { defineTool } from "@deepseek‑ai/dsh‑tools";

export const name = "greet‑tool";
export const inject = ["tools"];

export function apply(ctx: Context) {
  ctx.tools.register(defineTool({
    name: "greeter",
    parameters: {
      name: { type: "string", required: true }
    },
    async execute({ name }) {
      return `Hello, ${name}`;
    }
  }));
}

Three critical fields deserve attention:

1. `inject: ["tools"]`: Declares dependency on the tools registry service. The plugin loads only after the tool subsystem is ready.
2. `parameters`: JSON‑Schema object defining arguments the LLM is allowed to pass into this tool. It constrains what the model can request.
3. `execute` and `output.schema`: execute runs the actual business logic. output.schema defines how return values are formatted and validated before feeding back to the large model.

For rapid iterative testing without full npm packaging, developers can place plugin source files inside scratch‑plugin/cordis.yml and start the service with pnpm dsh web --patch ./scratch‑plugin/cordis.yml. This avoids repeated packaging overhead during early‑stage validation.

Schema‑Driven Configuration with cordis.yml

DeepSeek Harness does not hard‑code configuration values inside source files. Runtime behaviour is controlled by declarative cordis.yml together with Schema definitions.

export interface GreetingConfig {
  greeting: string;
  maxRetries: number;
}

export const Config = Schema.object({
  greeting: Schema.string().default("Hello"),
  maxRetries: Schema.number().default(3),
});

This schema‑oriented configuration brings two major engineering benefits:

1. Default values and input validation are defined declaratively within schema objects. No manual validation code scattered across business logic.
2. Configuration updates trigger hot‑reload. Developers adjust yml files without restarting the Harness process or modifying plugin source code.

For plugin authors, this pattern decouples parameter tuning from code deployment. Operators adjust runtime parameters purely via configuration files. Combined with unified API routing capabilities provided by Treerouter, Agent deployments can centralise external service endpoints while keeping plugin business logic unchanged.

Bundle Packaging and Local Installation Workflow

The complete development‑to‑local‑test workflow follows this sequence: author plugin module → assemble into bundle → add bundle to target profile → dump and inspect resolved configuration → start runtime.

# Add local bundle to "demo" profile
dsh plugin --profile demo add ./hello‑plugin

# Inspect fully‑resolved runtime configuration
dsh --profile demo --dump‑config

Uninstallation follows symmetric syntax:

dsh plugin --profile demo remove ./hello‑plugin

Removal cleans up registered dependencies and persisted profile settings.

When Should You Adopt DeepSeek Harness?

Harness fits well for these use‑cases:

• Building highly customisable Agent frameworks requiring custom tool sets.
• Needing local, reproducible, inspectable Agent execution layers.
• Decomposing Agent capabilities into independently maintainable plugin components.

If you only need to wrap existing products with standard LLM API access, a lightweight API gateway solution will deliver faster time‑to‑market. Harness demonstrates its greatest value when building long‑term Agent plugin ecosystems.

Frequently Asked Questions

Q: Must DeepSeek Harness use DeepSeek‑family models?
A: No. Harness decouples Agent runtime logic from model vendors. The framework focuses on execution orchestration. Model back‑ends are interchangeable via plugin configuration.

Q: What is the difference between bundle and profile?
A: A bundle is a distributable plugin package. A profile is a runtime assembly combining multiple bundles. You publish bundles; end‑users compose profiles for their workloads.

Q: How do Tool plugins differ from ordinary UI‑only plugins?
A: Tool plugins inject executable functions callable by the LLM. They are closer to real‑world task automation compared to purely visual UI extensions.

Q: Where should new developers start?
A: Launch the default web UI with npx @deepseek‑ai/dsh web. Follow official documentation sequentially: build minimal plugin, implement custom tool, adjust schema configuration, test inside profile, then prepare for publishing. The four‑step workflow covers core development cycles.

Final Observations

The core innovation of DeepSeek Harness is not improved model performance, but its composable Agent execution layer. As of September 2026, the project stays in Developer Preview. Interfaces, package naming conventions and default behaviours may evolve in subsequent releases. Production‑grade systems built on top of Harness should pin dependency versions and implement sufficient integration testing.

Developers should always refer to official GitHub repositories and documentation for up‑to‑date API specifications.

Learn more：https://treerouter.com