Repository Public
1# Upgrading to GPT-5.523> 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.567Use this guide when the user explicitly asks to upgrade an existing integration to GPT-5.5. Pair it with current OpenAI docs lookups. The default target string is `gpt-5.5`.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- do not automatically upgrade older or ambiguous model usages that may be intentionally pinned, such as historical docs, examples, tests, eval baselines, comparison code, or low-cost fallback/routing paths. Unless the user explicitly asks to upgrade all model usage, leave those sites unchanged and list them as confirmation-needed16- prefer prompt-only upgrades when possible17- if the upgrade would require API-surface changes, parameter rewrites, tool rewiring, provider migration, or broader code edits, mark it as blocked instead of stretching the scope1819## Upgrade workflow20211. Inventory current model usage.22 - Search for model strings, client calls, and prompt-bearing files.23 - Include inline prompts, prompt templates, YAML or JSON configs, Markdown docs, and saved prompts when they are clearly tied to a model usage site.242. Pair each model usage with its prompt surface.25 - Prefer the closest prompt surface first: inline system or developer text, then adjacent prompt files, then shared templates.26 - If you cannot confidently tie a prompt to the model usage, say so instead of guessing.273. Classify the source model family.28 - Common buckets: GPT-5.4, GPT-5.3-Codex or GPT-5.2-Codex, earlier GPT-5.x, GPT-4o or GPT-4.1, reasoning models such as o1 or o3 or o4-mini, third-party model, or mixed and unclear.294. Decide the upgrade class.30 - `model string only`31 - `model string + light prompt rewrite`32 - `blocked without code changes`335. Run the compatibility gate.34 - Check whether the current integration can accept `gpt-5.5` without API-surface changes or implementation changes.35 - Check whether structured outputs, tool schemas, function names, and downstream parsers can remain unchanged.36 - 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.37 - If compatibility depends on code changes, return `blocked`.38 - If compatibility is unclear, return `unknown` rather than improvising.396. Apply the upgrade when it is in scope.40 - Default replacement string: `gpt-5.5`.41 - Keep the intervention small and behavior-preserving.42 - Start from the current reasoning effort when it is visible unless there is a measured reason to change it.43 - For in-scope changes, update the model string and directly related prompts.44 - For blocked or unknown changes, do not edit; report the blocker or uncertainty.457. Summarize the result.46 - `Current model usage`47 - `Model-string updates`48 - `Reasoning-effort handling`49 - `Prompt updates`50 - `Structured output and formatting assessment`51 - `Tool-use assessment` when the flow uses tools, retrieval, or terminal actions52 - `Phase assessment` when the flow is long-running, replayed, or tool-heavy53 - `Compatibility check`54 - `Validation performed`5556Output rule:5758- For each usage site, state the starting reasoning-effort recommendation.59- If the repo exposes the current reasoning setting, recommend preserving it first unless current OpenAI docs say otherwise.60- If the repo does not expose the current setting, recommend not adding one unless current OpenAI docs require it.6162## Upgrade outcomes6364### `model string only`6566Choose this when:6768- the source model is GPT-5.469- the existing prompts are already short, explicit, and task-bounded70- the workflow does not rely on strict output formats, tool-call behavior, batch completeness, or long-horizon execution that should be validated after the upgrade71- there are no obvious compatibility blockers7273Default action:7475- replace the model string with `gpt-5.5`76- preserve the current reasoning effort77- keep prompts unchanged78- validate behavior with existing tests, realistic spot checks, or an existing eval suite when one is already available7980### `model string + light prompt rewrite`8182Choose this when:8384- the task needs stronger completeness, citation discipline, verification, or dependency handling85- the upgraded model becomes too verbose, too dense, or hard to scan unless formatting is constrained86- the workflow has strict output shape requirements and lacks an explicit format contract, schema, or parser validation87- the workflow is research-heavy and needs stronger handling of sparse or empty retrieval results88- the workflow is coding-oriented, terminal-based, tool-heavy, or multi-agent, but the existing API surface and tool definitions can remain unchanged8990Default action:9192- replace the model string with `gpt-5.5`93- preserve the current reasoning effort for the first pass94- make only the smallest prompt edits needed for the observed workflow risk95- read the [GPT-5.5 prompting best practices](https://developers.openai.com/api/docs/guides/latest-model?model=gpt-5.5#prompting-best-practices) to choose the smallest prompt changes that recover or improve behavior96- avoid broad prompt cleanup unrelated to the upgrade97- for research workflows, add citation rules, retrieval budgets, missing-evidence behavior, and validation guidance from the prompting guide98- for dependency-aware or tool-heavy workflows, add prerequisite checks, missing-context handling, explicit tool budgets, stop conditions, and validation guidance99- for coding or terminal workflows, add repo-specific constraints, acceptance criteria, and concrete validation commands100- for multi-agent support or triage workflows, add task ownership, handoff, completeness, and stopping criteria101- 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`102- 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.5 path would require host-side code changes103104### `blocked`105106Choose this when:107108- the upgrade appears to require API-surface changes109- the upgrade appears to require parameter rewrites or reasoning-setting changes that are not exposed outside implementation code110- the upgrade would require changing tool definitions, tool handler wiring, or schema contracts111- the user is asking for a tooling, IDE, plugin, shell, or environment migration rather than a model and prompt migration112- the integration depends on provider-specific APIs that do not map to the current OpenAI API surface without implementation work113- you cannot confidently identify the prompt surface tied to the model usage114115Default action:116117- do not improvise a broader upgrade118- report the blocker and explain that the fix is out of scope for this guide119- if useful, describe the smallest follow-up implementation task that would unblock the migration120121## Compatibility checklist122123Before applying or recommending a model-and-prompt-only upgrade, check:1241251. Can the current host accept the `gpt-5.5` model string without changing client code or API surface?1262. Are the related prompts identifiable and editable?1273. Does the host depend on behavior that likely needs API-surface changes, parameter rewrites, provider migration, or tool rewiring?1284. Would the likely fix be prompt-only, or would it need implementation changes?1295. Is the prompt surface close enough to the model usage that you can make a targeted change instead of a broad cleanup?1306. Do strict structured outputs, schemas, or downstream parsers still have an explicit contract?1317. 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?1328. Are latency, token, or price assumptions validated by tests, realistic spot checks, or an existing eval suite rather than inferred from general model positioning?133134If item 1 is no, items 3 through 4 point to implementation work, or item 7 is no and the fix needs code changes, return `blocked`.135136If item 2 is no, return `unknown` unless the user can point to the prompt location.137138Important:139140- Existing use of tools, agents, or multiple usage sites is not by itself a blocker.141- If the current host can keep the same API surface and the same tool definitions, prefer `model string + light prompt rewrite` over `blocked`.142- Reserve `blocked` for cases that truly require implementation changes, not cases that only need stronger prompt steering.143- Do not claim token savings without task-level validation.144145## Scope boundaries146147This guide may:148149- update or recommend updated model strings150- update or recommend updated prompts151- inspect code and prompt files to understand where those changes belong152- inspect whether existing Responses flows already preserve `phase`153- flag compatibility blockers154- propose validation with existing tests, realistic spot checks, or existing eval suites155156This guide may not:157158- move Chat Completions code to Responses159- move Responses code to another API surface160- migrate SDKs, APIs, IDE configuration, shell hooks, plugins, or provider-specific tooling161- rewrite parameter shapes162- change tool definitions or tool-call handling163- change structured-output wiring164- add or retrofit `phase` handling in implementation code165- edit business logic, orchestration logic, SDK usage, IDE configuration, shell hooks, or plugin integration behavior except for model-string replacements and directly related prompt edits166167If a safe GPT-5.5 upgrade requires any of those changes, mark the path as blocked and out of scope.168169## Validation plan170171- Validate each upgraded usage site with existing tests, realistic spot checks, or an existing eval suite when one is already available.172- Compare against the current GPT-5.4 baseline when available.173- Check task success, retry count, tool-call count, total tokens, latency, output shape, and user-visible quality.174- For specialized workflows, validate the contract that matters most instead of judging only general output quality.175- If prompt edits were added, confirm each block is doing real work instead of adding noise.176- If the workflow has downstream impact, add a lightweight verification pass before finalization.