DeepSeek Harness Agent lifecycle explained

The DeepSeek Harness Agent lifecycle is an event-driven loop. A user follow-up enters an inbox, the driver starts a turn, a pre-step hook can accept or reject the next input, the runtime assembles a prompt and streams a model response, and tool calls may trigger more steps. The turn finishes only when the model no longer requests tool work or execution ends through an error, abort, or cancellation path.

This page explains the flow shown in the official Chinese Agent lifecycle document. It is written for readers debugging Agent turns, tool calls, and events rather than as a line-by-line translation.

Turn and step: the two units to distinguish

A turn is the larger unit initiated by user or system input. A step is one model request and the work associated with its response. A turn can contain multiple steps because a model can request tools, receive their results, and then make another request.

This distinction explains a common debugging surprise: one user message can produce several LLM calls. Count steps when investigating provider usage, request failures, or tool loops. Count turns when investigating conversation-level input and completion.

From inbox to turn start

The user follow-up is queued in the Agent inbox. When the driver wakes, it reports an agent/status change to running and emits turn/start. The driver then claims the next step and one queued prompt.

Queueing separates arrival from execution. A message can exist before the driver is ready to process it, and live status can describe what the Agent is doing without rewriting the persisted conversation.

The pre-step decision point

Before a model request begins, the runtime dispatches agent/pre-step as a waterfall event. A handler can reject the proposed step or contribute messages to it. If the step proceeds, the runtime emits step/start, enters relevant user messages, and assembles the prompt.

This hook is a policy and orchestration seam. It can shape what reaches the model, but handlers should remain predictable: changing durable history and changing only the current request are different operations. Use the architecture guide to understand persistent session events versus live agent/* events.

Model request and streamed response

After prompt assembly, DeepSeek Harness sends the request to the selected LLM provider. The response can arrive as streamed assistant chunks before a completed assistant message is available.

Interfaces may render those chunks immediately, while session persistence records the durable message events required for replay. If a UI freezes but the provider still responds, inspect the stream handling and Client boundary. If the request itself never succeeds, inspect credentials, endpoint configuration, and the request-error path.

For provider setup basics, see configure a model provider.

How tool calls are scheduled

The completed assistant response can contain tool calls. The runtime classifies them by execution mode, then runs barriers or a rolling pool as appropriate. Each tool invocation passes through pre-execution, execution, and post-execution phases.

Execution mode affects concurrency and ordering. A read-only query may be safe to overlap with another operation, while a state-changing command may require a barrier. Tool authors should declare behavior accurately; users should still review the requested operation and its scope.

Tool results are added to the ongoing context. If the Agent needs another model response to interpret those results or choose the next action, the same turn advances to another step. Explore available tool groups in the DeepSeek Harness tool catalog.

Retry, abort, and cancellation paths

Not every request reaches a normal assistant message. On a request error, agent/request-error can return a retry action. Retry policy should distinguish transient provider failures from invalid credentials, malformed input, or a deterministic tool error. Repeating a non-transient failure only increases delay and usage.

Abort and cancellation are terminal control paths. They should stop pending work, release resources, and leave the Agent in an understandable state. A tool that supports cooperative cancellation must actually observe the supplied signal; accepting a signal without checking it does not make long-running work cancellable.

Persistent session facts versus live state

The lifecycle uses two complementary channels:

• session/event stores facts needed for replay, history, and audit; and
• agent/* communicates live control and runtime state.

A user message, assistant message, or durable tool result can be part of the append-only session history. Running status, stream progress, or an interception decision is usually live state. Mixing them can create duplicate replay output or missing history after restart.

Debugging a stuck Agent turn

Trace the lifecycle in this order:

1. confirm the follow-up entered the inbox;
2. look for running status and turn/start;
3. check whether agent/pre-step rejected or modified the step;
4. confirm prompt assembly and the provider request;
5. distinguish streamed chunks from the final assistant message;
6. inspect tool execution mode, barriers, and completion; and
7. check whether an error handler chose retry, abort, or cancellation.

This sequence narrows a vague “Agent is stuck” report to a specific boundary. For cross-process failures, continue with the API Gateway guide.

Official source

This guide was independently written from the official DeepSeek Harness Agent lifecycle document, reviewed on 2026-08-20. The upstream sequence diagram is the authoritative reference for the current event order.