1# Preserved reasoning1# Keep the prefix unchanged
2 2
3> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.3> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.
4 4
5When you continue a conversation with the Responses API, a model can reuse5In agentic and multi-turn applications, our models work best when [thinking is preserved](https://developers.openai.com/api/docs/guides/reasoning?api-mode=responses#preserve-reasoning-across-calls) across API requests, where new actions and instructions are always appended to the model’s context. Keeping the prefix intact has long been a best practice for [prompt caching](https://developers.openai.com/api/docs/guides/prompt-caching). The cache matches requests from the beginning, so a change to the prefix can cut cache reuse from that point onward. Appending changes keeps more of the conversation eligible for cache reuse, which can substantially **lower input costs and speed up responses**.
6reasoning items from an earlier response. To preserve that reasoning when you
7manage conversation history, keep the history that produced it intact and append
8new messages and tool results at the end. The selected model and
9[`reasoning.context` setting](https://developers.openai.com/api/docs/guides/reasoning#preserve-reasoning-across-calls)
10determine which available reasoning items the model can use.
11 6
12## How history changes affect reasoning7Starting with newer frontier models, the API **will drop reasoning items** that follow a prefix change as part of our anti-distillation safeguards. When reasoning items are dropped, the model may have to redo some reasoning, which can increase token usage, cost, and latency. If the model can't recover the lost reasoning, output quality may also drop.
13 8
14For newer frontier models, the API checks the conversation history before each9To get the best performance from our models, we recommend avoiding changes to the prefix and adopting an append-only integration pattern as far as possible.
15reasoning item you send back. This history is the item's _prefix_. If you edit,
16shorten, or insert a message in that prefix, the API drops the affected
17reasoning. The request can continue with the conversation you provide, and the
18model can generate new reasoning.
19 10
20For example, an agent calls a ledger tool and uses the returned rows to11## What is a prefix change?
21investigate a discrepancy. On the next request, your app replaces those rows
22with a subtotal. The model can still reuse reasoning it used to choose the tool,
23but the API drops reasoning that depended on the original rows, even if you send the
24reasoning item back unchanged.
25 12
26## Append new instructions13A reasoning item’s prefix is the conversation history that comes before it. A prefix change modifies that earlier history—for example, by shortening a tool result, rewriting a developer message, or replacing older turns with a summary.
27 14
28When you manage history yourself, keep the previous input and the response's15## How to update integrations to avoid prefix changes
29output items in their original order. Add new instructions at the point where
30they take effect.
31 16
32This example uses the Python SDK in stateless mode with a model that supports17You can change the prefix unintentionally by updating Responses API parameters such as `tools`, `instructions`, or `text.format`, or by editing earlier `input` items. Audit your integration for these changes.
33`reasoning.context` set to `all_turns`. Stateless responses
34include encrypted reasoning content by default. See
35[Preserve reasoning without stored responses](https://developers.openai.com/api/docs/guides/reasoning#preserve-reasoning-without-stored-responses).
36 18
37Append instructions to a conversation19The table below shows common ways integrations change the prefix and how to achieve the same goals by appending to the context where possible.
38 20
39```python21| Common reason to change prefix | How to avoid prefix change |
40from openai import OpenAI22| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
23| Changing reasoning effort | Instead of changing the `reasoning.effort` parameter in the Responses API, append a [`configuration_update` item](https://developers.openai.com/api/docs/guides/reasoning#change-reasoning-mid-conversation) with the new reasoning effort to the input items list. Keep the original request-level setting the same. |
24| Changing structured output schemas | Instead of changing the `text.format` parameter in the Responses API, append a [`configuration_update` item](https://developers.openai.com/api/docs/guides/structured-outputs#change-the-response-format-mid-conversation) with the new schema to the input items list. Keep the original request-level setting the same. |
25| Changing the tools available to the agent | Instead of changing the `tools` parameter in the Responses API, use an [`additional_tools` item](https://developers.openai.com/api/docs/guides/prompt-caching#manage-tools-with-append-only-updates) to add tools, or `tool_choice` with `allowed_tools` to restrict which tools the model can call on a turn. Keep existing tool definitions in order. Append `additional_tools` with the `developer` role and a `tools` array, and replay it in its original position. |
26| Updating developer instructions | Instead of editing the original developer message, append a new `developer` message asking the model to ignore older instructions and follow the new ones you provide. For instructions scoped to a single turn, place an [explicit cache breakpoint](https://developers.openai.com/api/docs/guides/prompt-caching#how-prefix-matching-works) immediately before the latest developer message so the reusable prefix ends before that message. |
27| Compaction | Compaction changes the prefix, so cache misses are difficult to avoid in these cases.<br /><br />**OpenAI compaction:** If you use [OpenAI compaction](https://developers.openai.com/api/docs/guides/compaction) via `/responses/compact` or `context_management`, our systems retain subsequent reasoning items despite the prefix being changed. An OpenAI compaction item can appear anywhere in context. When calling `/responses/compact`, omit `instructions` and pass the returned window to the next request in its original order. If your history contains `configuration_update` items, follow the [configuration-update compaction requirements](https://developers.openai.com/api/docs/guides/reasoning#change-reasoning-mid-conversation).<br /><br />**Custom compaction:** If you use a different or home-grown compaction strategy, place the compacted item at the end of the model’s context, instead of before recent turns. Alternatively, you can accept the trade-off and have the reasoning items from the original history that follow it dropped. |
28| Shortening past tool outputs or downsizing past files / images | Some integrations truncate past items, such as tool outputs, files, or images, instead of using compaction. These modifications change the prefix. We strongly recommend either using compaction, or shortening long tool outputs and downsizing images or files before they’re sent to the model for the first time. |
41 29
42client = OpenAI()30## Auditing your integration for prefix changes
43model = "gpt-6.1-sol"
44history = [{"role": "user", "content": "Compare invoice A ($80) and B ($95)."}]
45 31
46first = client.responses.create(32Use [Prompt Cache Diagnostics](https://developers.openai.com/api/docs/guides/prompt-caching/diagnostics) to see when cache misses occur and investigate prefix changes. Compare a request with an earlier response by setting `prompt_cache_options.comparison_response_id` to the earlier response ID, then inspect the diagnostic reason and cached token count. Use this information to reduce prefix changes in your integration. Diagnostics report the first identified difference on a best-effort basis; they can’t verify whether the model reused reasoning.
47 model=model,
48 reasoning={"context": "all_turns"},
49 input=history,
50 store=False,
51)
52
53next_input = [
54 *history,
55 *(item.to_dict() for item in first.output),
56 {
57 "role": "developer",
58 "content": "For the reconciliation report, use a Markdown table.",
59 },
60 {"role": "user", "content": "Add invoice C ($110) and show the total."},
61]
62report = client.responses.create(
63 model=model,
64 reasoning={"context": "all_turns"},
65 input=next_input,
66 store=False,
67)
68print(report.output_text)
69```
70
71
72If you use stored responses, you can continue from the prior response with
73`previous_response_id` and send only the new input items. See
74[Conversation state](https://developers.openai.com/api/docs/guides/conversation-state).
75
76## Migrate away from prefix edits
77
78Compare two consecutive requests in a workflow that reuses reasoning. Find the
79first place your app changes an item it already sent, then choose the migration
80that matches the edit.
81
82| If your app edits… | Migrate to… |
83| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
84| Older turns during compaction | Use OpenAI compaction and continue from the returned context. If you create a portable text summary, let the model reason from it. Replacing the prefix can invalidate reasoning you replay after the summary. If the history includes `configuration_update` items, use an explicit `compaction_trigger`, then append a fresh update before the next user message. Restate every setting you changed, including the format if applicable. Automatic compaction, automatic truncation, and standalone `/responses/compact` don't support histories containing these updates. |
85| Developer instructions | Append a developer message when the instruction takes effect. If the response is already running, use mid-turn steering where supported. |
86| The tool list when switching modes | Keep known tool definitions stable. Restrict the next request with `tool_choice` of type `allowed_tools`. To introduce new tools, append an `additional_tools` input item with role `developer` and the definitions in `tools`. Replay it in its original position. |
87| A tool result the model has already seen | Filter the result before sending `function_call_output` the first time. If the data changes, append a correction or return it from a new tool call. |
88
89For more on managing long conversations, see
90[Compaction](https://developers.openai.com/api/docs/guides/compaction).
