What Is an Agent Harness? Definition, Examples, and DeepSeek's Take

An agent harness is the software that sits between a language model and the real world, turning it into a working AI coding agent: it runs the tool-use loop, manages context and session state, enforces permissions, and provides an extension mechanism for adding capabilities. The model decides what to do; the harness decides how that decision becomes a shell command, a file edit, or an API call — safely, repeatedly, and with some kind of memory across steps.

The layers a harness actually provides

Strip away branding and vendor-specific names, and most agent harnesses converge on the same handful of responsibilities:

Layer	What it does
Tool-use loop	Sends the model a prompt plus available tools, receives tool calls, executes them, feeds results back — repeated until the model stops or a policy interrupts it
Context management	Assembles what the model sees each turn: system prompt, project instructions, conversation history, tool results — and compacts or prunes it as it grows
Permissions / sandboxing	Decides whether a requested action (write a file, run a command, hit the network) is allowed, denied, or needs explicit approval
Session state	Persists conversation and task state across turns, restarts, and sometimes across delegated sub-tasks
Extensibility	A mechanism for adding tools, integrations, or behavior without forking the harness itself — plugins, extensions, or some equivalent

A bare API call to a model provider gives you none of this. The harness is everything you build, or install, around that call to turn "a model that can respond to text" into "an agent that can get work done in a real environment."

How this differs from a "framework" or "agent SDK"

The terms get used loosely, but there's a useful distinction: an agent SDK or agent framework (LangChain-style libraries, for example) typically gives you building blocks — you write the orchestration code, decide the loop structure, and wire tools in yourself. A harness is closer to a finished application: you run it, and it already has an opinionated tool-use loop, a UI or CLI, session persistence, and a permission model. You extend a harness; you assemble a framework.

The line blurs in practice — some harnesses expose SDK-like programmatic interfaces, and some frameworks ship reference apps that look like harnesses — but "do I run this as-is, or do I write the orchestration loop myself" is usually the fastest way to tell which side of the line something sits on.

DeepSeek Harness, layer by layer

DeepSeek-Harness (dsh) is DeepSeek's open-source agent harness, and it makes a useful worked example precisely because its architecture states its own design philosophy out loud: everything is a plugin. Every one of the layers above is implemented as a plugin on top of the Cordis plugin framework, rather than as separate built-in subsystems with their own configuration formats.

Tool-use loop and tools — ctx.tools.register() registers a tool's schema and handler; the schema flows into prompt assembly automatically. A DSH_TOOLS_MODE environment variable even lets you switch between native structured tool calls and "Code Mode," where the model writes code that calls tools programmatically instead.
Context management — Sessions load AGENTS.md/CLAUDE.md project instructions (up to a 65,536-byte render budget) and index session content with an in-memory SQLite store; dedicated compaction plugins (compaction-basic, a tool-result pruner, and a /compact human command) manage what stays in context as a conversation grows.
Permissions and sandboxing — Three sandbox tiers (read-only, workspace-write, danger-full-access), backed by platform-specific enforcement (Linux bwrap/Landlock, macOS Seatbelt, Windows ACL, or an optional E2B cloud sandbox), paired with named permission presets that combine a sandbox mode with an approval policy. New sessions default to workspace-write with ask approval. Full detail is in DeepSeek Harness Permissions and Sandboxing.
Session state — Two pluggable persistence backends (JSONL and SQLite) store session history; a goal concept layers a persistent, stateful objective on top of an ongoing session.
Extensibility — This is where dsh's design commits hardest to its own thesis. Skills, slash commands, MCP server connections, hooks, model adapters, and even sub-agent delegation are all implemented as the same one kind of plugin, registered through the same Cordis mechanism — not as five separate subsystems with five separate manifest formats. The full breakdown of what that actually means in practice is in DeepSeek Harness Architecture: What "Everything Is a Plugin" Actually Means, and the vocabulary for talking about it precisely is in the DeepSeek Harness Glossary.

Installing a capability into dsh is one command: dsh plugin --profile web add <specifier>, pulling from npm, a GitHub repo, or a local path — see How to Install DeepSeek-Harness Plugins for the full mechanics, including the security tradeoffs of installing code that runs on your machine.

Other harnesses you'll encounter

DeepSeek Harness is not the only project in this space, and the category existed before it. Claude Code (Anthropic) and OpenAI's Codex CLI are both terminal-first coding agents that fit the same definition: a tool-use loop, permission model, session handling, and an extension mechanism (skills, commands, hooks, and MCP connections, organized as separate concerns in Claude Code's case, rather than dsh's single unified plugin mechanism). OpenCode is another open-source entrant with a similar shape and a terminal UI. Each project makes its own design choices about how tightly integrated the extension mechanisms are, what runs where, and how permissions default — a genuine point of comparison covered in depth in DeepSeek Harness vs Claude Code.

One fact worth knowing regardless of which harness you start with: dsh ships official sub-agent providers that delegate work to Claude Code or Codex as a backend (dsh-subagent-claude-code, dsh-subagent-codex), and provides bridge plugins that reuse an existing Claude Code or Codex hooks.json configuration directly. These tools aren't purely mutually exclusive — a harness can orchestrate another harness as one of its execution backends.

You'll sometimes see the term harness engineering alongside "agent harness" — it refers to the practice of deliberately shaping a codebase and its documentation (AGENTS.md files, lint rules, evaluation setups) to make an AI agent more effective when it's working inside that project. It's a discipline that applies to whatever harness you're using, not another name for the harness itself; the harness is the runtime, harness engineering is how you set up a codebase for it.

FAQ

Is an agent harness the same thing as an "AI agent"?

Not quite. The agent is the behavior — a model plus tools accomplishing a task. The harness is the infrastructure that makes that behavior possible: the loop, the permissions, the session handling. You could describe the harness as "the thing that turns a model into an agent," which is a fair one-line summary of why the term exists.

Do I need a harness to use an LLM for coding tasks?

Not for a single one-off request to a model API. But the moment you want multi-step tool use, persistent context, permission boundaries, or a way to extend behavior without hand-rolling your own orchestration, you're describing the problem a harness solves — whether you install one or build a minimal version yourself.

What's the difference between a harness and an IDE plugin?

An IDE plugin (a Copilot-style extension, for example) is usually one integration point bolted onto an existing editor. A harness is a standalone runtime with its own tool-use loop, permission model, and extension system — it can be exposed through an IDE integration, a web UI, a CLI, or an SDK, but the harness itself isn't defined by any one of those front ends.

Is DeepSeek Harness the same as the DeepSeek model API?

No. DeepSeek's model API answers text/chat requests. DeepSeek Harness (dsh) is a separate, open-source runtime that can call DeepSeek's models — or, via custom providers, models from other vendors — inside a full tool-use loop with sessions, permissions, and plugins. See What Is DeepSeek Harness? for the project-specific rundown.

Next steps

For the DeepSeek-specific version of this question — install steps, version status, and how it fits into the broader ecosystem — read What Is DeepSeek Harness?. To see "everything is a plugin" worked through in full architectural detail, go to DeepSeek Harness Architecture. If you're evaluating dsh against another harness you already use, DeepSeek Harness vs Claude Code is the deepest comparison on this site. To see the extension mechanism in action, browse Development & Runtime or the full plugin catalog.