What Did DeepSeek Harness Change? From AI Agent Framework to Next-Gen Coding Agent Infrastructure

At a glance

Layer	One line	What you maintain
Agent Framework	Orchestrates prompts, tools, and steps in app code	Python / TS call graphs
Agent Harness	Runtime that mounts tools, FS, sandbox, and loop as plugins	Profile / Bundle / SessionEvent
DeepSeek Harness	MIT open-source dsh on Cordis: everything is a plugin	ctx.* services + JSON tool schemas

Remember the split: frameworks ship chains; harnesses ship a replaceable host. Models change; seams and JSON contracts should stay.

What is DeepSeek Harness?

DeepSeek Harness (CLI entry often dsh) is DeepSeek’s official open-source agent harness: it connects a large model to real environments—filesystem, terminal, web—and drives continuous work. The core claim is Everything is a Plugin: model adapters, tools, sessions, storage, sandboxes, scheduling, and UI are all assembled from plugins.

It is explicitly not:

• A new model: the DeepSeek V4 line is the model layer; dsh is everything besides the model.
• A thin API client: it owns the loop, permissions, and session replay—not just HTTP calls.
• One god-class Agent: responsibilities live in packages like core/session, core/tools, and core/agent-loop.

If you still conflate chatbots with runtimes that finish multi-step workflows, start with the AI Agent guide. A harness is the host shape of the latter.

From AI Agent Framework to Harness—what actually changed?

For two years, “Agent Framework” usually meant chaining prompts, tools, and memory in app code, then running an Agent Loop in-process. The product boundary sat in your business repo; swapping models, sandboxes, or audit hooks meant editing core classes.

A harness flips the default: there is no privileged kernel that needs patching. You extend by mounting plugins; on unmount, services and side effects roll back together. Swap the model adapter, register tools into one system, point FS/process/terminal providers at a remote sandbox, or replace the Agent Loop—without rewriting the product.

• Privileged kernel → plugin tree: capabilities register into a shared Context instead of subclassing BaseAgent.
• Chat history → Session Log: everything the model saw must be rebuildable from the log, not only final bubbles.
• Hard-coded sandbox → Capability Seam: interface, provider, and model-facing tool stay separable.
• Prompt-as-product → config composition: Profile / Bundle / cordis.patch.yml define the runtime shape.

The cut is about ownership of the runtime. In the framework era, the runtime was usually an accessory of business code. In the harness era, the runtime itself is distributable, auditable, replaceable infrastructure.

Everything is a Plugin: the Cordis microkernel

dsh sits on Cordis. A running dsh is essentially a Cordis Context: plugins contribute services, typed events, and reversible effects. Mount to enable; unmount to roll back—which buys observability and replay.

Prefer encoding deploy differences as config composition, not piles of if env == prod. Example patch: swap the model and mount a repo-search tool:

# cordis.patch.yml — swap model + add a tool
plugins:
  - name: llm/deepseek
    config:
      model: deepseek-v4-pro
  - name: tools/my-repo-search
    config:
      root: ./src

For engineering teams, the shippable unit becomes “ordered bundles + patches,” not “an unforkable mega Agent class.” Hot reload becomes a first-class path, not a demo trick.

Capability Seams: swap backends without swapping the product

dsh calls replaceable capabilities Capability Seams. A full seam usually has three roles:

1. Service Definition: declare what “run a command / read a file” means.
2. Service Provider: local process, remote container, or enterprise execution platform.
3. Consumer: usually a model-facing tool that projects the capability into schema and result objects.

Take Bash: the interface defines executing a command; the local provider spawns processes; the tool package turns that into parameters and results the model understands. FS and process providers share one execution world—point them at a remote sandbox and Bash, PTY, and LSP move together without per-tool remote forks.

The model-facing layer is still a JSON Schema-shaped tool definition. Editor tool example:

{
  "name": "str_replace_editor",
  "description": "Edit a file by exact string replacement",
  "inputSchema": {
    "type": "object",
    "properties": {
      "path": { "type": "string" },
      "old_str": { "type": "string" },
      "new_str": { "type": "string" }
    },
    "required": ["path", "old_str", "new_str"],
    "additionalProperties": false
  }
}

Same discipline as MCP Tool Schema vs Function Calling and Why AI needs JSON Schema: one contract in the repo, projected to Function Calling parameters or MCP inputSchema. A harness does not erase Schema; it parks Schema in a replaceable tool registry.

Session Log: what the model saw is what was recorded

When a coding agent fails, the painful question is: what did the model actually see? Workspace injection, truncated tool results, mid-stream reroutes, user cancels—if you only store final chat text, those facts vanish.

dsh’s hard rule: model-visible inputs must be reconstructible from the Session Log. User messages, environment context, request metadata, streaming output, tool calls and results, compression events, permission flips, and cancel reasons enter an append-only stream. Example tool-result event:

{
  "type": "tool/result",
  "tool_call_id": "call_7f2a",
  "name": "bash",
  "ok": true,
  "content": {
    "stdout": "passed 12",
    "exit_code": 0
  },
  "ts": "2026-09-11T06:12:04.221Z"
}

Persistence is still a plugin (JSONL / SQLite). Resume continues the original session; Fork derives from a historical boundary. In debugging, format SessionEvents, then JSON Diff against last week’s green trajectory—closer to production engineering than “try a longer prompt.”

Profiles, Bundles, and Turn / Step

A launch is a stacked plugin tree:

• Profile: a named runtime composition (e.g. web, headless) with bundle lists and cordis.patch.yml.
• Bundle: a distributable plugin set; stacked in profile order, then user and CLI patches.
• Turn: one complete task round that may contain many steps.
• Step: one model request plus the tool calls it triggers; agent/* events can rewrite, intercept, or approve before the request.

Tools are not “call once you have a name”: pre-policy, irreversible safety gates, execution, post-processing, cleanup, and result notification are hook points. Read-only work may run in parallel; mutating or unknown-safety calls become barriers. That is infrastructure scheduling, not a demo for-loop.

Four modes: one host, different tool surfaces

The Web UI ships four Agent presets. They share the same harness host but assemble different tools, prompts, and capabilities for the session:

Creation Mode is the extreme reading of “everything is a plugin”: the agent can observe and even modify its own runtime. Production defaults should fail closed, not start with self-referential tools.

Why call this next-gen Coding Agent infrastructure?

A coding agent that can edit repos, install deps, and start processes is a production blast radius. dsh treats security as infrastructure: fail closed, hookable policy, movable execution worlds. “Next-gen” means four things at once:

• Replaceable: model, sandbox, UI, and loop can swap without forking the whole tree.
• Replayable: Session Logs give evals, audits, and incident reviews something to Diff.
• Composable: Profiles / Bundles absorb deploy differences instead of branch explosion.
• Validatable: tool args and results stay JSON Schema contracts with host-side gates.

That is not the same path as “write a longer system prompt.” Capture tools and workflow state as Schema, then let the harness mount execution—see JSON Schema and AI Agent workflows. Models turn over; infrastructure should stabilize interfaces first.

How does it compare to classic Agent Frameworks?

Not better/worse—different layers you are buying:

You can still write business agents on top of a harness—just stop gluing “business orchestration” to “host infrastructure.”

Common pitfalls

• Treating dsh as a new model. V4 is the model; the harness is the host. Mixing them breaks buying and evals.
• Forking the whole repo to add one tool. Write a plugin and mount it via Profile / patch.
• Skipping Schema validation. The harness owns the execution pipeline; you still parse and validate arguments.
• Ignoring the Session Log. Without the event stream, you do not have a reproducible coding agent.
• Enabling Creation Mode in untrusted environments. Self-modifying the runtime is high-trust; keep it off by default.

FAQ

Is DeepSeek Harness competing with Claude Code?

Early hiring notes did benchmark coding-agent UX. The open-source positioning is broader: composable agent runtime infrastructure, not only a single IDE product.

Do I have to use DeepSeek models?

Defaults are tuned for DeepSeek models, but the model is an adapter plugin. Swapping adapters is first-class; coverage of your vendor depends on available plugins and your own.

Can I use it without learning Cordis?

Yes for a first run: npx @deepseek-ai/dsh web. Deep extensions (new seams, tools, profiles) need Cordis mount and config-tree literacy.

What does this have to do with JSON / JSON Schema?

Tool definitions, tool results, SessionEvents, and config patches are all structured objects. The harness puts them in a replaceable pipeline; contracts still come from Schema. Without Schema, elegant plugins only move half-wrong objects faster.

Is it production-ready?

Officially a developer preview with fast-moving, potentially breaking interfaces. Fine for infra R&D and controlled environments; pin versions, keep an adapter layer, and put Session + Schema checks in CI before production.

Conclusion

DeepSeek Harness does not ship “another chat box that writes code.” It pushes coding agents from in-app frameworks toward replaceable runtime infrastructure: plugins, seams, session logs, fail-closed security, and JSON contracts speaking one language.

Argue less about which model is smarter today. Put tool schemas and execution seams in the repo first. Models will change; host interfaces should stabilize earlier.

Further reading

• What is an AI Agent? Full guide Runtime, Tool Calling, and JSON contracts
• Why AI needs JSON Schema Schema / Function Calling / Structured Outputs
• MCP Tool Schema vs Function Calling Protocol boundary for tool JSON
• JSON Schema and AI Agent workflows From schema to orchestrated pipelines
• JSONSort local toolbox Format, validate, Diff
• All posts More JSON and AI development notes

Changelog: 2026-09-11 initial release