DeepSeek Harness
DeepSeek Harness Tools, Sessions, and Model Adapters
Understand the three runtime surfaces that turn a model response into a durable, tool-using agent task.
What you will learn
- Tools combine schemas, scoped registration, and guarded execution.
- The append-only session log is the source of model-visible context.
- LLM adapters expose a provider seam and streaming interception point.
Before you start
- Basic HTTP and API knowledge
Leave with a concrete implementation checklist and a testable starting point.
Key takeaways
- Tools combine schemas, scoped registration, and guarded execution.
- The append-only session log is the source of model-visible context.
- LLM adapters expose a provider seam and streaming interception point.
Tools are a guarded pipeline
The architecture and subsystem docs describe tools as a scoped registry with a guarded execution pipeline. A model-facing tool is registered on ctx.tools, its schema enters prompt assembly, and execution passes through pre-execute, execute, and post-execute stages.
This separation is useful for policy: a listener can inspect or reject a call without changing the agent loop implementation. It also gives operators a stable place to record tool latency, failures, and approval decisions.
Sessions are the source of truth
The session log stores model-visible facts as append-only events. deriveMessages projects model history from that log, while raw assistant chunks preserve replay and UI fidelity. Forks, resumes, transcripts, and telemetry derive from the same stream.
If new information reaches a model request, it must be reconstructable from the log. That rule is stricter than simply writing a debug line, but it prevents hidden context from making a run impossible to reproduce.
LLM adapters are a seam
The LLM runtime is an adapter registry plus a streaming model-call API. Providers register routes, model metadata can be resolved, and a prepared call keeps the selected registration stable through capability lookup and dispatch.
The `llm/stream` waterfall is the extension point for retry, replay, and routing. An adapter can fail with terminal chunks, while middleware and consumer failures remain thrown; this distinction matters when writing observability and recovery code.
Decision guide
| Criterion | Option A | Option B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
Implementation steps
- 1
Find the tool registration and execution stages.
- 2
Trace a model-visible fact into the session log.
- 3
Locate the adapter route and model capability lookup.
- 4
Measure tool and upstream failures separately in traces.
Copy-ready example
ctx.tools -> prompt schema -> tools/pre-execute
-> tools/execute -> tools/post-execute
ctx.llm -> prepareCall -> llm/stream -> provider adapterFrequently asked questions
Can a tool bypass the session log?
Model-visible facts should be represented as session events so history and replay remain reconstructable.
Sources
- DeepSeek Harness tools subsystemSource checked 2026-08-27
- DeepSeek Harness session subsystemSource checked 2026-08-27
- DeepSeek Harness LLM streaming subsystemSource checked 2026-08-27