1# Using GPT-5.4
2
3## Introduction
4
5[GPT-5.4](https://developers.openai.com/api/docs/models/gpt-5.4) was released as a frontier model for professional work across the API and Codex. It helps developers analyze complex information, build production software, and automate multi-step workflows.
6
7Within the GPT-5.4 generation, `gpt-5.4` is the general-purpose model for workflows that move between software engineering, reasoning, writing, and tool use.
8
9This guide covers key features of the GPT-5 model family and how to get the most out of GPT-5.4.
10
11## What's new
12
13Compared with the previous GPT-5.2 model, GPT-5.4 shows improvements in:
14
15- Coding, document understanding, tool use, and instruction following
16- Image perception and multimodal tasks
17- Long-running task execution and multi-step agent workflows
18- Token efficiency and end-to-end performance on tool-heavy workloads
19- Web search and multi-source synthesis for hard-to-locate information
20- Document-heavy and spreadsheet-heavy business workflows in customer service, analytics, and finance
21
22GPT-5.4 brings the coding capabilities of GPT-5.3-Codex to our flagship frontier model. Developers can generate production-quality code, build polished front-end UI, follow repo-specific patterns, and handle multi-file changes with fewer retries. It also has a strong out-of-the-box coding personality, so teams spend less time on prompt tuning.
23
24For agentic workloads, GPT-5.4 reduces end-to-end time across multi-step trajectories and often completes tasks with fewer tokens and tool calls. This makes agents more responsive and lowers the cost of operating complex workflows at scale in the API and Codex.
25
26### New features in GPT-5.4
27
28Like earlier GPT-5 models, GPT-5.4 supports custom tools, parameters to control verbosity and reasoning, and an allowed tools list. GPT-5.4 also introduces several capabilities that make it easier to build powerful agent systems, operate over larger bodies of information, and run more reliable automated workflows:
29
30- **`tool_search` in the API:** GPT-5.4 improves tool search for larger tool ecosystems by using deferred tool loading. This makes tools searchable, loads only the relevant definitions, reduces token usage, and improves tool selection accuracy in real deployments. Learn more in the [tool search guide](https://developers.openai.com/api/docs/guides/tools-tool-search).
31- **1M token context window:** GPT-5.4 supports up to a 1M token context window, making it easier to analyze entire codebases, long document collections, or extended agent trajectories in a single request. Read more in the [1M context window](#1m-context-window) section.
32- **Built-in computer use:** GPT-5.4 is the first mainline model with built-in computer-use capabilities, enabling agents to interact directly with software to complete, verify, and fix tasks in a build-run-verify-fix loop. Learn more in the [computer use guide](https://developers.openai.com/api/docs/guides/tools-computer-use).
33- **Native compaction support:** GPT-5.4 is the first mainline model trained to support compaction, enabling longer agent trajectories while preserving key context.
34
35## Model, API, and feature updates
36
37Within this model generation, `gpt-5.4` is the general-purpose model for both broad tasks and coding. For more difficult problems, `gpt-5.4-pro` uses more compute to think longer and provide more consistent answers.
38
39For smaller, faster variants, start with `gpt-5.4-mini` or `gpt-5.4-nano`.
40
41To help you pick the model that best fits your use case, consider these tradeoffs:
42
43| Variant | Best for |
44| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
45| [`gpt-5.4`](https://developers.openai.com/api/docs/models/gpt-5.4) | General-purpose work, including complex reasoning, broad world knowledge, and code-heavy or multi-step agentic tasks |
46| [`gpt-5.4-pro`](https://developers.openai.com/api/docs/models/gpt-5.4-pro) | Tough problems that may take longer to solve and need deeper reasoning |
47| [`gpt-5.4-mini`](https://developers.openai.com/api/docs/models/gpt-5.4-mini) | High-volume coding, computer use, and agent workflows that still need strong reasoning |
48| [`gpt-5.4-nano`](https://developers.openai.com/api/docs/models/gpt-5.4-nano) | High-throughput tasks where speed and cost matter most |
49
50### Lower reasoning effort
51
52The `reasoning.effort` parameter controls how many reasoning tokens the model generates before producing a response. Earlier reasoning models like o3 supported only `low`, `medium`, and `high`: `low` favored speed and fewer tokens, while `high` favored more thorough reasoning.
53
54GPT-5.2 and GPT-5.4 support `none` as their lowest reasoning effort for lower-latency interactions. It is the default setting for both models. If you need more thinking, slowly increase to `medium` and experiment with results.
55
56With reasoning effort set to `none`, prompting is important. To improve the model's reasoning quality, even with the default settings, encourage it to “think” or outline its steps before answering.
57
58Reasoning effort set to none
59
60```bash
61curl --request POST \
62 --url https://api.openai.com/v1/responses \
63 --header "Authorization: Bearer $OPENAI_API_KEY" \
64 --header 'Content-type: application/json' \
65 --data '{
66 "model": "gpt-5.4",
67 "input": "Think carefully and outline your steps before answering. How much gold would it take to coat the Statue of Liberty in a 1mm layer?",
68 "reasoning": {
69 "effort": "none"
70 }
71}'
72```
73
74```javascript
75import OpenAI from "openai";
76const openai = new OpenAI();
77
78const response = await openai.responses.create({
79 model: "gpt-5.4",
80 input: "Think carefully and outline your steps before answering. How much gold would it take to coat the Statue of Liberty in a 1mm layer?",
81 reasoning: {
82 effort: "none"
83 }
84});
85
86console.log(response);
87```
88
89```python
90from openai import OpenAI
91client = OpenAI()
92
93response = client.responses.create(
94 model="gpt-5.4",
95 input="Think carefully and outline your steps before answering. How much gold would it take to coat the Statue of Liberty in a 1mm layer?",
96 reasoning={
97 "effort": "none"
98 }
99)
100
101print(response)
102```
103
104
105### Verbosity
106
107Verbosity determines how many output tokens are generated. Lowering the number of tokens reduces overall latency. While the model's reasoning approach stays mostly the same, the model finds ways to answer more concisely—which can either improve or diminish answer quality, depending on your use case. Here are some scenarios for both ends of the verbosity spectrum:
108
109- **High verbosity:** Use when you need the model to provide thorough explanations of documents or perform extensive code refactoring.
110- **Low verbosity:** Best for situations where you want concise answers or focused code generation, such as SQL queries.
111
112GPT-5 made this option configurable as one of `high`, `medium`, or `low`. With GPT-5.4, verbosity remains configurable and defaults to `medium`.
113
114When generating code with GPT-5.4, `medium` and `high` verbosity levels yield longer, more structured code with inline explanations, while `low` verbosity produces shorter, more concise code with minimal commentary.
115
116Control verbosity
117
118```bash
119curl --request POST \
120 --url https://api.openai.com/v1/responses \
121 --header "Authorization: Bearer $OPENAI_API_KEY" \
122 --header 'Content-type: application/json' \
123 --data '{
124 "model": "gpt-5.4",
125 "input": "What is the answer to the ultimate question of life, the universe, and everything?",
126 "text": {
127 "verbosity": "low"
128 }
129}'
130```
131
132```javascript
133import OpenAI from "openai";
134const openai = new OpenAI();
135
136const response = await openai.responses.create({
137 model: "gpt-5.4",
138 input: "What is the answer to the ultimate question of life, the universe, and everything?",
139 text: {
140 verbosity: "low"
141 }
142});
143
144console.log(response);
145```
146
147```python
148from openai import OpenAI
149client = OpenAI()
150
151response = client.responses.create(
152 model="gpt-5.4",
153 input="What is the answer to the ultimate question of life, the universe, and everything?",
154 text={
155 "verbosity": "low"
156 }
157)
158
159print(response)
160```
161
162
163You can still steer verbosity through prompting after setting it to `low` in the API. The verbosity parameter defines a general token range at the system prompt level, but the actual output is flexible to both developer and user prompts within that range.
164
165#### 1M context window
166
1671M token context window was introduced with GPT-5.4, making it easier to analyze entire codebases, long document collections, or extended agent trajectories in a single request.
168
169We have separate standard pricing for requests under 272K and over 272K tokens, available in the [pricing docs](https://developers.openai.com/api/docs/pricing). If you use [priority processing](https://developers.openai.com/api/docs/guides/priority-processing), any prompt above 272K tokens is automatically processed at standard rates.
170
171Long context pricing stacks with other pricing modifiers such as data residency and batch.
172
173We have different rate limits for requests under 272K tokens and over 272K tokens; this is available on the [GPT-5.4 model page](https://developers.openai.com/api/docs/models/gpt-5.4).
174
175## Using tools with GPT-5.4
176
177GPT-5.4 has been post-trained on specific tools. See the [tools docs](https://developers.openai.com/api/docs/guides/tools) for more specific guidance.
178
179### Computer use tool
180
181Computer use lets GPT-5.4 operate software through the user interface by inspecting screenshots and returning structured actions for your harness to execute. It is a good fit for browser or desktop workflows where a person could complete the task through the UI, such as navigating a site, filling out forms, or validating that a change actually worked.
182
183Use it in an isolated browser or VM, and keep a human in the loop for high-impact actions. The full guide covers the built-in Responses API loop, custom harness patterns, and code-execution-based setups.
184
185[
186
187<span slot="icon">
188 </span>
189 Learn how to run the built-in computer tool safely and integrate it with
190 your own harness.
191
192](https://developers.openai.com/api/docs/guides/tools-computer-use)
193
194### Tool search tool
195
196Tool search lets GPT-5.4 defer large tool surfaces until runtime so the model loads only the definitions it needs. This is most useful when you have many functions, `namespaces`, or MCP tools and want to reduce token usage, preserve cache performance, and improve latency without exposing every schema up front.
197
198Use hosted tool search when the candidate tools are already known at request time, or client-executed tool search when your application needs to decide what to load dynamically. The full guide also covers best practices for `namespaces`, MCP servers, and deferred loading.
199
200[
201
202<span slot="icon">
203 </span>
204 Learn how to defer tool definitions and load the right subset at runtime.
205
206](https://developers.openai.com/api/docs/guides/tools-tool-search)
207
208### Custom tools
209
210When the GPT-5 model family launched, we introduced a new capability called custom tools, which lets models send any raw text as tool call input but still constrain outputs if desired. This tool behavior remains true in GPT-5.4.
211
212[
213
214<span slot="icon">
215 </span>
216 Learn about custom tools in the function calling guide.
217
218](https://developers.openai.com/api/docs/guides/function-calling)
219
220#### Freeform inputs
221
222Define your tool with `type: custom` to enable models to send plaintext inputs directly to your tools, rather than being limited to structured JSON. The model can send any raw text—code, SQL queries, shell commands, configuration files, or long-form prose—directly to your tool.
223
224```json
225{
226 "type": "custom",
227 "name": "code_exec",
228 "description": "Executes arbitrary python code"
229}
230```
231
232#### Constraining outputs
233
234GPT-5.4 supports context-free grammars (`CFGs`) for custom tools, letting you provide a Lark grammar to constrain outputs to a specific syntax or DSL. Attaching a CFG, for example a SQL or DSL grammar, ensures the assistant's text matches your grammar.
235
236This enables precise, constrained tool calls or structured responses and lets you enforce strict syntactic or domain-specific formats directly in GPT-5.4's function calling, improving control and reliability for complex or constrained domains.
237
238#### Best practices for custom tools
239
240- **Write concise, explicit tool descriptions.** The model chooses what to send based on your description; state explicitly if you want it to always call the tool.
241- **Validate outputs on the server side**. Freeform strings are powerful but require safeguards against injection or unsafe commands.
242
243### Allowed tools
244
245The `allowed_tools` parameter under `tool_choice` lets you pass N tool definitions but restrict the model to only M (< N) of them. List your full toolkit in `tools`, and then use an `allowed_tools` block to name the subset and specify a mode—either `auto` (the model may pick any of those) or `required` (the model must invoke one).
246
247[
248
249<span slot="icon">
250 </span>
251 Learn about the allowed tools option in the function calling guide.
252
253](https://developers.openai.com/api/docs/guides/function-calling)
254
255By separating all possible tools from the subset that can be used _now_, you gain greater safety, predictability, and improved prompt caching. You also avoid brittle prompt engineering, such as hard-coded call order. GPT-5.4 dynamically invokes or requires specific functions mid-conversation while reducing the risk of unintended tool usage over long contexts.
256
257| | **Standard Tools** | **Allowed Tools** |
258| ---------------- | ----------------------------------------- | ------------------------------------------------------------- |
259| Model's universe | All tools listed under **`"tools": […]`** | Only the subset under **`"tools": […]`** in **`tool_choice`** |
260| Tool invocation | Model may or may not call any tool | Model restricted to (or required to call) chosen tools |
261| Purpose | Declare available capabilities | Constrain which capabilities are actually used |
262
263```json
264{
265 "tool_choice": {
266 "type": "allowed_tools",
267 "mode": "auto",
268 "tools": [
269 { "type": "function", "name": "get_weather" },
270 { "type": "function", "name": "search_docs" }
271 ]
272 }
273}
274```
275
276For a more detailed overview of all of these new features, see the [prompt guidance for GPT-5.4](https://developers.openai.com/api/docs/guides/latest-model?model=gpt-5.4#prompting-best-practices).
277
278### Preambles
279
280Preambles are brief, user-visible explanations that GPT-5.4 generates before invoking any tool or function, outlining its intent or plan—for example, “why I'm calling this tool.” They appear after the chain of thought and before the actual tool call, making the model's reasoning easier to understand and debug while supporting precise steering.
281
282By letting GPT-5.4 “think out loud” before each tool call, preambles boost tool-calling accuracy (and overall task success) without bloating reasoning overhead. To enable preambles, add a system or developer instruction—for example: “Before you call a tool, explain why you are calling it.” GPT-5.4 adds a concise rationale to each specified tool call. The model may also output multiple messages between tool calls, which can enhance the interaction experience—particularly for minimal reasoning or latency-sensitive use cases.
283
284For more on using preambles, see the [GPT-5 prompting cookbook](https://developers.openai.com/cookbook/examples/gpt-5/gpt-5_prompting_guide#tool-preambles).
285
286## Migration quickstart
287
288GPT-5.4 works best with the Responses API, which supports preserving reasoning context between turns to improve performance. Read below to migrate from your current model or API.
289
290### Migrating from other models to GPT-5.4
291
292Use the [OpenAI Docs
293 skill](https://github.com/openai/skills/tree/main/skills/.system/openai-docs)
294 when migrating existing prompts or workflows to GPT-5.4. It's available in our
295 public skills repository and the Codex desktop app.
296
297While the model should be close to a drop-in replacement for GPT-5.2, there are a few key changes to call out. See [Prompt guidance for GPT-5.4](https://developers.openai.com/api/docs/guides/latest-model?model=gpt-5.4#prompting-best-practices) for specific updates to make in your prompts.
298
299Using GPT-5 models with the Responses API provides improved intelligence because of the API design. The Responses API can pass the previous turn's CoT to the model. This leads to fewer generated reasoning tokens, higher cache hit rates, and less latency. To learn more, see an [in-depth guide](https://developers.openai.com/cookbook/examples/responses_api/reasoning_items) on the benefits of the Responses API.
300
301When migrating to GPT-5.4 from an older OpenAI model, start by experimenting with reasoning levels and prompting strategies. Based on our testing, we recommend using our [prompt optimizer](https://platform.openai.com/chat/edit?models=gpt-5.4&optimize=true)—which automatically updates your prompts for GPT-5.4 based on our best practices—and following this model-specific guidance:
302
303- **`gpt-5.2`**: `gpt-5.4` with default settings is meant to be a drop-in replacement.
304- **o3**: `gpt-5.4` with `medium` or `high` reasoning. Start with `medium` reasoning with prompt tuning, then increase to `high` if you aren't getting the results you want.
305- **`gpt-4.1`**: `gpt-5.4` with `none` reasoning. Start with `none` and tune your prompts; increase if you need better performance.
306- **`o4-mini` or `gpt-4.1-mini`**: `gpt-5.4-mini` with prompt tuning is a great replacement.
307- **`gpt-4.1-nano`**: `gpt-5.4-nano` with prompt tuning is a great replacement.
308
309### New `phase` parameter
310
311For long-running or tool-heavy GPT-5.4 flows in the Responses API, use the assistant message `phase` field to avoid early stopping and other misbehavior.
312
313`phase` is optional at the API level, but we highly recommend using it. Use `phase: "commentary"` for intermediate assistant updates (such as preambles before tool calls) and `phase: "final_answer"` for the completed answer. Do not add `phase` to user messages.
314
315If you use `previous_response_id`, that is usually the simplest path because
316 prior assistant state is preserved. If you replay assistant history manually,
317 preserve each original `phase` value.
318
319Missing or dropped `phase` can cause preambles to be treated as final answers
320in those workflows. For additional guidance and examples, see the [GPT-5.4
321prompting guide](https://developers.openai.com/api/docs/guides/latest-model?model=gpt-5.4#phase-parameter).
322
323Round-trip assistant phase values
324
325```javascript
326import OpenAI from "openai";
327const client = new OpenAI();
328
329const response = await client.responses.create({
330 model: "gpt-5.4",
331 input: [
332 {
333 role: "assistant",
334 phase: "commentary",
335 content:
336 "I’ll inspect the logs and then summarize root cause and remediation.",
337 },
338 {
339 role: "assistant",
340 phase: "final_answer",
341 content: "Root cause: cache invalidation race.",
342 },
343 {
344 role: "user",
345 content: "Great—now give me a rollout-safe fix plan.",
346 },
347 ],
348});
349
350console.log(response.output_text);
351```
352
353```python
354from openai import OpenAI
355
356client = OpenAI()
357
358response = client.responses.create(
359 model="gpt-5.4",
360 input=[
361 {
362 "role": "assistant",
363 "phase": "commentary",
364 "content": "I’ll inspect the logs and then summarize root cause and remediation.",
365 },
366 {
367 "role": "assistant",
368 "phase": "final_answer",
369 "content": "Root cause: cache invalidation race.",
370 },
371 {
372 "role": "user",
373 "content": "Great—now give me a rollout-safe fix plan.",
374 },
375 ],
376)
377
378print(response.output_text)
379```
380
381
382### GPT-5.4 parameter compatibility
383
384The following parameters are **only supported** when using GPT-5.4 with reasoning effort set to `none`:
385
386- `temperature`
387- `top_p`
388- `logprobs`
389
390Requests to GPT-5.4 or GPT-5.2 with any other reasoning effort setting, or to older GPT-5 models—for example, `gpt-5`, `gpt-5-mini`, or `gpt-5-nano`—that include these fields will raise an error.
391
392To achieve similar results with reasoning effort set higher, or with another GPT-5 family model, try these alternative parameters:
393
394- **Reasoning depth:** `reasoning: { effort: "none" | "low" | "medium" | "high" | "xhigh" }`
395- **Output verbosity:** `text: { verbosity: "low" | "medium" | "high" }`
396- **Output length:** `max_output_tokens`
397
398### Migrating from Chat Completions to Responses API
399
400The biggest difference, and main reason to migrate from Chat Completions to the Responses API for GPT-5.4, is support for passing chain of thought (CoT) between turns. See a full [comparison of the APIs](https://developers.openai.com/api/docs/guides/responses-vs-chat-completions).
401
402Passing CoT exists only in the Responses API, and we've seen improved intelligence, fewer generated reasoning tokens, higher cache hit rates, and lower latency as a result of doing so. Most other parameters remain at parity, though the formatting is different. Here's how new parameters are handled differently between Chat Completions and the Responses API:
403
404**Reasoning effort**
405
406
407
408<div data-content-switcher-pane data-value="responses">
409 <div class="hidden">Responses API</div>
410 Generate response with reasoning effort set to none
411
412```bash
413curl --request POST \
414 --url https://api.openai.com/v1/responses \
415 --header "Authorization: Bearer $OPENAI_API_KEY" \
416 --header "Content-type: application/json" \
417 --data '{
418 "model": "gpt-5.4",
419 "input": "How much gold would it take to coat the Statue of Liberty in a 1mm layer?",
420 "reasoning": {
421 "effort": "none"
422 }
423}'
424```
425
426 </div>
427 <div data-content-switcher-pane data-value="chat" hidden>
428 <div class="hidden">Chat Completions</div>
429 Generate response with reasoning effort set to none
430
431```bash
432curl --request POST \
433 --url https://api.openai.com/v1/chat/completions \
434 --header "Authorization: Bearer $OPENAI_API_KEY" \
435 --header "Content-type: application/json" \
436 --data '{
437 "model": "gpt-5.4",
438 "messages": [
439 {
440 "role": "user",
441 "content": "How much gold would it take to coat the Statue of Liberty in a 1mm layer?"
442 }
443 ],
444 "reasoning_effort": "none"
445}'
446```
447
448 </div>
449
450
451
452**Verbosity**
453
454
455
456<div data-content-switcher-pane data-value="responses">
457 <div class="hidden">Responses API</div>
458 Control verbosity
459
460```bash
461curl --request POST \
462 --url https://api.openai.com/v1/responses \
463 --header "Authorization: Bearer $OPENAI_API_KEY" \
464 --header "Content-type: application/json" \
465 --data '{
466 "model": "gpt-5.4",
467 "input": "What is the answer to the ultimate question of life, the universe, and everything?",
468 "text": {
469 "verbosity": "low"
470 }
471}'
472```
473
474 </div>
475 <div data-content-switcher-pane data-value="chat" hidden>
476 <div class="hidden">Chat Completions</div>
477 Control verbosity
478
479```bash
480curl --request POST \
481 --url https://api.openai.com/v1/chat/completions \
482 --header "Authorization: Bearer $OPENAI_API_KEY" \
483 --header "Content-type: application/json" \
484 --data '{
485 "model": "gpt-5.4",
486 "messages": [
487 {
488 "role": "user",
489 "content": "What is the answer to the ultimate question of life, the universe, and everything?"
490 }
491 ],
492 "verbosity": "low"
493}'
494```
495
496 </div>
497
498
499
500**Custom tools**
501
502
503
504<div data-content-switcher-pane data-value="responses">
505 <div class="hidden">Responses API</div>
506 Custom tool call
507
508```bash
509curl --request POST \
510 --url https://api.openai.com/v1/responses \
511 --header "Authorization: Bearer $OPENAI_API_KEY" \
512 --header "Content-type: application/json" \
513 --data '{
514 "model": "gpt-5.4",
515 "input": "Use the code_exec tool to calculate the area of a circle with radius equal to the number of r letters in blueberry",
516 "tools": [
517 {
518 "type": "custom",
519 "name": "code_exec",
520 "description": "Executes arbitrary Python code"
521 }
522 ]
523}'
524```
525
526 </div>
527 <div data-content-switcher-pane data-value="chat" hidden>
528 <div class="hidden">Chat Completions</div>
529 Custom tool call
530
531```bash
532curl --request POST \
533 --url https://api.openai.com/v1/chat/completions \
534 --header "Authorization: Bearer $OPENAI_API_KEY" \
535 --header "Content-type: application/json" \
536 --data '{
537 "model": "gpt-5.4",
538 "messages": [
539 {
540 "role": "user",
541 "content": "Use the code_exec tool to calculate the area of a circle with radius equal to the number of r letters in blueberry"
542 }
543 ],
544 "tools": [
545 {
546 "type": "custom",
547 "custom": {
548 "name": "code_exec",
549 "description": "Executes arbitrary Python code"
550 }
551 }
552 ]
553}'
554```
555
556 </div>
557
558
559
560
561## Prompting best practices
562
563When troubleshooting cases where GPT-5.4 treats an intermediate update as the
564 final answer, verify your integration preserves the assistant message `phase`
565 field correctly. See [Phase parameter](#phase-parameter) for details.
566
567### Understand GPT-5.4 behavior
568
569#### Where GPT-5.4 is strongest
570
571GPT-5.4 tends to work especially well in these areas:
572
573- Strong personality and tone adherence, with less drift over long answers
574- Agentic workflow robustness, with a stronger tendency to stick with multi-step work, retry, and complete agent loops end to end
575- Evidence-rich synthesis, especially in long-context or multi-tool workflows
576- Instruction adherence in modular, skill-based, and block-structured prompts when the contract is explicit
577- Long-context analysis across large, messy, or multi-document inputs
578- Batched or parallel tool calling while maintaining tool-call accuracy
579- Spreadsheet, finance, and Excel workflows that need instruction following, formatting fidelity, and stronger self-verification
580
581#### Where explicit prompting still helps
582
583Even with those strengths, GPT-5.4 benefits from more explicit guidance in a few recurring patterns:
584
585- Low-context tool routing early in a session, when tool selection can be less reliable
586- Dependency-aware workflows that need explicit prerequisite and downstream-step checks
587- Reasoning effort selection, where higher effort is not always better and the right choice depends on task shape, not intuition
588- Research tasks that require disciplined source collection and consistent citations
589- Irreversible or high-impact actions that require verification before execution
590- Terminal or coding-agent environments where tool boundaries must stay clear
591
592These patterns are observed defaults, not guarantees. Start with the smallest prompt that passes your evals, and add blocks only when they fix a measured failure mode.
593
594### Use core prompt patterns
595
596#### Keep outputs compact and structured
597
598To improve token efficiency with GPT-5.4, constrain verbosity and enforce structured output through clear output contracts. In practice, this acts as an additional control layer alongside the `verbosity` parameter in the Responses API, allowing you to guide both how much the model writes and how it structures the output.
599
600```xml
601<output_contract>
602- Return exactly the sections requested, in the requested order.
603- If the prompt defines a preamble, analysis block, or working section, do not treat it as extra output.
604- Apply length limits only to the section they are intended for.
605- If a format is required (JSON, Markdown, SQL, XML), output only that format.
606</output_contract>
607
608<verbosity_controls>
609- Prefer concise, information-dense writing.
610- Avoid repeating the user's request.
611- Keep progress updates brief.
612- Do not shorten the answer so aggressively that required evidence, reasoning, or completion checks are omitted.
613</verbosity_controls>
614```
615
616#### Set clear defaults for follow-through
617
618Users often change the task, format, or tone mid-conversation. To keep the assistant aligned, define clear rules for when to proceed, when to ask, and how newer instructions override earlier defaults.
619
620Use a default follow-through policy like this:
621
622```xml
623<default_follow_through_policy>
624- If the user’s intent is clear and the next step is reversible and low-risk, proceed without asking.
625- Ask permission only if the next step is:
626 (a) irreversible,
627 (b) has external side effects (for example sending, purchasing, deleting, or writing to production), or
628 (c) requires missing sensitive information or a choice that would materially change the outcome.
629- If proceeding, briefly state what you did and what remains optional.
630</default_follow_through_policy>
631```
632
633Make instruction priority explicit:
634
635```xml
636<instruction_priority>
637- User instructions override default style, tone, formatting, and initiative preferences.
638- Safety, honesty, privacy, and permission constraints do not yield.
639- If a newer user instruction conflicts with an earlier one, follow the newer instruction.
640- Preserve earlier instructions that do not conflict.
641</instruction_priority>
642```
643
644Higher-priority developer or system instructions remain binding.
645
646**Guidance:** When instructions change mid-conversation, make the update explicit, scoped, and local. State what changed, what still applies, and whether the change affects the next turn or the rest of the conversation.
647
648#### Handle mid-conversation instruction updates
649
650For mid-conversation updates, use explicit, scoped steering messages that state:
651
6521. Scope
6532. Override
6543. Carry forward
655
656```text
657<task_update>
658For the next response only:
659- Do not complete the task.
660- Only produce a plan.
661- Keep it to 5 bullets.
662
663All earlier instructions still apply unless they conflict with this update.
664</task_update>
665```
666
667If the task itself changes, say so directly:
668
669```text
670<task_update>
671The task has changed.
672Previous task: complete the workflow.
673Current task: review the workflow and identify risks only.
674
675Rules for this turn:
676- Do not execute actions.
677- Do not call destructive tools.
678- Return exactly:
679 1. Main risks
680 2. Missing information
681 3. Recommended next step
682</task_update>
683```
684
685#### Make tool use persistent when correctness depends on it
686
687Use explicit rules to keep tool use thorough, dependency-aware, and appropriately paced, especially in workflows where later actions rely on earlier retrieval or verification. A common failure mode is skipping prerequisites because the right end state seems obvious.
688
689GPT-5.4 can be less reliable at tool routing early in a session, when context is still thin. Prompt for prerequisites, dependency checks, and exact tool intent.
690
691```xml
692<tool_persistence_rules>
693- Use tools whenever they materially improve correctness, completeness, or grounding.
694- Do not stop early when another tool call is likely to materially improve correctness or completeness.
695- Keep calling tools until:
696 (1) the task is complete, and
697 (2) verification passes (see <verification_loop>).
698- If a tool returns empty or partial results, retry with a different strategy.
699</tool_persistence_rules>
700```
701
702This is especially important for workflows where the final action depends on earlier lookup or retrieval steps. One of the most common failure modes is skipping prerequisites because the intended end state seems obvious.
703
704```xml
705<dependency_checks>
706- Before taking an action, check whether prerequisite discovery, lookup, or memory retrieval steps are required.
707- Do not skip prerequisite steps just because the intended final action seems obvious.
708- If the task depends on the output of a prior step, resolve that dependency first.
709</dependency_checks>
710```
711
712Prompt for parallelism when the work is independent and wall-clock matters. Prompt for sequencing when dependencies, ambiguity, or irreversible actions matter more than speed.
713
714```xml
715<parallel_tool_calling>
716- When multiple retrieval or lookup steps are independent, prefer parallel tool calls to reduce wall-clock time.
717- Do not parallelize steps that have prerequisite dependencies or where one result determines the next action.
718- After parallel retrieval, pause to synthesize the results before making more calls.
719- Prefer selective parallelism: parallelize independent evidence gathering, not speculative or redundant tool use.
720</parallel_tool_calling>
721```
722
723#### Force completeness on long-horizon tasks
724
725For multi-step workflows, a common failure mode is incomplete execution: the model finishes after partial coverage, misses items in a batch, or treats empty or narrow retrieval as final. GPT-5.4 becomes more reliable when the prompt defines explicit completion rules and recovery behavior.
726
727Coverage can be achieved through sequential or parallel retrieval, but completion rules should remain explicit either way.
728
729```xml
730<completeness_contract>
731- Treat the task as incomplete until all requested items are covered or explicitly marked [blocked].
732- Keep an internal checklist of required deliverables.
733- For lists, batches, or paginated results:
734 - determine expected scope when possible,
735 - track processed items or pages,
736 - confirm coverage before finalizing.
737- If any item is blocked by missing data, mark it [blocked] and state exactly what is missing.
738</completeness_contract>
739```
740
741For workflows where empty, partial, or noisy retrieval is common:
742
743```xml
744<empty_result_recovery>
745If a lookup returns empty, partial, or suspiciously narrow results:
746- do not immediately conclude that no results exist,
747- try at least one or two fallback strategies,
748 such as:
749 - alternate query wording,
750 - broader filters,
751 - a prerequisite lookup,
752 - or an alternate source or tool,
753- Only then report that no results were found, along with what you tried.
754</empty_result_recovery>
755```
756
757#### Add a verification loop before high-impact actions
758
759Once the workflow appears complete, add a lightweight verification step before returning the answer or taking an irreversible action. This helps catch requirement misses, grounding issues, and format drift before commit.
760
761```xml
762<verification_loop>
763Before finalizing:
764- Check correctness: does the output satisfy every requirement?
765- Check grounding: are factual claims backed by the provided context or tool outputs?
766- Check formatting: does the output match the requested schema or style?
767- Check safety and irreversibility: if the next step has external side effects, ask permission first.
768</verification_loop>
769```
770
771```xml
772<missing_context_gating>
773- If required context is missing, do NOT guess.
774- Prefer the appropriate lookup tool when the missing context is retrievable; ask a minimal clarifying question only when it is not.
775- If you must proceed, label assumptions explicitly and choose a reversible action.
776</missing_context_gating>
777```
778
779For agents that actively take actions, add a short execution frame:
780
781```xml
782<action_safety>
783- Pre-flight: summarize the intended action and parameters in 1-2 lines.
784- Execute via tool.
785- Post-flight: confirm the outcome and any validation that was performed.
786</action_safety>
787```
788
789### Handle specialized workflows
790
791#### Choose image detail explicitly for vision and computer use
792
793If your workflow depends on visual precision, specify the image `detail` level in the prompt or integration instead of relying on `auto`. Use `high` for standard high-fidelity image understanding. Use `original` for large, dense, or spatially sensitive images, especially [computer use, localization, OCR, and click-accuracy tasks](https://developers.openai.com/api/docs/guides/tools-computer-use) on `gpt-5.4` and future models. Use `low` only when speed and cost matter more than fine detail. For more details on image detail levels, see the [Images and Vision guide](https://developers.openai.com/api/docs/guides/images-vision).
794
795#### Lock research and citations to retrieved evidence
796
797When citation quality matters, make both the source boundary and the format requirement explicit. This helps reduce fabricated references, unsupported claims, and citation-format drift.
798
799```xml
800<citation_rules>
801- Only cite sources retrieved in the current workflow.
802- Never fabricate citations, URLs, IDs, or quote spans.
803- Use exactly the citation format required by the host application.
804- Attach citations to the specific claims they support, not only at the end.
805</citation_rules>
806```
807
808```xml
809<grounding_rules>
810- Base claims only on provided context or tool outputs.
811- If sources conflict, state the conflict explicitly and attribute each side.
812- If the context is insufficient or irrelevant, narrow the answer or say you cannot support the claim.
813- If a statement is an inference rather than a directly supported fact, label it as an inference.
814</grounding_rules>
815```
816
817If your application requires inline citations, require inline citations. If it requires footnotes, require footnotes. The key is to lock the format and prevent the model from improvising unsupported references.
818
819#### Research mode
820
821Push GPT-5.4 into a disciplined research mode. Use this pattern for research, review, and synthesis tasks. Do not force it onto short execution tasks or simple deterministic transforms.
822
823```xml
824<research_mode>
825- Do research in 3 passes:
826 1) Plan: list 3-6 sub-questions to answer.
827 2) Retrieve: search each sub-question and follow 1-2 second-order leads.
828 3) Synthesize: resolve contradictions and write the final answer with citations.
829- Stop only when more searching is unlikely to change the conclusion.
830</research_mode>
831```
832
833If your host environment uses a specific research tool or requires a submit step, combine this with the host's finalization contract.
834
835#### Clamp strict output formats
836
837For SQL, JSON, or other parse-sensitive outputs, tell GPT-5.4 to emit only the target format and check it before finishing.
838
839```text
840<structured_output_contract>
841- Output only the requested format.
842- Do not add prose or markdown fences unless they were requested.
843- Validate that parentheses and brackets are balanced.
844- Do not invent tables or fields.
845- If required schema information is missing, ask for it or return an explicit error object.
846</structured_output_contract>
847```
848
849If you are extracting document regions or OCR boxes, define the coordinate system and add a drift check:
850
851```text
852<bbox_extraction_spec>
853- Use the specified coordinate format exactly, such as [x1,y1,x2,y2] normalized to 0..1.
854- For each box, include page, label, text snippet, and confidence.
855- Add a vertical-drift sanity check so boxes stay aligned with the correct line of text.
856- If the layout is dense, process page by page and do a second pass for missed items.
857</bbox_extraction_spec>
858```
859
860#### Keep tool boundaries explicit in coding and terminal agents
861
862In coding agents, GPT-5.4 works better when the rules for shell access and file editing are unambiguous. This is especially important when you expose tools like [Shell](https://developers.openai.com/api/docs/guides/tools-shell) or [Apply patch](https://developers.openai.com/api/docs/guides/tools-apply-patch).
863
864#### User updates
865
866GPT-5.4 does well with brief, outcome-based updates. Reuse the user-updates pattern from the 5.2 guide, but pair it with explicit completion and verification requirements.
867
868Recommended update spec:
869
870```xml
871<user_updates_spec>
872- Only update the user when starting a new major phase or when something changes the plan.
873- Each update: 1 sentence on outcome + 1 sentence on next step.
874- Do not narrate routine tool calls.
875- Keep the user-facing status short; keep the work exhaustive.
876</user_updates_spec>
877```
878
879For coding agents, see the Prompting patterns for coding tasks section below for more specific guidance.
880
881#### Prompting patterns for coding tasks
882
883**Autonomy and persistence**
884
885GPT-5.4 is generally more thorough end to end than earlier mainline models on coding and tool-use tasks, so you often need less explicit "verify everything" prompting. Still, for high-stakes changes such as production, migrations, or security work, keep a lightweight verification clause.
886
887```xml
888<autonomy_and_persistence>
889Persist until the task is fully handled end-to-end within the current turn whenever feasible: do not stop at analysis or partial fixes; carry changes through implementation, verification, and a clear explanation of outcomes unless the user explicitly pauses or redirects you.
890
891Unless the user explicitly asks for a plan, asks a question about the code, is brainstorming potential solutions, or some other intent that makes it clear that code should not be written, assume the user wants you to make code changes or run tools to solve the user's problem. In these cases, it's bad to output your proposed solution in a message, you should go ahead and actually implement the change. If you encounter challenges or blockers, you should attempt to resolve them yourself.
892</autonomy_and_persistence>
893```
894
895**Intermediary updates**
896
897Keep updates sparse and high-signal. In coding tasks, prefer updates at key points.
898
899```xml
900<user_updates_spec>
901- Intermediary updates go to the `commentary` channel.
902- User updates are short updates while you are working. They are not final answers.
903- Use 1-2 sentence updates to communicate progress and new information while you work.
904- Do not begin responses with conversational interjections or meta commentary. Avoid openers such as acknowledgements ("Done -", "Got it", or "Great question") or similar framing.
905- Before exploring or doing substantial work, send a user update explaining your understanding of the request and your first step. Avoid commenting on the request or starting with phrases such as "Got it" or "Understood."
906- Provide updates roughly every 30 seconds while working.
907- When exploring, explain what context you are gathering and what you learned. Vary sentence structure so the updates do not become repetitive.
908- When working for a while, keep updates informative and varied, but stay concise.
909- When work is substantial, provide a longer plan after you have enough context. This is the only update that may be longer than 2 sentences and may contain formatting.
910- Before file edits, explain what you are about to change.
911- While thinking, keep the user informed of progress without narrating every tool call. Even if you are not taking actions, send frequent progress updates rather than going silent, especially if you are thinking for more than a short stretch.
912- Keep the tone of progress updates consistent with the assistant's overall personality.
913</user_updates_spec>
914```
915
916**Formatting**
917
918GPT-5.4 often defaults to more structured formatting and may overuse bullet lists. If you want a clean final response, explicitly clamp list shape.
919
920```xml
921Never use nested bullets. Keep lists flat (single level). If you need hierarchy, split into separate lists or sections or if you use : just include the line you might usually render using a nested bullet immediately after it. For numbered lists, only use the `1. 2. 3.` style markers (with a period), never `1)`.
922```
923
924**Frontend tasks**
925
926Use this only when additional frontend guidance is useful.
927
928```xml
929<frontend_tasks>
930When doing frontend design tasks, avoid generic, overbuilt layouts.
931
932Use these hard rules:
933- One composition: The first viewport must read as one composition, not a dashboard, unless it is a dashboard.
934- Brand first: On branded pages, the brand or product name must be a hero-level signal, not just nav text or an eyebrow. No headline should overpower the brand.
935- Brand test: If the first viewport could belong to another brand after removing the nav, the branding is too weak.
936- Full-bleed hero only: On landing pages and promotional surfaces, the hero image should usually be a dominant edge-to-edge visual plane or background. Do not default to inset hero images, side-panel hero images, rounded media cards, tiled collages, or floating image blocks unless the existing design system clearly requires them.
937- Hero budget: The first viewport should usually contain only the brand, one headline, one short supporting sentence, one CTA group, and one dominant image. Do not place stats, schedules, event listings, address blocks, promos, "this week" callouts, metadata rows, or secondary marketing content there.
938- No hero overlays: Do not place detached labels, floating badges, promo stickers, info chips, or callout boxes on top of hero media.
939- Cards: Default to no cards. Never use cards in the hero unless they are the container for a user interaction. If removing a border, shadow, background, or radius does not hurt interaction or understanding, it should not be a card.
940- One job per section: Each section should have one purpose, one headline, and usually one short supporting sentence.
941- Real visual anchor: Imagery should show the product, place, atmosphere, or context.
942- Reduce clutter: Avoid pill clusters, stat strips, icon rows, boxed promos, schedule snippets, and competing text blocks.
943- Use motion to create presence and hierarchy, not noise. Ship 2-3 intentional motions for visually led work, and prefer Framer Motion when it is available.
944
945Exception: If working within an existing website or design system, preserve the established patterns, structure, and visual language.
946</frontend_tasks>
947```
948
949```xml
950<terminal_tool_hygiene>
951- Only run shell commands via the terminal tool.
952- Never "run" tool names as shell commands.
953- If a patch or edit tool exists, use it directly; do not attempt it in bash.
954- After changes, run a lightweight verification step such as ls, tests, or a build before declaring the task done.
955</terminal_tool_hygiene>
956```
957
958#### Document localization and OCR boxes
959
960For bbox tasks, be explicit about coordinate conventions and add drift tests.
961
962```xml
963<bbox_extraction_spec>
964- Use the specified coordinate format exactly (for example [x1,y1,x2,y2] normalized 0..1).
965- For each bbox, include: page, label, text snippet, confidence.
966- Add a vertical-drift sanity check:
967 - ensure bboxes align with the line of text (not shifted up or down).
968- If dense layout, process page by page and do a second pass for missed items.
969</bbox_extraction_spec>
970```
971
972#### Use runtime and API integration notes
973
974For long-running or tool-heavy agents, the runtime contract matters as much as the prompt contract.
975
976##### Phase parameter
977
978For GPT-5.4, `gpt-5.3-codex`, and later Responses models, the `phase` field can
979help in the small number of long-running or tool-heavy flows where preambles or
980other intermediate assistant updates are mistaken for the final answer.
981
982- `phase` is optional at the API level, but it is highly recommended. Best-effort inference may exist server-side, but explicit round-tripping of `phase` is strictly better.
983- Use `phase` for long-running or tool-heavy agents that may emit commentary before tool calls or before a final answer.
984- Preserve `phase` when replaying prior assistant items so the model can distinguish working commentary from the completed answer. This matters most in multi-step flows with preambles, tool-related updates, or multiple assistant messages in the same turn.
985- Do not add `phase` to user messages.
986- If you use `previous_response_id`, that is usually the simplest path, since OpenAI can often recover prior state without manually replaying assistant items.
987- If you replay assistant history yourself, preserve the original `phase` values.
988- Missing or dropped `phase` can cause preambles to be interpreted as final answers and degrade behavior on those multi-step tasks.
989
990#### Preserve behavior in long sessions
991
992Compaction unlocks significantly longer effective context windows, where user conversations can persist for many turns without hitting context limits or long-context performance degradation, and agents can perform very long trajectories that exceed a typical context window for long-running, complex tasks.
993
994If you are using [Compaction](https://developers.openai.com/api/docs/guides/compaction) in the Responses API, compact after major milestones, treat compacted items as opaque state, and keep prompts functionally identical after compaction. The endpoint is ZDR compatible and returns an `encrypted_content` item that you can pass into future requests. GPT-5.4 tends to remain more coherent and reliable over longer, multi-turn conversations with fewer breakdowns as sessions grow.
995
996For more guidance, see the [`/responses/compact` API reference](https://developers.openai.com/api/docs/api-reference/responses/compact).
997
998#### Control personality for customer-facing workflows
999
1000GPT-5.4 can be steered more effectively when you separate persistent personality from per-response writing controls. This is especially useful for customer-facing workflows such as emails, support replies, announcements, and blog-style content.
1001
1002- **Personality (persistent):** sets the default tone, verbosity, and decision style across the session.
1003- **Writing controls (per response):** define the channel, register, formatting, and length for a specific artifact.
1004- **Reminder:** personality should not override task-specific output requirements. If the user asks for JSON, return JSON.
1005
1006For natural, high-quality prose, the highest-leverage controls are:
1007
1008- Give the model a clear persona.
1009- Specify the channel and emotional register.
1010- Explicitly ban formatting when you want prose.
1011- Use hard length limits.
1012
1013```xml
1014<personality_and_writing_controls>
1015- Persona: <one sentence>
1016- Channel: <Slack | email | memo | PRD | blog>
1017- Emotional register: <direct/calm/energized/etc.> + "not <overdo this>"
1018- Formatting: <ban bullets/headers/markdown if you want prose>
1019- Length: <hard limit, e.g. <=150 words or 3-5 sentences>
1020- Default follow-through: if the request is clear and low-risk, proceed without asking permission.
1021</personality_and_writing_controls>
1022```
1023
1024For more personality patterns you can lift directly, see the [Prompt Personalities cookbook](https://developers.openai.com/cookbook/examples/gpt-5/prompt_personalities).
1025
1026**Professional memo mode**
1027
1028For memos, reviews, and other professional writing tasks, general writing instructions are often not enough. These workflows benefit from explicit guidance on specificity, domain conventions, synthesis, and calibrated certainty.
1029
1030```xml
1031<memo_mode>
1032- Write in a polished, professional memo style.
1033- Use exact names, dates, entities, and authorities when supported by the record.
1034- Follow domain-specific structure if one is requested.
1035- Prefer precise conclusions over generic hedging.
1036- When uncertainty is real, tie it to the exact missing fact or conflicting source.
1037- Synthesize across documents rather than summarizing each one independently.
1038</memo_mode>
1039```
1040
1041This mode is especially useful for legal, policy, research, and executive-facing writing, where the goal is not just fluency, but disciplined synthesis and clear conclusions.
1042
1043### Tune reasoning and migration
1044
1045#### Treat reasoning effort as a last-mile knob
1046
1047Reasoning effort is not one-size-fits-all. Treat it as a last-mile tuning knob, not the primary way to improve quality. In many cases, stronger prompts, clear output contracts, and lightweight verification loops recover much of the performance teams might otherwise seek through higher reasoning settings.
1048
1049Recommended defaults:
1050
1051- `none`: Best for fast, cost-sensitive, latency-sensitive tasks where the model does not need to think.
1052- `low`: Works well for latency-sensitive tasks where a small amount of thinking can produce a meaningful accuracy gain, especially with complex instructions.
1053- `medium` or `high`: Reserve for tasks that truly require stronger reasoning and can absorb the latency and cost tradeoff. Choose between them based on how much performance gain your task gets from additional reasoning.
1054- `xhigh`: Avoid as a default unless your evals show clear benefits. It is best suited for long, agentic, reasoning-heavy tasks where maximum intelligence matters more than speed or cost.
1055
1056In practice, most teams should default to the `none`, `low`, or `medium` range.
1057
1058Start with `none` for execution-heavy workloads such as workflow steps, field extraction, support triage, and short structured transforms.
1059
1060Start with `medium` or higher for research-heavy workloads such as long-context synthesis, multi-document review, conflict resolution, and strategy writing. With `medium` and a well-engineered prompt, you can squeeze out a lot of performance.
1061
1062For GPT-5.4 workloads, `none` can already perform well on action-selection and tool-discipline tasks. If your workload depends on nuanced interpretation, such as implicit requirements, ambiguity, or cancelled-tool-call recovery, start with `low` or `medium` instead.
1063
1064Before increasing reasoning effort, first add:
1065
1066- `<completeness_contract>`
1067- `<verification_loop>`
1068- `<tool_persistence_rules>`
1069
1070If the model still feels too literal or stops at the first plausible answer, add an initiative nudge before raising reasoning effort:
1071
1072```xml
1073<dig_deeper_nudge>
1074- Don’t stop at the first plausible answer.
1075- Look for second-order issues, edge cases, and missing constraints.
1076- If the task is safety or accuracy critical, perform at least one verification step.
1077</dig_deeper_nudge>
1078```
1079
1080#### Migrate prompts to GPT-5.4 one change at a time
1081
1082Use the same one-change-at-a-time discipline as the 5.2 guide: switch model first, pin `reasoning_effort`, run evals, then iterate.
1083
1084These starting points work well for many migrations:
1085
1086| Current setup | Suggested GPT-5.4 start | Notes |
1087| ------------------------- | ---------------------------------- | ------------------------------------------------------------------- |
1088| `gpt-5.2` | Match the current reasoning effort | Preserve the existing latency and quality profile first, then tune. |
1089| `gpt-5.3-codex` | Match the current reasoning effort | For coding workflows, keep the reasoning effort the same. |
1090| `gpt-4.1` or `gpt-4o` | `none` | Keep snappy behavior, and increase only if evals regress. |
1091| Research-heavy assistants | `medium` or `high` | Use explicit research multi-pass and citation gating. |
1092| Long-horizon agents | `medium` or `high` | Add tool persistence and completeness accounting. |
1093
1094#### Small-model guidance for `gpt-5.4-mini` and `gpt-5.4-nano`
1095
1096`gpt-5.4-mini` and `gpt-5.4-nano` are highly steerable, but they are less likely than larger models to infer missing steps, resolve ambiguity implicitly, or package outputs the way you intended unless you specify that behavior directly. In practice, prompts for smaller models are often a bit longer and more explicit.
1097
1098**How `gpt-5.4-mini` differs**
1099
1100- `gpt-5.4-mini` is more literal and makes fewer assumptions.
1101- It is strong when the task is clearly structured, but weaker on implicit workflows and ambiguity handling.
1102- By default, it may try to keep the conversation going with a follow-up question unless you suppress that behavior explicitly.
1103
1104**Prompting `gpt-5.4-mini`**
1105
1106- Put critical rules first.
1107- Specify the full execution order when tool use or side effects matter.
1108- Do not rely on "you MUST" alone. Use structural scaffolding such as numbered steps, decision rules, and explicit action definitions.
1109- Separate "do the action" from "report the action."
1110- Show the correct flow, not just the final format.
1111- Define ambiguity behavior explicitly: when to ask, abstain, or proceed.
1112- Specify packaging directly: answer length, whether to ask a follow-up question, citation style, and section order.
1113- Be careful with `output nothing else`. Prefer scoped instructions such as `after the final JSON, output nothing further`.
1114
1115**Prompting `gpt-5.4-nano`**
1116
1117- Use `gpt-5.4-nano` only for narrow, well-bounded tasks.
1118- Prefer closed outputs: labels, enums, short JSON, or fixed templates.
1119- Avoid multi-step orchestration unless the flow is extremely constrained.
1120- Route ambiguous or planning-heavy tasks to a stronger model instead of over-prompting `gpt-5.4-nano`.
1121
1122**Good default pattern**
1123
11241. Task
11252. Critical rule
11263. Exact step order
11274. Edge cases or clarification behavior
11285. Output format
11296. One correct example
1130
1131**Avoid**
1132
1133- Implied next steps
1134- Unspecified edge cases
1135- Schema-only prompts for tool workflows
1136- Generic instructions without structure
1137
1138#### Web search and deep research
1139
1140If you are migrating a research agent in particular, make these prompt updates before increasing reasoning effort:
1141
1142- Add `<research_mode>`
1143- Add `<citation_rules>`
1144- Add `<empty_result_recovery>`
1145- Increase `reasoning_effort` one notch only after prompt fixes.
1146
1147You can start from the 5.2 research block and then layer in citation gating and finalization contracts as needed.
1148
1149GPT-5.4 performs especially well when the task requires multi-step evidence gathering, long-context synthesis, and explicit prompt contracts. In practice, the highest-leverage prompt changes are choosing reasoning effort by task shape, defining exact output and citation formats, adding dependency-aware tool rules, and making completion criteria explicit. The model is often strong out of the box, but it is most reliable when prompts clearly specify how to search, how to verify, and what counts as done.
1150
1151### Next steps
1152
1153- Review [Model, API, and feature updates](#model-api-and-feature-updates) for model capabilities, parameters, and API compatibility details.
1154- Read [Prompt engineering](https://developers.openai.com/api/docs/guides/prompt-engineering) for broader prompting strategies that apply across model families.
1155- Read [Compaction](https://developers.openai.com/api/docs/guides/compaction) if you are building long-running GPT-5.4 sessions in the Responses API.
1156
1157
1158## Further reading
1159
1160[GPT-5.3-Codex prompting guide](https://developers.openai.com/cookbook/examples/gpt-5/codex_prompting_guide)
1161
1162[GPT-5.4 blog post](https://openai.com/index/introducing-gpt-5-4/)
1163
1164[GPT-5 frontend guide](https://developers.openai.com/cookbook/examples/gpt-5/gpt-5_frontend)
1165
1166[GPT-5 model family: new features guide](https://developers.openai.com/cookbook/examples/gpt-5/gpt-5_new_params_and_tools)
1167
1168[Cookbook on reasoning models](https://developers.openai.com/cookbook/examples/responses_api/reasoning_items)
1169
1170[Comparison of Responses API vs. Chat Completions](https://developers.openai.com/api/docs/guides/migrate-to-responses)
