Repository Public
1# Using GPT-5.223> 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## Introduction67GPT-5.2 was released as a flagship general-purpose model for both general and agentic tasks. Compared with GPT-5.1, it improved:89- General intelligence10- Instruction following11- Accuracy and token efficiency12- Multimodality—especially vision13- Code generation—especially front-end UI creation14- Tool calling and context management in the API15- Spreadsheet understanding and creation1617Unlike the previous GPT-5.1 model, GPT-5.2 has new features for managing what the model "knows" and "remembers" to improve accuracy.1819This guide covers key features of the GPT-5 model family and how to get the most out of GPT-5.2.2021## Explore coding examples2223Click through a few demo applications generated entirely with a single prompt, without writing any code by hand. Note that these examples were either generated by GPT-5.2 or our previous flagship model, GPT-5.2425## Model, API, and feature updates2627The GPT-5.2 generation includes `gpt-5.2` for complex tasks that require broad world knowledge, `gpt-5.2-chat-latest` for ChatGPT-aligned behavior, and `gpt-5.2-pro` for problems that benefit from more compute.2829For a smaller model, use `gpt-5-mini`.3031To help you pick the model that best fits your use case, consider these tradeoffs:3233| Variant | Best for |34| ------------------------------------------------- | ------------------------------------------------------------------------------------ |35| [`gpt-5.2`](https://developers.openai.com/api/docs/models/gpt-5.2) | Complex reasoning, broad world knowledge, and code-heavy or multi-step agentic tasks |36| [`gpt-5.2-pro`](https://developers.openai.com/api/docs/models/gpt-5.2-pro) | Tough problems that may take longer to solve but require harder thinking |37| [`gpt-5.2-codex`](https://developers.openai.com/api/docs/models/gpt-5.2-codex) | Companies building interactive coding products; full spectrum of coding tasks |38| [`gpt-5-mini`](https://developers.openai.com/api/docs/models/gpt-5-mini) | Cost-optimized reasoning and chat; balances speed, cost, and capability |39| [`gpt-5-nano`](https://developers.openai.com/api/docs/models/gpt-5-nano) | High-throughput tasks, especially focused instruction-following or classification |4041### New features in GPT-5.24243Just like GPT-5.1, the new GPT-5.2 has API features like custom tools, parameters to control verbosity and reasoning, and an allowed tools list. What's new in 5.2 is a new `xhigh` reasoning effort level, concise reasoning summaries, and new context management using _compaction_.4445This guide walks through some of the key features of the GPT-5 model family and how to get the most out of 5.2 in particular.4647For coding tasks, GPT-5.2-Codex is our coding-optimized variant for agentic workflows in Codex or Codex-like environments.4849### Lower reasoning effort5051The `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.5253With GPT-5.2, the lowest setting is `none` to provide lower-latency interactions. This is the default setting in GPT-5.2. If you need more thinking, slowly increase to `medium` and experiment with results.5455With 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.5657Reasoning effort set to none5859```javascript60import OpenAI from "openai";61const openai = new OpenAI();6263const response = await openai.responses.create({64 model: "gpt-5.2",65 input:66 "Think carefully and outline your steps before answering. How much gold would it take to coat the Statue of Liberty in a 1mm layer?",67 reasoning: {68 effort: "none",69 },70});7172console.log(response);73```7475```python76from openai import OpenAI7778client = OpenAI()7980response = client.responses.create(81 model="gpt-5.2",82 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?",83 reasoning={"effort": "none"},84)8586print(response)87```8889```go90package main9192import (93 "context"94 "fmt"9596 "github.com/openai/openai-go/v3"97 "github.com/openai/openai-go/v3/responses"98 "github.com/openai/openai-go/v3/shared"99)100101func main() {102 client := openai.NewClient()103 response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{104 Model: "gpt-5.2",105 Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("Think carefully and outline your steps before answering. How much gold would it take to coat the Statue of Liberty in a 1mm layer?")},106 Reasoning: shared.ReasoningParam{Effort: shared.ReasoningEffortNone},107 })108 if err != nil {109 panic(err)110 }111 fmt.Println(response)112}113```114115```java116import com.openai.client.OpenAIClient;117import com.openai.client.okhttp.OpenAIOkHttpClient;118import com.openai.models.Reasoning;119import com.openai.models.ReasoningEffort;120import com.openai.models.responses.ResponseCreateParams;121122ResponseCreateParams params =123 ResponseCreateParams.builder()124 .model("gpt-5.2")125 .input("Explain the bug and propose a fix.")126 .reasoning(Reasoning.builder().effort(ReasoningEffort.NONE).build())127 .build();128129client.responses().create(params).output().stream()130 .flatMap(item -> item.message().stream())131 .flatMap(message -> message.content().stream())132 .flatMap(content -> content.outputText().stream())133 .forEach(text -> System.out.println(text.text()));134```135136```csharp137using OpenAI.Responses;138#pragma warning disable OPENAI001139140string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;141ResponsesClient client = new(key);142143CreateResponseOptions options = new()144{145 Model = "gpt-5.2",146 ReasoningOptions = new ResponseReasoningOptions147 {148 ReasoningEffortLevel = ResponseReasoningEffortLevel.None,149 },150};151options.InputItems.Add(152 ResponseItem.CreateUserMessageItem(153 "Think carefully and outline your steps before answering. How much gold would it take to coat the Statue of Liberty in a 1mm layer?"154 )155);156157ResponseResult response = await client.CreateResponseAsync(options);158Console.WriteLine(response.GetOutputText());159```160161```ruby162require "openai"163164client = OpenAI::Client.new165response = client.responses.create(166 model: "gpt-5.2",167 reasoning: { effort: :minimal },168 input: "Explain the bug and propose a fix."169)170puts(response.output_text)171```172173```bash174curl --request POST \175 --url https://api.openai.com/v1/responses \176 --header "Authorization: Bearer $OPENAI_API_KEY" \177 --header 'Content-type: application/json' \178 --data '{179 "model": "gpt-5.2",180 "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?",181 "reasoning": {182 "effort": "none"183 }184}'185```186187188### Verbosity189190Verbosity 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:191192- **High verbosity:** Use when you need the model to provide thorough explanations of documents or perform extensive code refactoring.193- **Low verbosity:** Best for situations where you want concise answers or focused code generation, such as SQL queries.194195GPT-5 made this option configurable as one of `high`, `medium`, or `low`. With GPT-5.2, verbosity remains configurable and defaults to `medium`.196197When generating code with GPT-5.2, `medium` and `high` verbosity levels yield longer, more structured code with inline explanations, while `low` verbosity produces shorter, more concise code with minimal commentary.198199Control verbosity200201```javascript202import OpenAI from "openai";203const openai = new OpenAI();204205const response = await openai.responses.create({206 model: "gpt-5.2",207 input:208 "What is the answer to the ultimate question of life, the universe, and everything?",209 text: {210 verbosity: "low",211 },212});213214console.log(response);215```216217```python218from openai import OpenAI219220client = OpenAI()221222response = client.responses.create(223 model="gpt-5.2",224 input="What is the answer to the ultimate question of life, the universe, and everything?",225 text={"verbosity": "low"},226)227228print(response)229```230231```go232package main233234import (235 "context"236 "fmt"237238 "github.com/openai/openai-go/v3"239 "github.com/openai/openai-go/v3/responses"240)241242func main() {243 client := openai.NewClient()244 response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{245 Model: "gpt-5.2",246 Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("What is the answer to the ultimate question of life, the universe, and everything?")},247 Text: responses.ResponseTextConfigParam{Verbosity: responses.ResponseTextConfigVerbosityLow},248 })249 if err != nil {250 panic(err)251 }252 fmt.Println(response)253}254```255256```java257import com.openai.client.OpenAIClient;258import com.openai.client.okhttp.OpenAIOkHttpClient;259import com.openai.models.responses.ResponseCreateParams;260import com.openai.models.responses.ResponseTextConfig;261262ResponseCreateParams params =263 ResponseCreateParams.builder()264 .model("gpt-5.2")265 .input("Explain the bug and propose a fix.")266 .text(ResponseTextConfig.builder().verbosity(ResponseTextConfig.Verbosity.LOW).build())267 .build();268269client.responses().create(params).output().stream()270 .flatMap(item -> item.message().stream())271 .flatMap(message -> message.content().stream())272 .flatMap(content -> content.outputText().stream())273 .forEach(text -> System.out.println(text.text()));274```275276```ruby277require "openai"278279client = OpenAI::Client.new280response = client.responses.create(281 model: "gpt-5.2",282 text: { verbosity: :low },283 input: "Explain the bug and propose a fix."284)285puts(response.output_text)286```287288```bash289curl --request POST \290 --url https://api.openai.com/v1/responses \291 --header "Authorization: Bearer $OPENAI_API_KEY" \292 --header 'Content-type: application/json' \293 --data '{294 "model": "gpt-5.2",295 "input": "What is the answer to the ultimate question of life, the universe, and everything?",296 "text": {297 "verbosity": "low"298 }299}'300```301302303You 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.304305### Using tools with GPT-5.2306307GPT-5.2 has been post-trained on specific tools. See the [tools docs](https://developers.openai.com/api/docs/guides/tools) for more specific guidance.308309#### The apply patch tool310311The `apply_patch` tool lets GPT-5.2 create, update, and delete files in your codebase using structured diffs. Instead of just suggesting edits, the model emits patch operations that your application applies and then reports back on, enabling iterative, multi-step code editing workflows. [Read the docs](https://developers.openai.com/api/docs/guides/tools-apply-patch).312313Under the hood, this implementation uses a freeform function call rather than a JSON format. In testing, the named function decreased `apply_patch` failure rates by 35%.314315#### Shell tool316317Local shell is supported in GPT-5.2. The shell tool allows the model to interact with your local computer through a controlled command-line interface. [Read the docs](https://developers.openai.com/api/docs/guides/tools-shell) to learn more.318319### Custom tools320321When 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.2.322323[Function calling guide324325326327 Learn about custom tools in the function calling guide.](https://developers.openai.com/api/docs/guides/function-calling)328329#### Freeform inputs330331Define 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.332333```json334{335 "type": "custom",336 "name": "code_exec",337 "description": "Executes arbitrary python code"338}339```340341#### Constraining outputs342343GPT-5.2 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.344345This enables precise, constrained tool calls or structured responses and lets you enforce strict syntactic or domain-specific formats directly in GPT-5.2's function calling, improving control and reliability for complex or constrained domains.346347#### Best practices for custom tools348349- **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.350- **Validate outputs on the server side**. Freeform strings are powerful but require safeguards against injection or unsafe commands.351352### Allowed tools353354The `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).355356[Function calling guide357358359360 Learn about the allowed tools option in the function calling guide.](https://developers.openai.com/api/docs/guides/function-calling)361362By 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.2 dynamically invokes or requires specific functions mid-conversation while reducing the risk of unintended tool usage over long contexts.363364| | **Standard Tools** | **Allowed Tools** |365| ---------------- | ----------------------------------------- | ------------------------------------------------------------- |366| Model's universe | All tools listed under **`"tools": […]`** | Only the subset under **`"tools": […]`** in **`tool_choice`** |367| Tool invocation | Model may or may not call any tool | Model restricted to (or required to call) chosen tools |368| Purpose | Declare available capabilities | Constrain which capabilities are actually used |369370```json371{372 "tool_choice": {373 "type": "allowed_tools",374 "mode": "auto",375 "tools": [376 { "type": "function", "name": "get_weather" },377 { "type": "function", "name": "search_docs" }378 ]379 }380}381```382383For a more detailed overview of all of these new features, see the [accompanying cookbook](https://developers.openai.com/cookbook/examples/gpt-5/gpt-5-2_prompting_guide).384385### Preambles386387Preambles are brief, user-visible explanations that GPT-5.2 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.388389By letting GPT-5.2 “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.2 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.390391For more on using preambles, see the [GPT-5 prompting cookbook](https://developers.openai.com/cookbook/examples/gpt-5/gpt-5_prompting_guide#tool-preambles).392393## Migration quickstart394395GPT-5.2 works best with the Responses API, which supports preserving reasoning context between turns. Read below to migrate from your current model or API.396397### Migrating from other models to GPT-5.2398399While the model should be close to a drop-in replacement for GPT-5.1, there are a few key changes to call out. See the [GPT-5.2 prompting guide](https://developers.openai.com/cookbook/examples/gpt-5/gpt-5-2_prompting_guide) for specific updates to make in your prompts.400401Using 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.402403When migrating to GPT-5.2 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.2&optimize=true)—which automatically updates your prompts for GPT-5.2 based on our best practices—and following this model-specific guidance:404405- **`gpt-5.1`**: `gpt-5.2` with default settings is meant to be a drop-in replacement.406- **o3**: `gpt-5.2` 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.407- **`gpt-4.1`**: `gpt-5.2` with `none` reasoning. Start with `none` and tune your prompts; increase if you need better performance.408- **`o4-mini` or `gpt-4.1-mini`**: `gpt-5-mini` with prompt tuning is a great replacement.409- **`gpt-4.1-nano`**: `gpt-5-nano` with prompt tuning is a great replacement.410411### GPT-5.2 parameter compatibility412413The following parameters are **only supported** when using GPT-5.2 with reasoning effort set to `none`:414415- `temperature`416- `top_p`417- `logprobs`418419Requests to GPT-5.2 or GPT-5.1 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.420421To achieve similar results with reasoning effort set higher, or with another GPT-5 family model, try these alternative parameters:422423- **Reasoning depth:** `reasoning: { effort: "none" | "low" | "medium" | "high" | "xhigh" }`424- **Output verbosity:** `text: { verbosity: "low" | "medium" | "high" }`425- **Output length:** `max_output_tokens`426427### Migrating from Chat Completions to Responses API428429The biggest difference, and main reason to migrate from Chat Completions to the Responses API for GPT-5.2, is support for passing chain of thought (CoT) between turns. See a full [comparison of the APIs](https://developers.openai.com/api/docs/guides/migrate-to-responses).430431Passing 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:432433**Reasoning effort**434435436437Responses API438439 Generate response with reasoning effort set to none440441```bash442curl --request POST \443 --url https://api.openai.com/v1/responses \444 --header "Authorization: Bearer $OPENAI_API_KEY" \445 --header "Content-type: application/json" \446 --data '{447 "model": "gpt-5.2",448 "input": "How much gold would it take to coat the Statue of Liberty in a 1mm layer?",449 "reasoning": {450 "effort": "none"451 }452}'453```454455 456457 458459 460Chat Completions461462 Generate response with reasoning effort set to none463464```bash465curl --request POST \466 --url https://api.openai.com/v1/chat/completions \467 --header "Authorization: Bearer $OPENAI_API_KEY" \468 --header "Content-type: application/json" \469 --data '{470 "model": "gpt-5.2",471 "messages": [472 {473 "role": "user",474 "content": "How much gold would it take to coat the Statue of Liberty in a 1mm layer?"475 }476 ],477 "reasoning_effort": "none"478}'479```480481482483**Verbosity**484485486487Responses API488489 Control verbosity490491```bash492curl --request POST \493 --url https://api.openai.com/v1/responses \494 --header "Authorization: Bearer $OPENAI_API_KEY" \495 --header "Content-type: application/json" \496 --data '{497 "model": "gpt-5.2",498 "input": "What is the answer to the ultimate question of life, the universe, and everything?",499 "text": {500 "verbosity": "low"501 }502}'503```504505 506507 508509 510Chat Completions511512 Control verbosity513514```bash515curl --request POST \516 --url https://api.openai.com/v1/chat/completions \517 --header "Authorization: Bearer $OPENAI_API_KEY" \518 --header "Content-type: application/json" \519 --data '{520 "model": "gpt-5.2",521 "messages": [522 {523 "role": "user",524 "content": "What is the answer to the ultimate question of life, the universe, and everything?"525 }526 ],527 "verbosity": "low"528}'529```530531532533**Custom tools**534535536537Responses API538539 Custom tool call540541```bash542curl --request POST \543 --url https://api.openai.com/v1/responses \544 --header "Authorization: Bearer $OPENAI_API_KEY" \545 --header "Content-type: application/json" \546 --data '{547 "model": "gpt-5.2",548 "input": "Use the code_exec tool to calculate the area of a circle with radius equal to the number of r letters in blueberry",549 "tools": [550 {551 "type": "custom",552 "name": "code_exec",553 "description": "Executes arbitrary Python code"554 }555 ]556}'557```558559 560561 562563 564Chat Completions565566 Custom tool call567568```bash569curl --request POST \570 --url https://api.openai.com/v1/chat/completions \571 --header "Authorization: Bearer $OPENAI_API_KEY" \572 --header "Content-type: application/json" \573 --data '{574 "model": "gpt-5.2",575 "messages": [576 {577 "role": "user",578 "content": "Use the code_exec tool to calculate the area of a circle with radius equal to the number of r letters in blueberry"579 }580 ],581 "tools": [582 {583 "type": "custom",584 "custom": {585 "name": "code_exec",586 "description": "Executes arbitrary Python code"587 }588 }589 ]590}'591```592593594595## Prompting best practices596597### 2. Key behavioral differences598599**Compared with previous generation models (e.g. GPT-5 and GPT-5.1), GPT-5.2 delivers:**600601- **More deliberate scaffolding:** Builds clearer plans and intermediate structure by default; benefits from explicit scope and verbosity constraints.602- **Generally lower verbosity:** More concise and task-focused, though still prompt-sensitive and preference needs to be articulated in the prompt.603- **Stronger instruction adherence:** Less drift from user intent; improved formatting and rationale presentation.604- **Tool efficiency trade-offs:** Takes additional tool actions in interactive flows compared with GPT-5.1, can be further optimized via prompting.605- **Conservative grounding bias:** Tends to favor correctness and explicit reasoning; ambiguity handling improves with clarification prompts.606607This guide focuses on prompting GPT-5.2 to maximize its strengths — higher intelligence, accuracy, grounding, and discipline — while mitigating remaining inefficiencies. Existing GPT-5 / GPT-5.1 prompting guidance largely carries over and remains applicable.608609### 3. Prompting patterns610611Adapt following themes into your prompts for better steer on GPT-5.2612613#### 3.1 Controlling verbosity and output shape614615Give **clear and concrete length constraints** especially in enterprise and coding agents.616617Example clamp adjust based on desired verbosity:618619```text620<output_verbosity_spec>621- Default: 3–6 sentences or ≤5 bullets for typical answers.622- For simple “yes/no + short explanation” questions: ≤2 sentences.623- For complex multi-step or multi-file tasks:624 - 1 short overview paragraph625 - then ≤5 bullets tagged: What changed, Where, Risks, Next steps, Open questions.626- Provide clear and structured responses that balance informativeness with conciseness. Break down the information into digestible chunks and use formatting like lists, paragraphs and tables when helpful.627- Avoid long narrative paragraphs; prefer compact bullets and short sections.628- Do not rephrase the user’s request unless it changes semantics.629</output_verbosity_spec>630```631632#### 3.2 Preventing Scope drift (e.g., UX / design in frontend tasks)633634GPT-5.2 is stronger at structured code but may produce more code than the minimal UX specs and design systems. To stay within the scope, explicitly forbid extra features and uncontrolled styling.635636```text637<design_and_scope_constraints>638- Explore any existing design systems and understand it deeply.639- Implement EXACTLY and ONLY what the user requests.640- No extra features, no added components, no UX embellishments.641- Style aligned to the design system at hand.642- Do NOT invent colors, shadows, tokens, animations, or new UI elements, unless requested or necessary to the requirements.643- If any instruction is ambiguous, choose the simplest valid interpretation.644</design_and_scope_constraints>645```646647For design system enforcement, reuse your 5.1 `<design_system_enforcement>` block but add “no extra features” and “tokens-only colors” for extra emphasis.648649#### 3.3 Long-context and recall650651For long-context tasks, the prompt may benefit from **force summarization and re-grounding**. This pattern reduces “lost in the scroll” errors and improves recall over dense contexts.652653```text654<long_context_handling>655- For inputs longer than ~10k tokens (multi-chapter docs, long threads, multiple PDFs):656 - First, produce a short internal outline of the key sections relevant to the user’s request.657 - Re-state the user’s constraints explicitly (e.g., jurisdiction, date range, product, team) before answering.658 - In your answer, anchor claims to sections (“In the ‘Data Retention’ section…”) rather than speaking generically.659- If the answer depends on fine details (dates, thresholds, clauses), quote or paraphrase them.660</long_context_handling>661```662663#### 3.4 Handling ambiguity & hallucination risk664665Configure the prompt for overconfident hallucinations on ambiguous queries (e.g., unclear requirements, missing constraints, or questions that need fresh data but no tools are called).666667Mitigation prompt:668669```text670<uncertainty_and_ambiguity>671- If the question is ambiguous or underspecified, explicitly call this out and:672 - Ask up to 1–3 precise clarifying questions, OR673 - Present 2–3 plausible interpretations with clearly labeled assumptions.674- When external facts may have changed recently (prices, releases, policies) and no tools are available:675 - Answer in general terms and state that details may have changed.676- Never fabricate exact figures, line numbers, or external references when you are uncertain.677- When you are unsure, prefer language like “Based on the provided context…” instead of absolute claims.678</uncertainty_and_ambiguity>679```680681You can also add a short self-check step for high-risk outputs:682683```text684<high_risk_self_check>685Before finalizing an answer in legal, financial, compliance, or safety-sensitive contexts:686- Briefly re-scan your own answer for:687 - Unstated assumptions,688 - Specific numbers or claims not grounded in context,689 - Overly strong language (“always,” “guaranteed,” etc.).690- If you find any, soften or qualify them and explicitly state assumptions.691</high_risk_self_check>692```693694### 4. Compaction (Extending Effective Context)695696For long-running, tool-heavy workflows that exceed the standard context window, GPT-5.2 with Reasoning supports response compaction via the /responses/compact endpoint. Compaction performs a loss-aware compression pass over prior conversation state, returning encrypted, opaque items that preserve task-relevant information while dramatically reducing token footprint. This allows the model to continue reasoning across extended workflows without hitting context limits.697698**When to use compaction**699700- Multi-step agent flows with many tool calls701- Long conversations where earlier turns must be retained702- Iterative reasoning beyond the maximum context window703704**Key properties**705706- Produces opaque, encrypted items (internal logic may evolve)707- Designed for continuation, not inspection708- Compatible with GPT-5.2 and Responses API709- Safe to run repeatedly in long sessions710711**Compact a Response**712713Endpoint714715```text716POST https://api.openai.com/v1/responses/compact717```718719**What it does**720721Runs a compaction pass over a conversation and returns a compacted response object. Pass the compacted output into your next request to continue the workflow with reduced context size.722723**Best practices**724725- Monitor context usage and plan ahead to avoid hitting context window limits726- Compact after major milestones (e.g., tool-heavy phases), not every turn727- Keep prompts functionally identical when resuming to avoid behavior drift728- Treat compacted items as opaque; don’t parse or depend on internals729730For guidance on when and how to compact in production, see the [Conversation State](https://developers.openai.com/api/docs/guides/conversation-state?api-mode=responses) guide and [Compact a Response](https://developers.openai.com/api/reference/resources/responses/methods/compact) page.731732Here is an example:733734```python735from openai import OpenAI736import json737738739client = OpenAI()740741742response = client.responses.create(743 model="gpt-5.2",744 input=[745 {746 "role": "user",747 "content": "write a very long poem about a dog.",748 },749 ],750)751752753output_json = [msg.model_dump() for msg in response.output]754755756# Now compact, passing the original user prompt and the assistant text as inputs757compacted_response = client.responses.compact(758 model="gpt-5.2",759 input=[760 {761 "role": "user",762 "content": "write a very long poem about a dog.",763 },764 output_json[0],765 ],766)767768769print(json.dumps(compacted_response.model_dump(), indent=2))770```771772```java773import com.openai.client.OpenAIClient;774import com.openai.client.okhttp.OpenAIOkHttpClient;775import com.openai.core.JsonValue;776import com.openai.models.responses.EasyInputMessage;777import com.openai.models.responses.ResponseCompactParams;778import com.openai.models.responses.ResponseCreateParams;779import com.openai.models.responses.ResponseInputItem;780import java.util.ArrayList;781782var input = new ArrayList<ResponseInputItem>();783input.add(784 ResponseInputItem.ofEasyInputMessage(785 EasyInputMessage.builder()786 .role(EasyInputMessage.Role.USER)787 .content("Write a very long poem about a dog.")788 .build()));789var response =790 client791 .responses()792 .create(ResponseCreateParams.builder().model("gpt-5.2").inputOfResponse(input).build());793response.output().stream()794 .map(item -> JsonValue.from(item).convert(ResponseInputItem.class))795 .forEach(input::add);796var compacted =797 client798 .responses()799 .compact(800 ResponseCompactParams.builder()801 .model("gpt-5.2")802 .inputOfResponseInputItems(input)803 .build());804System.out.println(compacted.output());805```806807```ruby808require "openai"809810client = OpenAI::Client.new811response = client.responses.create(812 model: "gpt-5.2",813 input: [814 {815 role: :user,816 content: "Write a very long poem about a dog."817 }818 ]819)820compaction = client.responses.compact(821 model: "gpt-5.2",822 input: [823 {824 role: :user,825 content: "Write a very long poem about a dog."826 },827 *response.output828 ]829)830831puts(compaction.output)832```833834835### 5. Agentic steerability & user updates836837GPT-5.2 is strong on agentic scaffolding and multi-step execution when prompted well. You can reuse your GPT-5.1 `<user_updates_spec>` and `<solution_persistence>` blocks.838839Two key tweaks could be added to further push the performance of GPT-5.2:840841- Clamp verbosity of updates (shorter, more focused).842- Make scope discipline explicit (don’t expand problem surface area).843844Example updated spec:845846```text847<user_updates_spec>848- Send brief updates (1–2 sentences) only when:849 - You start a new major phase of work, or850 - You discover something that changes the plan.851- Avoid narrating routine tool calls (“reading file…”, “running tests…”).852- Each update must include at least one concrete outcome (“Found X”, “Confirmed Y”, “Updated Z”).853- Do not expand the task beyond what the user asked; if you notice new work, call it out as optional.854</user_updates_spec>855```856857### 6. Tool-calling and parallelism858859GPT-5.2 improves on 5.1 in tool reliability and scaffolding, especially in MCP/Atlas-style environments.860Best practices as applicable to GPT-5 / 5.1:861862- Describe tools crisply: 1–2 sentences for what they do and when to use them.863- Encourage parallelism explicitly for scanning codebases, vector stores, or multi-entity operations.864- Require verification steps for high-impact operations (orders, billing, infra changes).865866Example tool usage section:867868```text869<tool_usage_rules>870- Prefer tools over internal knowledge whenever:871 - You need fresh or user-specific data (tickets, orders, configs, logs).872 - You reference specific IDs, URLs, or document titles.873- Parallelize independent reads (read_file, fetch_record, search_docs) when possible to reduce latency.874- After any write/update tool call, briefly restate:875 - What changed,876 - Where (ID or path),877 - Any follow-up validation performed.878</tool_usage_rules>879```880881### 7. Structured extraction, PDF, and Office workflows882883This is an area where GPT-5.2 clearly shows strong improvements. To get the most out of it:884885- Always provide a schema or JSON shape for the output. You can use structured outputs for strict schema adherence.886- Distinguish between required and optional fields.887- Ask for “extraction completeness” and handle missing fields explicitly.888889Example:890891```text892<extraction_spec>893You will extract structured data from tables/PDFs/emails into JSON.894895- Always follow this schema exactly (no extra fields):896 {897 "party_name": string,898 "jurisdiction": string | null,899 "effective_date": string | null,900 "termination_clause_summary": string | null901 }902- If a field is not present in the source, set it to null rather than guessing.903- Before returning, quickly re-scan the source for any missed fields and correct omissions.904</extraction_spec>905```906907For multi-table/multi-file extraction, add guidance to:908909- Serialize per-document results separately.910- Include a stable ID (filename, contract title, page range).911912### 8. Prompt Migration Guide to GPT-5.2913914This section helps you migrate prompts and model configs to GPT-5.2 while keeping behavior stable and cost/latency predictable. GPT-5-class models support a reasoning_effort knob (e.g., none|minimal|low|medium|high|xhigh) that trades off speed/cost vs. deeper reasoning.915916Migration mapping917Use the following default mappings when updating to GPT-5.2918919| Current model | Target model | Target reasoning_effort | Notes |920| ------------- | ------------ | -------------------------------- | ----------------------------------------------------------------------------------------------------- |921| GPT-4o | GPT-5.2 | none | Treat 4o/4.1 migrations as “fast/low-deliberation” by default; only increase effort if evals regress. |922| GPT-4.1 | GPT-5.2 | none | Same mapping as GPT-4o to preserve snappy behavior. |923| GPT-5 | GPT-5.2 | same value except minimal → none | Preserve none/low/medium/high to keep latency/quality profile consistent. |924| GPT-5.1 | GPT-5.2 | same value | Preserve existing effort selection; adjust only after running evals. |925926\*Note that default reasoning level for GPT-5 is medium, and for GPT-5.1 and GPT-5.2 is none.927928We introduced the [Prompt Optimizer](https://platform.openai.com/chat/edit?optimize=true) in the Playground to help users quickly improve existing prompts and migrate them across GPT-5 and other OpenAI models. General steps to migrate to a new model are as follows:929930- Step 1: Switch models, don’t change prompts yet. Keep the prompt functionally identical so you’re testing the model change—not prompt edits. Make one change at a time.931- Step 2: Pin reasoning_effort. Explicitly set GPT-5.2 reasoning_effort to match the prior model’s latency/depth profile (avoid provider-default “thinking” traps that skew cost/verbosity/structure).932- Step 3: Run Evals for a baseline. After model + effort are aligned, run your eval suite. If results look good (often better at med/high), you’re ready to ship.933- Step 4: If regressions, tune the prompt. Use Prompt Optimizer + targeted constraints (verbosity/format/schema, scope discipline) to restore parity or improve.934- Step 5: Re-run Evals after each small change. Iterate by either bumping reasoning_effort one notch or making incremental prompt tweaks—then re-measure.935936### 9. Web search and research937938GPT-5.2 is more steerable and capable at synthesizing information across many sources.939940Best practices to follow:941942- Specify the research bar up front: Tell the model how you want to perform search. Whether to follow second-order leads, resolve contradictions and include citations. Explicitly state how far to go, for instance: that additional research should continue until marginal value drops.943944- Constrain ambiguity by instruction, not questions: Instruct the model to cover all plausible intents comprehensively and not ask clarifying questions. Require breadth and depth when uncertainty exists.945946- Dictate output shape and tone: Set expectations for structure (Markdown, headers, tables for comparisons), clarity (define acronyms, concrete examples) and voice (conversational, persona-adaptive, non-sycophantic)947948```text949<web_search_rules>950- Act as an expert research assistant; default to comprehensive, well-structured answers.951- Prefer web research over assumptions whenever facts may be uncertain or incomplete; include citations for all web-derived information.952- Research all parts of the query, resolve contradictions, and follow important second-order implications until further research is unlikely to change the answer.953- Do not ask clarifying questions; instead cover all plausible user intents with both breadth and depth.954- Write clearly and directly using Markdown (headers, bullets, tables when helpful); define acronyms, use concrete examples, and keep a natural, conversational tone.955</web_search_rules>956```957958### 10. Conclusion959960GPT-5.2 represents a meaningful step forward for teams building production-grade agents that prioritize accuracy, reliability, and disciplined execution. It delivers stronger instruction following, cleaner output, and more consistent behavior across complex, tool-heavy workflows. Most existing prompts migrate cleanly, especially when reasoning effort, verbosity, and scope constraints are preserved during the initial transition. Teams should rely on evals to validate behavior before making prompt changes, adjusting reasoning effort or constraints only when regressions appear. With explicit prompting and measured iteration, GPT-5.2 can unlock higher quality outcomes while maintaining predictable cost and latency profiles.961962### Appendix963964#### Example prompt for a web research agent:965966```text967You are a helpful, warm web research agent. Your job is to deeply and thoroughly research the web and provide long, detailed, comprehensive, well written, and well structured answers grounded in reliable sources. Your answers should be engaging, informative, concrete, and approachable. You MUST adhere perfectly to the guidelines below.968############################################969CORE MISSION970############################################971Answer the user’s question fully and helpfully, with enough evidence that a skeptical reader can trust it.972Never invent facts. If you can’t verify something, say so clearly and explain what you did find.973Default to being detailed and useful rather than short, unless the user explicitly asks for brevity.974Go one step further: after answering the direct question, add high-value adjacent material that supports the user’s underlying goal without drifting off-topic. Don’t just state conclusions—add an explanatory layer. When a claim matters, explain the underlying mechanism/causal chain (what causes it, what it affects, what usually gets misunderstood) in plain language.975############################################976PERSONA977############################################978You are the world’s greatest research assistant.979Engage warmly, enthusiastically, and honestly, while avoiding any ungrounded or sycophantic flattery.980Adopt whatever persona the user asks you to take.981Default tone: natural, conversational, and playful rather than formal or robotic, unless the subject matter requires seriousness.982Match the vibe of the request: for casual conversation lean supportive; for work/task-focused requests lean straightforward and helpful.983############################################984FACTUALITY AND ACCURACY (NON-NEGOTIABLE)985############################################986You MUST browse the web and include citations for all non-creative queries, unless:987The user explicitly tells you not to browse, OR988The request is purely creative and you are absolutely sure web research is unnecessary (example: “write a poem about flowers”).989If you are on the fence about whether browsing would help, you MUST browse.990You MUST browse for:991“Latest/current/today” or time-sensitive topics (news, politics, sports, prices, laws, schedules, product specs, rankings/records, office-holders).992Up-to-date or niche topics where details may have changed recently (weather, exchange rates, economic indicators, standards/regulations, software libraries that could be updated, scientific developments, cultural trends, recent media/entertainment developments).993Travel and trip planning (destinations, venues, logistics, hours, closures, booking constraints, safety changes).994Recommendations of any kind (because what exists, what’s good, what’s open, and what’s safe can change).995Generic/high-level topics (example: “what is an AI agent?” or “openai”) to ensure accuracy and current framing.996Navigational queries (finding a resource, site, official page, doc, definition, source-of-truth reference, etc.).997Any query containing a term you’re unsure about, suspect is a typo, or has ambiguous meaning.998For news queries, prioritize more recent events, and explicitly compare:999The publish date of each source, AND1000The date the event happened (if different).1001############################################1002CITATIONS (REQUIRED)1003############################################1004When you use web info, you MUST include citations.1005Place citations after each paragraph (or after a tight block of closely related sentences) that contains non-obvious web-derived claims.1006Do not invent citations. If the user asked you not to browse, do not cite web sources.1007Use multiple sources for key claims when possible, prioritizing primary sources and high-quality outlets.1008############################################1009HOW YOU RESEARCH1010############################################1011You must conduct deep research in order to provide a comprehensive and off-the-charts informative answer. Provide as much color around your answer as possible, and aim to surprise and delight the user with your effort, attention to detail, and nonobvious insights.1012Start with multiple targeted searches. Use parallel searches when helpful. Do not ever rely on a single query.1013Deeply and thoroughly research until you have sufficient information to give an accurate, comprehensive answer with strong supporting detail.1014Begin broad enough to capture the main answer and the most likely interpretations.1015Add targeted follow-up searches to fill gaps, resolve disagreements, or confirm the most important claims.1016If the topic is time-sensitive, explicitly check for recent updates.1017If the query implies comparisons, options, or recommendations, gather enough coverage to make the tradeoffs clear (not just a single source).1018Keep iterating until additional searching is unlikely to materially change the answer or add meaningful missing detail.1019If evidence is thin, keep searching rather than guessing.1020If a source is a PDF and details depend on figures/tables, use PDF viewing/screenshot rather than guessing.1021Only stop when all are true:1022You answered the user’s actual question and every subpart.1023You found concrete examples and high-value adjacent material.1024You found sufficient sources for core claims10251026############################################1027WRITING GUIDELINES1028############################################1029Be direct: Start answering immediately.1030Be comprehensive: Answer every part of the user’s query. Your answer should be very detailed and long unless the user request is extremely simplistic. If your response is long, include a short summary at the top.1031Use simple language: full sentences, short words, concrete verbs, active voice, one main idea per sentence.1032Avoid jargon or esoteric language unless the conversation unambiguously indicates the user is an expert.1033Use readable formatting:1034Use Markdown unless the user specifies otherwise.1035Use plain-text section labels and bullets for scannability.1036Use tables when the reader’s job is to compare or choose among options (when multiple items share attributes and a grid makes differences pop faster than prose).1037Do NOT add potential follow-up questions or clarifying questions at the beginning or end of the response unless the user has explicitly asked for them.10381039############################################1040REQUIRED “VALUE-ADD” BEHAVIOR (DETAIL/RICHNESS)1041############################################1042Concrete examples: You MUST provide concrete examples whenever helpful (named entities, mechanisms, case examples, specific numbers/dates, “how it works” detail). For queries that ask you to explain a topic, you can also occasionally include an analogy if it helps.1043Do not be overly brief by default: even for straightforward questions, your response should include relevant, well-sourced material that makes the answer more useful (context, background, implications, notable details, comparisons, practical takeaways).1044In general, provide additional well-researched material whenever it clearly helps the user’s goal.10451046Before you finalize, do a quick completeness pass:10471. Did I answer every subpart10482. Did each major section include explanation + at least one concrete detail/example when possible10493. Did I include tradeoffs/decision criteria where relevant105010511052############################################1053HANDLING AMBIGUITY (WITHOUT ASKING QUESTIONS)1054############################################1055Never ask clarifying or follow-up questions unless the user explicitly asks you to.1056If the query is ambiguous, state your best-guess interpretation plainly, then comprehensively cover the most likely intent. If there are multiple most likely intents, then comprehensively cover each one (in this case you will end up needing to provide a full, long answer for each intent interpretation), rather than asking questions.1057############################################1058IF YOU CANNOT FULLY COMPLY WITH A REQUEST1059############################################1060Do not lead with a blunt refusal if you can safely provide something helpful immediately.1061First deliver what you can (safe partial answers, verified material, or a closely related helpful alternative), then clearly state any limitations (policy limits, missing/behind-paywall data, unverifiable claims).1062If something cannot be verified, say so plainly, explain what you did verify, what remains unknown, and the best next step to resolve it (without asking the user a question).1063```10641065## Further reading10661067[GPT-5.2-Codex prompting guide](https://developers.openai.com/cookbook/examples/gpt-5/codex_prompting_guide)10681069[GPT-5.2 blog post](https://openai.com/index/introducing-gpt-5-2/)10701071[GPT-5 frontend guide](https://developers.openai.com/cookbook/examples/gpt-5/gpt-5_frontend)10721073[GPT-5 model family: new features guide](https://developers.openai.com/cookbook/examples/gpt-5/gpt-5_new_params_and_tools)10741075[Cookbook on reasoning models](https://developers.openai.com/cookbook/examples/responses_api/reasoning_items)10761077[Comparison of Responses API vs. Chat Completions](https://developers.openai.com/api/docs/guides/migrate-to-responses)