DeepSeek Harness Handbook

English · 简体中文 · 日本語 · 한국어 · Español

The agent-first, multilingual field guide to understanding, running, debugging, and extending DeepSeek Harness.

If this handbook saves you time, star the repository and watch releases. That signal helps more Agent builders find source-backed DeepSeek Harness guidance.

Open the cheat sheet · Get started in five minutes · Build a repository research Agent · Contribute

DeepSeek Harness is more than a model wrapper. It is a composable agent runtime that connects model providers, tools, approval, sandboxing, durable sessions, subagents, and user interfaces through a plugin graph. This independent handbook explains those systems from the perspective of people building and operating agents.

The project is maintained by SandBase. It is not an official DeepSeek AI project.

[!IMPORTANT] DeepSeek Harness is in developer preview and may introduce compatibility-breaking changes. Pages in this handbook name their verification date and link to primary sources. Pin the revision you deploy.

Start with your goal

| I want to… | Start here | |---|---| | Keep the essential commands and checks in one tab | DeepSeek Harness cheat sheet | | Understand what DeepSeek Harness actually is | DeepSeek Harness explained | | Run the Web UI safely | Five-minute quickstart | | Use it from Python | Python SDK quickstart | | Run one task in automation or CI | Headless Agent guide | | Configure DeepSeek or another provider | Model provider guide | | Connect external MCP tools | MCP integration guide | | Add reusable Agent instructions | Skills guide | | Delegate work to child Agents | Subagents guide | | Understand the runtime | The agent-runtime mental model | | Understand one complete turn | Agent Loop and Session Events | | Understand approval, guards, and tool effects | Tool execution pipeline | | Build an Agent rather than a loose collection of tools | Agent design map | | Research a repository without publishing changes | Repository Research Agent recipe | | Fix a failing installation or run | Troubleshooting index | | Track upstream changes | Updates and breaking changes |

The agent-first mental model

flowchart LR
  U[User goal] --> A[Agent contract]
  A --> C[Profile + Bundles + Patches]
  C --> G[Cordis plugin graph]
  G --> L[Agent Loop]
  L --> M[Model provider]
  L --> T[Tools + policy + approval + sandbox]
  L --> S[Durable Session events]
  S --> L
  S --> H[Web, headless, SDK, clients]

An agent is not just a prompt. A useful Agent has a task boundary, allowed effects, completion condition, model route, tool surface, permission policy, session strategy, failure behavior, and an operator-visible result. DeepSeek Harness supplies the runtime vocabulary for assembling those responsibilities without forcing every product into one fixed loop or interface.

What makes this handbook different

• Agent-first: concepts are organized around building, running, and debugging Agents.
• Source-backed: version-sensitive claims link to official documentation or source.
• Operational: every tutorial includes success evidence, failure branches, and safety boundaries.
• Visual: architecture pages prioritize diagrams over walls of text.
• Living: updates, breaking changes, and troubleshooting pages follow upstream development.
• Multilingual by design: translations declare their canonical source revision and review status.

Handbook map

Getting started

• What is DeepSeek Harness?
• Five-minute Web UI quickstart
• Python SDK quickstart
• Headless Agent and CI
• Configure model providers
• Headless CLI
• Run from source
• Python SDK
• Model providers

Architecture

• The agent-runtime mental model
• Agent Loop and Session Events
• Tool execution pipeline
• Profile, Bundle, and Patch
• Capability Seams
• Tool execution pipeline
• Permissions, approval, and sandboxing
• Subagents

Agent patterns

• Designing an Agent
• Skills: discovery, precedence, and invocation
• Subagents: providers, delegation, and continuation
• Context and prompt surfaces
• Tools and side effects
• Memory, compaction, and replay
• Multi-agent coordination
• Evaluation and observability

Recipes

• Repository Research Agent
• Coding Agent
• Documentation Agent
• Browser Research Agent
• Read-only Agent
• Headless CI Agent

Integrations

• Connect MCP servers

Searchable operations

• DeepSeek Harness cheat sheet
• Troubleshooting index
• MCP server not connecting
• Sandbox denial versus sandbox unavailable
• Updates and breaking changes
• Ecosystem projects and plugins
• Comparisons with other agent runtimes

Repository structure

docs/<locale>/
  getting-started/     installation and first runs
  architecture/        runtime and lifecycle explanations
  agent-patterns/      design decisions for real agents
  recipes/             reproducible agent builds
  troubleshooting/     symptom-driven diagnostic pages
  ecosystem/           plugins, tools, skills, and comparisons
  updates/             upstream change coverage
scripts/               content and translation verification
content-manifest.json  canonical revision and locale status

Editorial and commercial boundary

DeepSeek Harness remains the subject of every technical page. SandBase maintains the handbook and may provide a restrained link to related Agent, model, Skill, or MCP discovery resources. A mention is never presented as an official DeepSeek recommendation, a compatibility guarantee, or a security endorsement.

Contributing

Corrections, reproducible examples, diagrams, troubleshooting cases, upstream change notes, and fluent translation reviews are welcome. Read CONTRIBUTING.md and run npm run check before submitting a pull request.

New here? Choose a scoped task from the public roadmap, or open a documentation request. Reproducible evidence is more valuable than a large patch.

Primary sources

• DeepSeek Harness official repository
• Official architecture documentation
• Official Agent lifecycle
• Official capability seams
• Official tool execution pipeline
• Official user guides

License

Apache-2.0. See LICENSE.