ChatGPTClaudeGrok / X / CursorGemini

DeepSeek Harness Cookbook: Add an LLM Adapter

Plugin DevelopmentPublished 2026-11-18Author: DeepSeek Plugin Market
DeepSeek HarnessDSH pluginLLM adapterstreamingCookbook
A DeepSeek Harness LLM adapter translates frames and classifies errors, not just sends requests. Verify normal flow, a broken stream, and a retryable error.

The easy mistake is writing an LLM adapter as “a function that sends HTTP.” The Cookbook wants a piece that fits the DeepSeek Harness streaming and error model: translate provider output into unified frames, split retryable from deterministic failures, and keep config and credentials outside the adapter (source).

DeepSeek Harness: The adapter seam: define the boundary

An adapter is a seam, not a business plugin: it translates protocols and does not choose models or credentials. Model selection, routing, and credentials are decided above; the adapter receives a prepared call and produces a unified stream. (source)

Three things should stay out:

  1. Hard-coded model names — the model is passed in.
  2. Hard-coded endpoints — base URL and protocol come from provider config.
  3. Hard-coded retry policy — the adapter classifies; the caller decides.

Hard-coding these works briefly and then forces a rewrite when you change models, gateways, or retry behavior. The Cookbook keeps them in config so the adapter remains replaceable.

The adapter registers through ctx.llm, contributing a capability to the shared context rather than starting a separate service. The caller finds the adapter by model selection.

DeepSeek Harness: Streaming frames: start, chunk, end

Streaming is not “return the whole string once”; it advances frame by frame. The official stream has start, chunk, and end frames (source).

The adapter should:

  1. start — confirm the request is established and increments can arrive.
  2. chunk — translate provider increments into unified chunks in arrival order.
  3. end — close the stream with a complete message or a failed attempt.

Three common errors:

  • Buffering all chunks until the end — the result looks right, but streaming is gone and cancellation is late.
  • Sending a complete message before end — the caller sees duplicate content.
  • Never sending end on a broken stream — the caller cannot tell “still waiting” from “failed.”

Frame order is more error-prone than content. Get start, chunk, and end right before tuning translation. Once the order is correct, disconnects and cancellation have a clear landing point.

DeepSeek Harness: Error classes: retryable vs deterministic

Error classification is one of the adapter's most important outputs; a wrong class makes retries harmful. A practical three-way split (engineering analysis, not an official taxonomy) (source):

ClassExamplesHandling
TemporaryNetwork drop, timeout, 429, 5xxRetry with backoff
Deterministic401, unknown model, invalid argumentsDo not retry; raise
Stream breakConnection lost mid-chunkRetry carefully; never splice two streams

The first is worth retrying because the next attempt may succeed. The second only wastes quota. The third is the easiest to get wrong: splicing two streams produces duplicated or scrambled content.

The adapter does not need to decide how many retries happen, but it must mark the class. The caller retries only retryable failures and raises deterministic ones. When classification is unclear, default to no retry.

Also keep credentials out of errors and logs. A 401 response may echo request headers; redact before surfacing.

DeepSeek Harness: Retry boundaries

More retries is not better; unclear boundaries cause duplicate billing, duplicate side effects, and hard-to-reproduce corruption. Three boundaries (source):

  1. Retry only requests without side effects — model calls usually qualify, but a local write before the call does not.
  2. Retry only idempotent requests — the same request should produce the same result; a session-dependent request may not.
  3. Start a new request series — a failed attempt must not masquerade as part of the same message.

The third is most often missed. Splicing a failed attempt and a retry into one message duplicates content in model history. Keep the failed attempt and let the retry be a new attempt.

If both the adapter and the caller retry, requests multiply. Clear ownership beats one more layer of “just in case.”

DeepSeek Harness: Config and credentials stay outside

External config and credentials are what make the adapter replaceable. The Cookbook puts provider, base URL, protocol, and credentials in the config layer (source).

The adapter does three things:

  • Read config — endpoint, model, timeout, retry limits.
  • Resolve credentials — through a reference or environment variable, never plaintext.
  • Send and translate — request in, unified stream out.

Do not put an API key in a constant or build a fixed endpoint string. Otherwise a gateway change becomes a code change, and the seam is gone.

When a credential is missing, raise a clear error instead of falling back to an anonymous request. Anonymous requests are usually rejected, and the error is less useful than “missing credential.”

DeepSeek Harness: Three verifications

Do not test only the happy path. Three scenarios (source):

  1. Normal stream — a fake endpoint sends start, several chunks, and end; the caller gets a complete message in order.
  2. Broken stream — disconnect mid-chunk; the adapter emits a failure and does not present half a message as complete.
  3. Retryable error — return 429 or a timeout; the error is marked retryable and content is not spliced.

Then test deterministic errors (401, unknown model) and confirm they are not retried. Finally test cancellation between chunks: the adapter stops and cleans up.

Start with the healthy stream, then break it. A healthy stream proves frame order; broken stream and cancellation prove lifecycle; error classes prove retry boundaries.

The existing develop-llm-adapter covers the interface and registration, and develop-llm-stream-chunks covers chunk details; this article covers the Cookbook walkthrough and the three checks. A correct adapter makes model integration repeatable instead of a one-off.

ChatGPTClaudeGrok / X / CursorGemini

FAQ

What is the minimum a DeepSeek Harness LLM adapter must do?

A DeepSeek Harness LLM adapter must run one request as streaming frames: emit start, chunks, and end, and hand back a complete message or failed attempt. Config and credentials come from outside.

How should a DeepSeek Harness adapter classify retryable errors?

In DeepSeek Harness, classify by source: network drops, timeouts, 429, and 5xx are temporary and retryable; 401, unknown model, and invalid arguments are deterministic and should be raised unchanged.

What happens to partial output when a DeepSeek Harness stream breaks?

DeepSeek Harness keeps the attempt as a failed or partial attempt depending on the error class. It does not present an unfinished stream as a complete message, and a retry starts a new request series.

Should a DeepSeek Harness adapter implement its own retry count?

In DeepSeek Harness, usually no. The DeepSeek Harness request layer and adapter have separate jobs; the adapter should classify the error clearly and let the caller decide, avoiding two layers of retries.

Related Terms

LLM adapter
An LLM adapter is the DeepSeek Harness implementation that translates a unified request into a provider protocol and streams the response back in unified frames.— DeepSeek Harness reference - Adding an LLM adapter
stream frame
A stream frame is a DeepSeek Harness streaming unit such as start, chunk, or end; start begins, chunk carries increments, and end closes the stream.— DeepSeek Harness reference - LLM streaming
retryable error
A retryable error is a temporary DeepSeek Harness failure, such as a network drop, timeout, or rate limit, that the caller may retry.— DeepSeek Harness reference - Adding an LLM adapter
failed attempt
A failed attempt is a DeepSeek Harness record of an unfinished request, kept for retry, cancellation, and diagnosis but not treated as a complete message.— DeepSeek Harness reference - LLM streaming

Sources