guides/latest-model/gpt-5.6.md +0 −228 deleted
File Deleted View Diff
1latestModelInfo:
2 model: gpt-5.6-sol
3 migrationGuide: /api/docs/guides/upgrading-to-gpt-5p6-sol.md
4 promptingGuide: /api/docs/guides/prompt-guidance-gpt-5p6.md
5
6# Using GPT-5.6
7
8> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.
9
10## Introduction
11
12GPT-5.6 sets a new quality and efficiency baseline for complex production workflows. GPT-5.6 is especially token-efficient and improves frontend aesthetics, including layout, visual hierarchy, and design judgment.
13
14GPT-5.6 also introduces a new naming scheme. The `gpt-5.6` alias routes requests to `gpt-5.6-sol`, the model for flagship capability. Use `gpt-5.6-terra` for strong performance at a lower price and `gpt-5.6-luna` for efficient, high-volume workloads.
15
16When migrating from GPT-5.5 or GPT-5.4, start with your current GPT-5.5 or GPT-5.4 reasoning setting, then test the same setting and one level lower on representative tasks. GPT-5.6 can often maintain or improve quality with fewer tokens, but the best setting depends on your workload.
17
18<a id="what-is-new" className="scroll-mt-[110px]"></a>
19
20## What's new
21
22- **Programmatic Tool Calling:** GPT-5.6 can write JavaScript to call eligible tools, pass results between calls, and process intermediate outputs in a hosted runtime. Use [Programmatic Tool Calling](https://developers.openai.com/api/docs/guides/tools-programmatic-tool-calling) for bounded, tool-heavy workflows that do not require fresh model judgment between each step. Programmatic Tool Calling is ZDR-compatible with no additional container costs.
23- **Multi-agent [beta]:** [Multi-agent](https://developers.openai.com/api/docs/guides/responses-multi-agent) lets a GPT-5.6 instance coordinate multiple subagents in parallel and synthesize their results. Similar to ultra mode in Codex, this can reduce wall-clock time and improve performance for complex tasks that divide cleanly into independent workstreams. Multi-agent is available as a beta feature in the Responses API as we iterate on developer feedback.
24- **Explicit prompt caching:** GPT-5.6 lets you mark exactly which reusable prompt prefixes OpenAI caches. You can still use automatic caching in implicit mode. OpenAI bills cache writes at 1.25× the uncached input rate, while cache reads remain discounted. Learn how to [configure prompt caching](https://developers.openai.com/api/docs/guides/prompt-caching).
25- **Persisted reasoning:** GPT-5.6 can reuse available reasoning items across turns to improve multi-turn quality and cache efficiency. Use `reasoning.context` to select the behavior. Learn how to [preserve reasoning across calls](https://developers.openai.com/api/docs/guides/reasoning#preserve-reasoning-across-calls).
26- **Max reasoning effort:** GPT-5.6 supports `max` reasoning effort for demanding tasks that need more exploration and verification. If you currently use `xhigh`, compare both settings on representative workloads.
27- **Pro mode:** GPT-5.6 can perform more model work to improve reliability on difficult tasks and return a single final answer. Enable it with `reasoning.mode: "pro"` when quality matters more than latency and token usage. Learn how to [use pro mode](https://developers.openai.com/api/docs/guides/reasoning#reasoning-mode).
28- **Token efficiency:** GPT-5.6 reaches flagship-level performance with fewer output tokens.
29- **Frontend design:** GPT-5.6 creates more polished and usable websites and applications, with stronger layout, visual hierarchy, and design judgment.
30- **Intent understanding:** GPT-5.6 can better infer the user's underlying goal and intended level of work from context, so you often do not need to prescribe every step. Continue to provide domain context, hard constraints, approval boundaries, and success criteria. Tell the model when an important ambiguity should trigger a question.
31- **Original image detail:** GPT-5.6 preserves image dimensions with `original` or `auto` detail, except that images larger than 65,535 pixels on either side are scaled down to fit that limit. The API rejects images that still exceed the [30,000-patch limit](https://developers.openai.com/api/docs/guides/images-vision#image-input-requirements), rather than resizing them to fit it. Large images can use more input tokens and increase latency. Learn how to [choose an image detail level](https://developers.openai.com/api/docs/guides/images-vision#choose-an-image-detail-level).
32
33## Safeguards
34
35When using GPT-5.6 models, users may encounter safeguards that block or refuse some requests due to real-time cyber and biology misuse classifiers that are run as model outputs are generated. Other requests may take longer because generation is paused for several seconds mid-stream while these classifiers synchronously review outputs. Safeguards may occasionally intervene on legitimate work, particularly in dual-use areas where defensive and offensive activity can initially look similar.
36
37If your application serves individual end users, send a stable, privacy-preserving `safety_identifier` with each request. See [Implement safety identifiers](https://developers.openai.com/api/docs/guides/safety-best-practices#implement-safety-identifiers) for guidance.
38
39We are continuously evolving these safeguards so that they are robust and effective in holding up to adversarial pressure, while preserving access to legitimate work such as code review, vulnerability research, patch development, debugging, security education, and defensive testing.
40
41
42
43
44
45## Migration quickstart
46
47### Migrate with Codex
48
49Codex can apply the recommended changes in this guide with the [OpenAI Docs skill](https://github.com/openai/skills/tree/main/skills/.curated/openai-docs).
50
51```text
52$openai-docs migrate this project to the GPT-5.6 model family
53```
54
55To use this skill in other coding agents, download it from the [OpenAI skills repository](https://github.com/openai/skills/tree/main/skills/.curated/openai-docs).
56
57### Update API and model parameters
58
59- Choose the target model for the workload. Use `gpt-5.6-sol` for flagship capability, `gpt-5.6-terra` for a balance of intelligence and cost, or `gpt-5.6-luna` for efficient, high-volume workloads. The `gpt-5.6` alias routes requests to `gpt-5.6-sol`.
60- Use the [Responses API](https://developers.openai.com/api/docs/guides/migrate-to-responses) for reasoning, tool-calling, and multi-turn workflows.
61- Set `reasoning.effort` intentionally. GPT-5.6 supports `none`, `low`, `medium`, `high`, `xhigh`, and `max`.
62 - If you are migrating from GPT-5.5 or GPT-5.4, preserve your current reasoning effort as the baseline, then compare one level lower.
63 - If you use `none`, keep it as your latency baseline and also test `low` when the workflow benefits from reasoning or tool use.
64 - Use `medium` as a balanced starting point and `low` for latency-sensitive workloads.
65 - Use `high` or `xhigh` when more reasoning produces a measured quality gain.
66 - Reserve `max` for the hardest quality-first workloads. Compare `max` and `xhigh` to find the best quality, latency, and cost tradeoff for your use case.
67- To use pro mode, keep your selected GPT-5.6 model and set `reasoning.mode` to `pro` in the Responses API; do not switch to a separate Pro model slug. Choose `reasoning.effort` independently. If you omit it, GPT-5.6 defaults to `medium` in both standard and pro modes. See [reasoning mode](https://developers.openai.com/api/docs/guides/reasoning#reasoning-mode) for a request example and billing details.
68- Configure persisted reasoning based on how much prior reasoning is still relevant. GPT-5.6 models default to `all_turns`; earlier models default to `current_turn`.
69 - Omit `reasoning.context` or set it to `auto` to use `all_turns`, the GPT-5.6 default. Check the response's `reasoning.context` field to confirm the effective mode.
70 - Set `reasoning.context` to `all_turns` when the task's goals, assumptions, and priorities stay stable across turns.
71 - With `all_turns`, continue with `previous_response_id` to make reasoning from earlier responses available to the model.
72 - When managing history manually, preserve and resend previous user inputs and every response output item. For `store: false` or Zero Data Retention, replay the encrypted reasoning items that the API returns by default.
73 - Set `reasoning.context` to `current_turn` when earlier reasoning is no longer relevant.
74- Review prompt caching. You do not need to change code to keep using implicit caching. Because GPT-5.6 cache writes cost 1.25× the uncached input rate, track `cached_tokens` and `cache_write_tokens` to understand net cost. Use explicit breakpoints or `prompt_cache_options.mode: "explicit"` to avoid unnecessary writes, and replace `prompt_cache_retention` with `prompt_cache_options.ttl`.
75- To use Programmatic Tool Calling, add the `programmatic_tool_calling` tool and opt eligible tools in with `allowed_callers`. Update your application to handle `program` items, program-issued function calls, and `program_output` items while preserving each call's `call_id` and `caller` linkage. See the [Programmatic Tool Calling guide](https://developers.openai.com/api/docs/guides/tools-programmatic-tool-calling) for request and continuation examples.
76 - Benchmark the PTC-enabled workflow on representative tasks. Compare task success, final-answer completeness, required evidence, total tokens, latency, and cost. Fewer calls, turns, or intermediate outputs are improvements only when the final answer still meets the required quality bar.
77
78## Prompting best practices
79
80### Favor leaner prompts
81
82Removing repeated instructions and examples and simplifying tool descriptions can improve task performance and token efficiency. In a sample of internal coding-agent eval runs, configurations with leaner system prompts improved evaluation scores by roughly 10–15% while reducing total tokens by 41–66% and cost by 33–67%. Results will vary by workload, so treat these ranges as directional and validate changes on representative tasks from your own application.
83
84To simplify prompts without losing important guidance:
85
86- Start with a prompt and tool set that already works. Remove one group of instructions, examples, or tools at a time, then rerun the same evals.
87- State each instruction once.
88- Expose only tools relevant to the task, and keep their descriptions concise and precise.
89- Keep examples and style guidance when they encode a product requirement or correct a measured gap.
90- Track context both at the start of a run and as the conversation grows. Long sessions can amplify repeated prompt and tool content.
91
92### Define autonomy and approval boundaries
93
94GPT-5.6 can be proactive and persistent when carrying out multi-step tasks. Define what level of action each request authorizes so the model can continue safe, in-scope work without unnecessary pauses while stopping before external, destructive, costly, or scope-expanding actions.
95
96A compact policy is usually sufficient:
97
98```text
99For requests to answer, explain, review, diagnose, or plan, inspect the relevant
100materials and report the result. Do not implement changes unless the request also
101asks for them.
102
103For requests to change, build, or fix, make the requested in-scope local changes
104and run relevant non-destructive validation without asking first.
105
106Require confirmation for external writes, destructive actions, purchases, or a
107material expansion of scope.
108```
109
110Name safe local actions explicitly, such as reading files, inspecting logs, editing in-scope code, and running tests. Keep the policy in one place and state each rule once. Repeating instructions such as “ask first,” “do not mutate,” or “wait for approval” can cause unnecessary approval requests for safe, expected actions.
111
112### Set response length and style
113
114GPT-5.6 tends to be more concise by default than GPT-5.5. When migrating, check whether broad brevity instructions such as “Be concise” or “Keep it short” are still useful. They may be unnecessary for some tasks and can sometimes make responses too brief. Keep them when they reliably produce the output your application needs.
115
116For more consistent control across requests, use `text.verbosity` to set the default level of detail, then use the prompt for task-specific requirements.
117
118#### Set a default with `text.verbosity`
119
120Choose `low`, `medium`, or `high` as the default level of detail for a request. In the prompt, specify any task-specific length, structure, or required content. See [Set up `text.verbosity`](https://developers.openai.com/api/docs/guides/deployment-checklist#set-up-textverbosity) for an API example.
121
122#### Specify what a short answer must include
123
124When a task calls for a shorter answer, identify the information the model must preserve and the detail it can omit. For example:
125
126```text
127Lead with the conclusion. Include the evidence needed to support it, any material
128caveat, and the next action. Omit secondary detail and repetition.
129
130Keep all required facts, decisions, caveats, and next steps. Trim introductions,
131repetition, generic reassurance, and optional background first.
132```
133
134This gives the model a clear priority order: preserve the content needed to complete the task, then remove lower-value detail.
135
136#### Define the tone
137
138Broad labels such as “friendly” or “empathetic” can be ambiguous. Describe the writing choices that define your product's tone, such as how directly to state the answer, when to acknowledge a problem, and whether reassurance or a sign-off is appropriate.
139
140```text
141State the answer directly. If the user reports a problem, acknowledge the
142specific issue before giving the next step. Use reassurance only when it is
143relevant. Omit generic praise and unnecessary sign-offs.
144```
145
146### Pro mode
147
148#### Choose pro mode when quality matters most
149
150Pro mode is a Responses API execution mode that applies more model work to a request before returning a single final answer. It can improve reliability on difficult tasks, but it increases latency and aggregates the tokens from that work in reported usage. Those tokens are billed at the selected model's standard token rates.
151
152Use pro mode when a marginal quality improvement materially affects the outcome and the task is difficult enough to benefit, such as complex optimization, high-value coding or review, or deep analysis with clear evaluation criteria. Prefer standard mode for routine, latency-sensitive, or high-volume work, and whenever your evaluations do not show a meaningful gain from pro mode.
153
154Reasoning mode and reasoning effort are independent. Pro mode works with any GPT-5.6 model and its supported reasoning efforts. Start with the same model and effort as your standard-mode baseline, then compare configurations on representative tasks instead of assuming that the highest effort is always the best tradeoff.
155
156#### Configure pro mode in the API
157
158Enable pro mode in the API request. Keep the same outcome-focused prompt you use in standard mode: state the goal, relevant context, constraints, required evidence, success criteria, and output format. You do not need to ask the model to “use pro mode,” “think harder,” or generate several candidate answers.
159
160For example:
161
162```text
163Review this database migration plan for failure modes that could cause data loss
164or extended downtime. For each finding, cite the relevant step, estimate impact
165and likelihood, and recommend a specific mitigation. Return the five most
166important risks in severity order.
167```
168
169#### Compare quality and cost
170
171Compare standard and pro modes on the same representative tasks. Measure task success, answer completeness, required evidence, total tokens, latency, and cost. Use pro mode selectively where its quality or reliability gain justifies the extra model work.
172
173Learn more in the [reasoning mode guide](https://developers.openai.com/api/docs/guides/reasoning#reasoning-mode).
174
175### Programmatic Tool Calling
176
177#### Choose Programmatic Tool Calling by task shape
178
179Programmatic Tool Calling (PTC) works best for bounded workflows where code can process several tool results or large intermediate outputs and return a much smaller structured result. Use it for filtering, joining, ranking, deduplication, aggregation, validation, or other predictable processing.
180
181Multiple, parallel, or dependent calls alone do not justify Programmatic Tool Calling. Prefer direct, non-PTC tool calls when:
182
183- One call is sufficient
184- The intermediate outputs are already small
185- Each result may change the model’s next decision
186- An action requires approval
187- The final output must preserve citations or native artifacts
188
189#### Make routing instructions task-specific
190
191Do not rely on tool availability or generic instructions such as “use Programmatic Tool Calling efficiently” to produce the right route. When both direct and programmatic calling are available, explicitly state:
192
193- Which bounded stage should use Programmatic Tool Calling.
194- Which tools it may call.
195- The exact output schema and required evidence.
196- Concurrency, retry, and stopping limits.
197- Which work should remain direct.
198
199Tool descriptions should document their expected return fields, types, and error behavior. If the model cannot determine the return shape before writing the program, prefer direct tool calling so it can inspect the result before deciding how to use it.
200
201If both routes are needed, define one clear handoff and tell the model not to switch routes or repeat completed work.
202
203For example:
204
205```text
206<tool_orchestration>
207Use Programmatic Tool Calling for [bounded stage] using only [eligible tools].
208Run independent calls concurrently when safe. Use only documented tool input
209and output fields.
210
211Process and reduce the intermediate results, then emit exactly [output schema],
212including the evidence needed for the final answer.
213
214Stop when [condition] is met. Retry transient failures at most [R] times.
215Do not repeat completed calls or perform side-effecting actions. If a required
216result is still missing, return a clear structured failure.
217
218Use direct tool calls for [semantic judgment, approval, or final validation].
219</tool_orchestration>
220```
221
222#### Assess the final answer
223
224The `program_output` item and final assistant `message` are separate outputs; make sure to test both. In theory, a program can return the correct records while the message omits a required field, citation, or caveat.
225
226Compare direct and programmatic calling on the same representative tasks. Check whether the final response is correct, complete, and includes the required evidence. Then compare total tokens, latency, cost, calls, turns, and retries. Count lower resource use as an improvement only when the response still passes your existing evals.
227
228Learn more in the [Programmatic Tool Calling guide](https://developers.openai.com/api/docs/guides/tools-programmatic-tool-calling).