Qwen4 prompt caching: reuse an agent's context and diagnose cache misses

Set a Qwen4 cache breakpoint, compare two requests and read cache usage correctly. Includes a local request builder and a checklist for missed cache hits.

A reusable printing block produces consistent impressions while a small orange detail changes.

For an agent that repeatedly reads the same reference material, put the stable context before a cache breakpoint and the changing question after it. Then check reported cache reads. Sending similar prompts and observing a faster answer is not enough to prove caching worked.

This guide covers QwenCloud’s direct Qwen4 API, checked on November 16, 2026. It builds on our Qwen4-Max access and migration guide. The request builder below runs locally without a key. We have not run paid cache requests for this article, so the examples describe a reproducible experiment, not measured savings or latency.

Decide what should remain identical

Consider a support-analysis agent that receives the same product manual and answers a different customer question each turn. The manual is a reasonable candidate for reuse. A timestamp, random identifier or changing question inserted before the manual can make the beginning of the request different.

Create two explicit parts of your input:

Stable contextChanging task
Approved manual versionCurrent customer question
Fixed tool definitionsTool results from the current task
Consistent instruction orderingRequested output for this turn
A pinned document serializationNew evidence that changes the analysis

Do not freeze incorrect information merely to improve a hit rate. When the manual changes, a new prefix is appropriate. Record the document version and a hash so that a cache miss caused by an intentional update is distinguishable from an accidental formatting change.

The official Qwen4 cache guide documents a minimum cached prefix of 1,024 tokens, exact-prefix matching within the same user scope, and support for Chat Completions, Responses and Anthropic Messages. Its Qwen4 explicit-cache feature is not supported by DashScope. A word or character count is not an exact token count.

Generate two requests locally

Use a synthetic or non-sensitive reference document that you are authorized to send to your chosen provider. Save it as reference.txt. Keep its contents unchanged between the first and second request.

Save the following as build_cache_requests.py:

import hashlib
import json
from pathlib import Path

reference = Path("reference.txt").read_text(encoding="utf-8")
if not reference.strip():
    raise SystemExit("reference.txt is empty")

questions = [
    "List the three main responsibilities described in the reference.",
    "Which responsibilities in the reference require an explicit approval?"
]
for number, question in enumerate(questions, 1):
    payload = {
        "model": "qwen4-max",
        "messages": [{
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": reference,
                    "prompt_cache_breakpoint": {"mode": "explicit"}
                },
                {"type": "text", "text": question}
            ]
        }],
        "enable_thinking": False,
        "max_completion_tokens": 1024
    }
    Path(f"request-{number}.json").write_text(
        json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8"
    )
print("Reference SHA256:", hashlib.sha256(reference.encode()).hexdigest())
print("Created two request files; no network requests were sent.")

Run python3 build_cache_requests.py. Inspect the generated JSON: the first content block and its breakpoint must match exactly; only the second block’s question should differ. This script does not measure the reference’s tokens. Use the provider’s token-counting facilities or your established model-specific tokenizer to check the minimum before sending a billable request.

The breakpoint belongs to a content block, so the message’s content is an array. This example uses one breakpoint marker; do not combine it with a second cache-marker syntax in the same request. The first call is intended to establish reusable context, and the second is intended to reuse it. The actual response usage decides whether that happened.

Send the requests sequentially on the correct route

Configure a QwenCloud pay-as-you-go key for the selected region using the official key guide. The following command uses the Singapore Chat Completions endpoint. It does not accept an Ofox key or a Token Plan key interchangeably.

curl --silent --show-error --fail-with-body --max-time 120 \
  https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1/chat/completions \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request-1.json -o response-1.json

Inspect the HTTP outcome, response body and usage before continuing. Once the first request has completed successfully, repeat the command with request-2.json and response-2.json. Run within the documented cache validity period. Do not send both simultaneously for this experiment: sequential requests make it easier to tell creation from reuse.

A timeout does not prove the provider did no work. Check its request records before retrying, and keep an explicit budget for the experiment. This guide does not execute either command on your behalf.

The default cache lifetime is five minutes; the official guide also documents a one-hour option. For this first experiment, leave the default unchanged. Changing lifetime and prefix together makes a failed hit harder to diagnose. Generation time also consumes part of the available validity period.

Read the usage for the protocol you actually used

For the Chat Completions experiment above, inspect usage.prompt_tokens_details. The important distinctions are cache reads, cache writes and ordinary input. Do not treat the presence of a cache field as proof that the entire document was reused.

import json
from pathlib import Path

for name in ["response-1.json", "response-2.json"]:
    response = json.loads(Path(name).read_text(encoding="utf-8"))
    usage = response.get("usage") or {}
    details = usage.get("prompt_tokens_details") or {}
    print(name, {
        "input_tokens": usage.get("prompt_tokens"),
        "cache_read_tokens": details.get("cached_tokens"),
        "cache_write_tokens": details.get("cache_write_tokens"),
        "output_tokens": usage.get("completion_tokens")
    })

Missing values remain None; the script does not quietly convert missing reporting to zero. Save both raw responses privately. If the provider returns a different protocol’s usage structure, use that protocol’s documentation rather than renaming fields until the script appears to work.

For example, QwenCloud documents Responses cache details under input_tokens_details, while Anthropic-compatible usage has its own read and creation fields. Some fields are aliases: adding both an alias and its corresponding count would overstate usage. See the protocol-specific tables in the cache usage reference.

Diagnose a miss without changing everything at once

ObservationCheckControlled next experiment
First request reports no reusable prefixToken minimum, marker placement and supported protocolKeep the route fixed and inspect the serialized request
Second request has no cache readsExact prefix, user scope and elapsed timeCompare the first content blocks byte for byte
Only part of the input was cachedWhere the breakpoint ends and what changedSeparate the stable document from the current question
A previously working sequence missesReference version, tool definitions and client serializationCompare saved requests with the last working pair
Usage fields are absentProtocol, response format and streaming behaviorStart with a complete non-streaming response
The call returns a parameter errorRoute-specific support and JSON shapeReduce to the documented single-marker example

Long agent conversations have an additional boundary: the official guide documents a lookback of up to 20 content blocks for each breakpoint and retention of only the last four effective breakpoints, including an automatic breakpoint when used. If a growing history pushes the useful prefix outside that search window, review your block layout and place a deliberate breakpoint at the stable boundary. Do not delete required tool results or reasoning history merely to force a hit. Keep a before-and-after request snapshot and verify the resulting usage.

Do not interpret every cache miss as a model regression. Your harness may reorder tools, prepend dynamic system text or change document formatting. Log a sanitized representation of the stable prefix and its hash before blaming the provider.

For identifier or endpoint errors, use our model-not-found troubleshooting guide. If the cache works but a multi-turn agent loses tool results, that is a separate history problem; see multi-turn tool-call preservation.

Calculate savings from complete accepted tasks

A cache write can cost differently from a read or ordinary input. Compare the complete sequence, including its initial write and every generated answer, against the same sequence without caching. Use the current region-specific rates from QwenCloud pricing, not a rate copied from another region or a preview promotion.

Record these columns for each call: document version, input tokens, cache-read tokens, cache-write tokens, ordinary input, output tokens, elapsed time and acceptance result. Avoid counting aliases twice. Do not describe a cached input discount as the same percentage discount on the entire agent task: outputs and external tools may account for much of the total.

Check the answer as well as the bill. For the two-question example, independently verify that the listed responsibilities and approval requirements occur in the reference. A cheaper unsupported answer is not an accepted result.

This is a direct QwenCloud workflow. Our November 16 Ofox catalog check did not list Qwen4. For existing Ofox routes, verify the exact model entry, use Ofox authentication, and follow Ofox error handling. These documents do not establish that QwenCloud’s new cache parameters are available on Ofox.

Frequently Asked Questions

Does a repeated prompt prove Qwen4 used its cache?
No. Check the cache-read usage fields returned by the provider. A faster response or repeated text alone does not establish a cache hit.
Can I use these cache parameters on Ofox?
This article describes QwenCloud's direct Qwen4 API. The November 16 Ofox catalog check did not list Qwen4; do not assume the same model or cache contract is available through Ofox.