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.
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 context | Changing task |
|---|---|
| Approved manual version | Current customer question |
| Fixed tool definitions | Tool results from the current task |
| Consistent instruction ordering | Requested output for this turn |
| A pinned document serialization | New 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
| Observation | Check | Controlled next experiment |
|---|---|---|
| First request reports no reusable prefix | Token minimum, marker placement and supported protocol | Keep the route fixed and inspect the serialized request |
| Second request has no cache reads | Exact prefix, user scope and elapsed time | Compare the first content blocks byte for byte |
| Only part of the input was cached | Where the breakpoint ends and what changed | Separate the stable document from the current question |
| A previously working sequence misses | Reference version, tool definitions and client serialization | Compare saved requests with the last working pair |
| Usage fields are absent | Protocol, response format and streaming behavior | Start with a complete non-streaming response |
| The call returns a parameter error | Route-specific support and JSON shape | Reduce 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.


