DeepSeek Harness
DeepSeek Harness Agent Loop: Steps, Turns, and Events
Follow one task through the agent loop and learn when session, agent, and capability events are the right extension point.
What you will learn
- A step is one model request plus tools; a turn can contain multiple steps.
- The session log reconstructs model-visible history.
- Event domains separate durable facts from live interception points.
Before you start
- Basic HTTP and API knowledge
Leave with a concrete implementation checklist and a testable starting point.
Key takeaways
- A step is one model request plus tools; a turn can contain multiple steps.
- The session log reconstructs model-visible history.
- Event domains separate durable facts from live interception points.
Step versus turn
The architecture guide defines a step as one model request plus the tools it calls. A turn spans zero or more steps, opening before the first input is claimed and closing once no work remains.
This vocabulary prevents a common debugging mistake: a tool call and the next model request are not separate user turns. They are part of the same durable turn lifecycle and should be traced together.
The execution path
A turn claims queued input, assembles prompt sections and tool schemas, enters a step, derives model history from the session log, streams the model response, dispatches tool calls, appends results, and either claims the next step or stops.
The event map distinguishes durable session events from live extension points. Session events such as user/message and assistant/message survive reload; waterfalls such as agent/request, llm/stream, and tools/execute let listeners intercept work while calling next().
Choose the right event
Use session/event when a fact must be replayable. Use agent events to observe or intercept live work. Use capability events such as tools/* or fs/* when you are attaching policy or an adapter without importing the loop.
When adding behavior, write down whether it must survive a reload, whether it needs to change the request, and which service owns the contract. Those answers usually identify the correct event domain.
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
Trace a task from turn/start to turn/end.
- 2
Mark which events append to the session log.
- 3
Locate waterfalls that require next().
- 4
Choose an event based on replay and interception needs.
Copy-ready example
turn/start -> step/start -> agent/request -> llm/stream
-> tools/execute -> tool/result -> step/end -> turn/endFrequently asked questions
Why are session events durable?
They are appended to the session log so history, replay, transcripts, and UI state can be reconstructed.
Sources
- DeepSeek Harness architecture turn flowSource checked 2026-08-27
- DeepSeek Harness core subsystemSource checked 2026-08-27