Repository Public
1# Upgrading to GPT-5.423> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.45# Upgrading to GPT-5.467Use this guide when the user explicitly asks to upgrade an existing integration to GPT-5.4. Pair it with current OpenAI docs lookups. The default target string is `gpt-5.4`.89## Upgrade posture1011Upgrade with the narrowest safe change set:1213- replace the model string first14- update only the prompts that are directly tied to that model usage15- prefer prompt-only upgrades when possible16- if the upgrade would require API-surface changes, parameter rewrites, tool rewiring, or broader code edits, mark it as blocked instead of stretching the scope1718## Upgrade workflow19201. Inventory current model usage.21 - Search for model strings, client calls, and prompt-bearing files.22 - Include inline prompts, prompt templates, YAML or JSON configs, Markdown docs, and saved prompts when they are clearly tied to a model usage site.232. Pair each model usage with its prompt surface.24 - Prefer the closest prompt surface first: inline system or developer text, then adjacent prompt files, then shared templates.25 - If you cannot confidently tie a prompt to the model usage, say so instead of guessing.263. Classify the source model family.27 - Common buckets: `gpt-4o` or `gpt-4.1`, `o1` or `o3` or `o4-mini`, early `gpt-5`, later `gpt-5.x`, or mixed and unclear.284. Decide the upgrade class.29 - `model string only`30 - `model string + light prompt rewrite`31 - `blocked without code changes`325. Run the no-code compatibility gate.33 - Check whether the current integration can accept `gpt-5.4` without API-surface changes or implementation changes.34 - For long-running Responses or tool-heavy agents, check whether `phase` is already preserved or round-tripped when the host replays assistant items or uses preambles.35 - If compatibility depends on code changes, return `blocked`.36 - If compatibility is unclear, return `unknown` rather than improvising.376. Recommend the upgrade.38 - Default replacement string: `gpt-5.4`39 - Keep the intervention small and behavior-preserving.407. Deliver a structured recommendation.41 - `Current model usage`42 - `Recommended model-string updates`43 - `Starting reasoning recommendation`44 - `Prompt updates`45 - `Phase assessment` when the flow is long-running, replayed, or tool-heavy46 - `No-code compatibility check`47 - `Validation plan`48 - `Launch-day refresh items`4950Output rule:5152- Always emit a starting `reasoning_effort_recommendation` for each usage site.53- If the repo exposes the current reasoning setting, preserve it first unless the source guide says otherwise.54- If the repo does not expose the current setting, use the source-family starting mapping instead of returning `null`.5556## Upgrade outcomes5758### `model string only`5960Choose this when:6162- the existing prompts are already short, explicit, and task-bounded63- the workflow is not strongly research-heavy, tool-heavy, multi-agent, batch or completeness-sensitive, or long-horizon64- there are no obvious compatibility blockers6566Default action:6768- replace the model string with `gpt-5.4`69- keep prompts unchanged70- validate behavior with existing evals or spot checks7172### `model string + light prompt rewrite`7374Choose this when:7576- the old prompt was compensating for weaker instruction following77- the workflow needs more persistence than the default tool-use behavior will likely provide78- the task needs stronger completeness, citation discipline, or verification79- the upgraded model becomes too verbose or under-complete unless instructed otherwise80- the workflow is research-heavy and needs stronger handling of sparse or empty retrieval results81- the workflow is coding-oriented, tool-heavy, or multi-agent, but the existing API surface and tool definitions can remain unchanged8283Default action:8485- replace the model string with `gpt-5.4`86- add one or two targeted prompt blocks87- read [Prompting best practices for GPT-5.4](https://developers.openai.com/api/docs/guides/latest-model?model=gpt-5.4#prompting-best-practices) to choose the smallest prompt changes that recover the old behavior88- avoid broad prompt cleanup unrelated to the upgrade89- for research workflows, default to `research_mode` + `citation_rules` + `empty_result_handling`; add `tool_persistence_rules` when the host already uses retrieval tools90- for dependency-aware or tool-heavy workflows, default to `tool_persistence_rules` + `dependency_checks` + `verification_loop`; add `parallel_tool_calling` only when retrieval steps are truly independent91- for coding or terminal workflows, default to `terminal_tool_hygiene` + `verification_loop`92- for multi-agent support or triage workflows, default to at least one of `tool_persistence_rules`, `completeness_contract`, or `verification_loop`93- for long-running Responses agents with preambles or multiple assistant messages, explicitly review whether `phase` is already handled; if adding or preserving `phase` would require code edits, mark the path as `blocked`94- do not classify a coding or tool-using Responses workflow as `blocked` just because the visible snippet is minimal; prefer `model string + light prompt rewrite` unless the repo clearly shows that a safe GPT-5.4 path would require host-side code changes9596### `blocked`9798Choose this when:99100- the upgrade appears to require API-surface changes101- the upgrade appears to require parameter rewrites or reasoning-setting changes that are not exposed outside implementation code102- the upgrade would require changing tool definitions, tool handler wiring, or schema contracts103- you cannot confidently identify the prompt surface tied to the model usage104105Default action:106107- do not improvise a broader upgrade108- report the blocker and explain that the fix is out of scope for this guide109110## No-code compatibility checklist111112Before recommending a no-code upgrade, check:1131141. Can the current host accept the `gpt-5.4` model string without changing client code or API surface?1152. Are the related prompts identifiable and editable?1163. Does the host depend on behavior that likely needs API-surface changes, parameter rewrites, or tool rewiring?1174. Would the likely fix be prompt-only, or would it need implementation changes?1185. Is the prompt surface close enough to the model usage that you can make a targeted change instead of a broad cleanup?1196. For long-running Responses or tool-heavy agents, is `phase` already preserved if the host relies on preambles, replayed assistant items, or multiple assistant messages?120121If item 1 is no, items 3 through 4 point to implementation work, or item 6 is no and the fix needs code changes, return `blocked`.122123If item 2 is no, return `unknown` unless the user can point to the prompt location.124125Important:126127- Existing use of tools, agents, or multiple usage sites is not by itself a blocker.128- If the current host can keep the same API surface and the same tool definitions, prefer `model string + light prompt rewrite` over `blocked`.129- Reserve `blocked` for cases that truly require implementation changes, not cases that only need stronger prompt steering.130131## Scope boundaries132133This guide may:134135- update or recommend updated model strings136- update or recommend updated prompts137- inspect code and prompt files to understand where those changes belong138- inspect whether existing Responses flows already preserve `phase`139- flag compatibility blockers140141This guide may not:142143- move Chat Completions code to Responses144- move Responses code to another API surface145- rewrite parameter shapes146- change tool definitions or tool-call handling147- change structured-output wiring148- add or retrofit `phase` handling in implementation code149- edit business logic, orchestration logic, or SDK usage beyond a literal model-string replacement150151If a safe GPT-5.4 upgrade requires any of those changes, mark the path as blocked and out of scope.152153## Validation plan154155- Validate each upgraded usage site with existing evals or realistic spot checks.156- Check whether the upgraded model still matches expected latency, output shape, and quality.157- If prompt edits were added, confirm each block is doing real work instead of adding noise.158- If the workflow has downstream impact, add a lightweight verification pass before finalization.159160## Launch-day refresh items161162When final GPT-5.4 guidance changes:1631641. Replace release-candidate assumptions with final GPT-5.4 guidance where appropriate.1652. Re-check whether the default target string should stay `gpt-5.4` for all source families.1663. Re-check any prompt-block recommendations whose semantics may have changed.1674. Re-check research, citation, and compatibility guidance against the final model behavior.1685. Re-run the same upgrade scenarios and confirm the blocked-versus-viable boundaries still hold.