Documentation 2026-09-16 20:58 UTC to 2026-09-17 10:04 UTC

1# Using GPT-4.1

2 

3> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.

4 

5## Introduction

6 

7The GPT-4.1 family of models represents a significant step forward from GPT-4o in capabilities across coding, instruction following, and long context. In this prompting guide, we collate a series of important prompting tips derived from extensive internal testing to help developers fully leverage the improved abilities of this new model family.

8 

9Many typical best practices still apply to GPT-4.1, such as providing context examples, making instructions as specific and clear as possible, and inducing planning via prompting to maximize model intelligence. However, we expect that getting the most out of this model will require some prompt migration. GPT-4.1 is trained to follow instructions more closely and more literally than its predecessors, which tended to more liberally infer intent from user and system prompts. This also means, however, that GPT-4.1 is highly steerable and responsive to well-specified prompts - if model behavior is different from what you expect, a single sentence firmly and unequivocally clarifying your desired behavior is almost always sufficient to steer the model on course.

10 

11Please read on for prompt examples you can use as a reference, and remember that while this guidance is widely applicable, no advice is one-size-fits-all. AI engineering is inherently an empirical discipline, and large language models are inherently nondeterministic; in addition to following this guide, we advise building informative evals and iterating often to ensure your prompt engineering changes are yielding benefits for your use case.

12 

13## What's new

14 

15- Closer and more literal instruction following than previous GPT models

16- Stronger coding and long-context behavior

17- Better API-native tool use when schemas are passed through the `tools` field

18- Prompt migration guidance for agentic workflows and diff generation

19 

20## Migration quickstart

21 

22- Update the model slug to `gpt-4.1`.

23- Use either the Responses API or Chat Completions API, depending on your integration.

24- Remove reasoning-specific parameters; GPT-4.1 is a non-reasoning model.

25- Pass tool schemas through the API `tools` field instead of injecting tool definitions into the prompt.

26- Review prompts for literal instruction following, add explicit persistence and tool-use rules where needed, and validate changes with evals.

27 

28## Model, API, and feature updates

29 

30- The GPT-4.1 family includes `gpt-4.1`, `gpt-4.1-mini`, and `gpt-4.1-nano`.

31- GPT-4.1 has a 1M-token context window and low latency without a reasoning step.

32- The family supports the Responses API and Chat Completions API.

33- GPT-4.1 and GPT-4.1 mini support supervised fine-tuning.

34- Supported tools include function calling, web search, file search, image generation, code interpreter, and remote MCP.

35 

36 

37## Prompting best practices

38 

39### 1. Agentic Workflows

40 

41GPT-4.1 is a great place to build agentic workflows. In model training we emphasized providing a diverse range of agentic problem-solving trajectories, and our agentic harness for the model achieves state-of-the-art performance for non-reasoning models on SWE-bench Verified, solving 55% of problems.

42 

43### System Prompt Reminders

44 

45In order to fully utilize the agentic capabilities of GPT-4.1, we recommend including three key types of reminders in all agent prompts. The following prompts are optimized specifically for the agentic coding workflow, but can be easily modified for general agentic use cases.

46 

471. Persistence: this ensures the model understands it is entering a multi-message turn, and prevents it from prematurely yielding control back to the user. Our example is the following:

48 

49```text

50You are an agent - please keep going until the user’s query is completely resolved, before ending your turn and yielding back to the user. Only terminate your turn when you are sure that the problem is solved.

51```

52 

532. Tool-calling: this encourages the model to make full use of its tools, and reduces its likelihood of hallucinating or guessing an answer. Our example is the following:

54 

55```text

56If you are not sure about file content or codebase structure pertaining to the user’s request, use your tools to read files and gather the relevant information: do NOT guess or make up an answer.

57```

58 

593. Planning \[optional\]: if desired, this ensures the model explicitly plans and reflects upon each tool call in text, instead of completing the task by chaining together a series of only tool calls. Our example is the following:

60 

61```text

62You MUST plan extensively before each function call, and reflect extensively on the outcomes of the previous function calls. DO NOT do this entire process by making function calls only, as this can impair your ability to solve the problem and think insightfully.

63```

64 

65GPT-4.1 is trained to respond very closely to both user instructions and system prompts in the agentic setting. The model adhered closely to these three simple instructions and increased our internal SWE-bench Verified score by close to 20% \- so we highly encourage starting any agent prompt with clear reminders covering the three categories listed above. As a whole, we find that these three instructions transform the model from a chatbot-like state into a much more “eager” agent, driving the interaction forward autonomously and independently.

66 

67### Tool Calls

68 

69Compared to previous models, GPT-4.1 has undergone more training on effectively utilizing tools passed as arguments in an OpenAI API request. We encourage developers to exclusively use the tools field to pass tools, rather than manually injecting tool descriptions into your prompt and writing a separate parser for tool calls, as some have reported doing in the past. This is the best way to minimize errors and ensure the model remains in distribution during tool-calling trajectories \- in our own experiments, we observed a 2% increase in SWE-bench Verified pass rate when using API-parsed tool descriptions versus manually injecting the schemas into the system prompt.

70 

71Developers should name tools clearly to indicate their purpose and add a clear, detailed description in the "description" field of the tool. Similarly, for each tool param, lean on good naming and descriptions to ensure appropriate usage. If your tool is particularly complicated and you'd like to provide examples of tool usage, we recommend that you create an `# Examples` section in your system prompt and place the examples there, rather than adding them into the "description" field, which should remain thorough but relatively concise. Providing examples can be helpful to indicate when to use tools, whether to include user text alongside tool calls, and what parameters are appropriate for different inputs. Remember that you can use “Generate Anything” in the [Prompt Playground](https://platform.openai.com/playground) to get a good starting point for your new tool definitions.

72 

73### Prompting-Induced Planning & Chain-of-Thought

74 

75As mentioned already, developers can optionally prompt agents built with GPT-4.1 to plan and reflect between tool calls, instead of silently calling tools in an unbroken sequence. GPT-4.1 is not a reasoning model \- meaning that it does not produce an internal chain of thought before answering \- but in the prompt, a developer can induce the model to produce an explicit, step-by-step plan by using any variant of the Planning prompt component shown above. This can be thought of as the model “thinking out loud.” In our experimentation with the SWE-bench Verified agentic task, inducing explicit planning increased the pass rate by 4%.

76 

77### Sample Prompt: SWE-bench Verified

78 

79Below, we share the agentic prompt that we used to achieve our highest score on SWE-bench Verified, which features detailed instructions about workflow and problem-solving strategy. This general pattern can be used for any agentic task.

80 

81```python

82from openai import OpenAI

83 

84client = OpenAI()

85 

86SYS_PROMPT_SWEBENCH = """

87You will be tasked to fix an issue from an open-source repository.

88 

89Your thinking should be thorough and so it's fine if it's very long. You can think step by step before and after each action you decide to take.

90 

91You MUST iterate and keep going until the problem is solved.

92 

93You already have everything you need to solve this problem in the /testbed folder, even without internet connection. I want you to fully solve this autonomously before coming back to me.

94 

95Only terminate your turn when you are sure that the problem is solved. Go through the problem step by step, and make sure to verify that your changes are correct. NEVER end your turn without having solved the problem, and when you say you are going to make a tool call, make sure you ACTUALLY make the tool call, instead of ending your turn.

96 

97THE PROBLEM CAN DEFINITELY BE SOLVED WITHOUT THE INTERNET.

98 

99Take your time and think through every step - remember to check your solution rigorously and watch out for boundary cases, especially with the changes you made. Your solution must be perfect. If not, continue working on it. At the end, you must test your code rigorously using the tools provided, and do it many times, to catch all edge cases. If it is not robust, iterate more and make it perfect. Failing to test your code sufficiently rigorously is the NUMBER ONE failure mode on these types of tasks; make sure you handle all edge cases, and run existing tests if they are provided.

100 

101You MUST plan extensively before each function call, and reflect extensively on the outcomes of the previous function calls. DO NOT do this entire process by making function calls only, as this can impair your ability to solve the problem and think insightfully.

102 

103# Workflow

104 

105## High-Level Problem Solving Strategy

106 

1071. Understand the problem deeply. Carefully read the issue and think critically about what is required.

1082. Investigate the codebase. Explore relevant files, search for key functions, and gather context.

1093. Develop a clear, step-by-step plan. Break down the fix into manageable, incremental steps.

1104. Implement the fix incrementally. Make small, testable code changes.

1115. Debug as needed. Use debugging techniques to isolate and resolve issues.

1126. Test frequently. Run tests after each change to verify correctness.

1137. Iterate until the root cause is fixed and all tests pass.

1148. Reflect and validate comprehensively. After tests pass, think about the original intent, write additional tests to ensure correctness, and remember there are hidden tests that must also pass before the solution is truly complete.

115 

116Refer to the detailed sections below for more information on each step.

117 

118## 1. Deeply Understand the Problem

119Carefully read the issue and think hard about a plan to solve it before coding.

120 

121## 2. Codebase Investigation

122- Explore relevant files and directories.

123- Search for key functions, classes, or variables related to the issue.

124- Read and understand relevant code snippets.

125- Identify the root cause of the problem.

126- Validate and update your understanding continuously as you gather more context.

127 

128## 3. Develop a Detailed Plan

129- Outline a specific, simple, and verifiable sequence of steps to fix the problem.

130- Break down the fix into small, incremental changes.

131 

132## 4. Making Code Changes

133- Before editing, always read the relevant file contents or section to ensure complete context.

134- If a patch is not applied correctly, attempt to reapply it.

135- Make small, testable, incremental changes that logically follow from your investigation and plan.

136 

137## 5. Debugging

138- Make code changes only if you have high confidence they can solve the problem

139- When debugging, try to determine the root cause rather than addressing symptoms

140- Debug for as long as needed to identify the root cause and identify a fix

141- Use print statements, logs, or temporary code to inspect program state, including descriptive statements or error messages to understand what's happening

142- To test hypotheses, you can also add test statements or functions

143- Revisit your assumptions if unexpected behavior occurs.

144 

145## 6. Testing

146- Run tests frequently using `!python3 run_tests.py` (or equivalent).

147- After each change, verify correctness by running relevant tests.

148- If tests fail, analyze failures and revise your patch.

149- Write additional tests if needed to capture important behaviors or edge cases.

150- Ensure all tests pass before finalizing.

151 

152## 7. Final Verification

153- Confirm the root cause is fixed.

154- Review your solution for logic correctness and robustness.

155- Iterate until you are extremely confident the fix is complete and all tests pass.

156 

157## 8. Final Reflection and Additional Testing

158- Reflect carefully on the original intent of the user and the problem statement.

159- Think about potential edge cases or scenarios that may not be covered by existing tests.

160- Write additional tests that would need to pass to fully validate the correctness of your solution.

161- Run these new tests and ensure they all pass.

162- Be aware that there are additional hidden tests that must also pass for the solution to be successful.

163- Do not assume the task is complete just because the visible tests pass; continue refining until you are confident the fix is robust and comprehensive.

164"""

165 

166PYTHON_TOOL_DESCRIPTION = """This function is used to execute Python code or terminal commands in a stateful Jupyter notebook environment. python will respond with the output of the execution or time out after 60.0 seconds. Internet access for this session is disabled. Do not make external web requests or API calls as they will fail. Just as in a Jupyter notebook, you may also execute terminal commands by calling this function with a terminal command, prefaced with an exclamation mark.

167 

168In addition, for the purposes of this task, you can call this function with an `apply_patch` command as input. `apply_patch` effectively allows you to execute a diff/patch against a file, but the format of the diff specification is unique to this task, so pay careful attention to these instructions. To use the `apply_patch` command, you should pass a message of the following structure as "input":

169 

170%%bash

171apply_patch <<"EOF"

172*** Begin Patch

173[YOUR_PATCH]

174*** End Patch

175EOF

176 

177Where [YOUR_PATCH] is the actual content of your patch, specified in the following V4A diff format.

178 

179*** [ACTION] File: [path/to/file] -> ACTION can be one of Add, Update, or Delete.

180For each snippet of code that needs to be changed, repeat the following:

181[context_before] -> See below for further instructions on context.

182- [old_code] -> Precede the old code with a minus sign.

183+ [new_code] -> Precede the new, replacement code with a plus sign.

184[context_after] -> See below for further instructions on context.

185 

186For instructions on [context_before] and [context_after]:

187- By default, show 3 lines of code immediately above and 3 lines immediately below each change. If a change is within 3 lines of a previous change, do NOT duplicate the first change's [context_after] lines in the second change's [context_before] lines.

188- If 3 lines of context is insufficient to uniquely identify the snippet of code within the file, use the @@ operator to indicate the class or function to which the snippet belongs. For instance, we might have:

189@@ class BaseClass

190[3 lines of pre-context]

191- [old_code]

192+ [new_code]

193[3 lines of post-context]

194 

195- If a code block is repeated so many times in a class or function such that even a single @@ statement and 3 lines of context cannot uniquely identify the snippet of code, you can use multiple `@@` statements to jump to the right context. For instance:

196 

197@@ class BaseClass

198@@ def method():

199[3 lines of pre-context]

200- [old_code]

201+ [new_code]

202[3 lines of post-context]

203 

204Note, then, that we do not use line numbers in this diff format, as the context is enough to uniquely identify code. An example of a message that you might pass as "input" to this function, in order to apply a patch, is shown below.

205 

206%%bash

207apply_patch <<"EOF"

208*** Begin Patch

209*** Update File: pygorithm/searching/binary_search.py

210@@ class BaseClass

211@@ def search():

212- pass

213+ raise NotImplementedError()

214 

215@@ class Subclass

216@@ def search():

217- pass

218+ raise NotImplementedError()

219 

220*** End Patch

221EOF

222 

223File references can only be relative, NEVER ABSOLUTE. After the apply_patch command is run, Python will always say "Done!", regardless of whether the patch was successfully applied or not. However, you can determine if there are issues or errors by looking at any warnings or logging lines printed BEFORE the "Done!" is output.

224"""

225 

226python_bash_patch_tool = {

227 "type": "function",

228 "name": "python",

229 "description": PYTHON_TOOL_DESCRIPTION,

230 "parameters": {

231 "type": "object",

232 "strict": True,

233 "properties": {

234 "input": {

235 "type": "string",

236 "description": " The Python code, terminal command (prefaced by exclamation mark), or apply_patch command that you wish to execute.",

237 }

238 },

239 "required": ["input"],

240 },

241}

242 

243# Additional harness setup:

244# - Add your repo to /testbed

245# - Add your issue to the first user message

246# - Note: Even though we used a single tool for python, bash, and apply_patch, we generally recommend defining more granular tools that are focused on a single function

247 

248response = client.responses.create(

249 instructions=SYS_PROMPT_SWEBENCH,

250 model="gpt-4.1-2025-04-14",

251 tools=[python_bash_patch_tool],

252 input="Please answer the following question:\nBug: Typerror...",

253)

254 

255response.to_dict()["output"]

256```

257 

258```java

259import com.openai.client.OpenAIClient;

260import com.openai.client.okhttp.OpenAIOkHttpClient;

261import com.openai.core.JsonValue;

262import com.openai.models.responses.FunctionTool;

263import com.openai.models.responses.ResponseCreateParams;

264import java.util.List;

265import java.util.Map;

266 

267String agentInstructions =

268 """

269 You will be tasked to fix an issue from an open-source repository.

270 

271 Your thinking should be thorough and so it's fine if it's very long. You can think step by step before and after each action you decide to take.

272 

273 You MUST iterate and keep going until the problem is solved.

274 

275 You already have everything you need to solve this problem in the /testbed folder, even without internet connection. I want you to fully solve this autonomously before coming back to me.

276 

277 Only terminate your turn when you are sure that the problem is solved. Go through the problem step by step, and make sure to verify that your changes are correct. NEVER end your turn without having solved the problem, and when you say you are going to make a tool call, make sure you ACTUALLY make the tool call, instead of ending your turn.

278 

279 THE PROBLEM CAN DEFINITELY BE SOLVED WITHOUT THE INTERNET.

280 

281 Take your time and think through every step - remember to check your solution rigorously and watch out for boundary cases, especially with the changes you made. Your solution must be perfect. If not, continue working on it. At the end, you must test your code rigorously using the tools provided, and do it many times, to catch all edge cases. If it is not robust, iterate more and make it perfect. Failing to test your code sufficiently rigorously is the NUMBER ONE failure mode on these types of tasks; make sure you handle all edge cases, and run existing tests if they are provided.

282 

283 You MUST plan extensively before each function call, and reflect extensively on the outcomes of the previous function calls. DO NOT do this entire process by making function calls only, as this can impair your ability to solve the problem and think insightfully.

284 

285 # Workflow

286 

287 ## High-Level Problem Solving Strategy

288 

289 1. Understand the problem deeply. Carefully read the issue and think critically about what is required.

290 2. Investigate the codebase. Explore relevant files, search for key functions, and gather context.

291 3. Develop a clear, step-by-step plan. Break down the fix into manageable, incremental steps.

292 4. Implement the fix incrementally. Make small, testable code changes.

293 5. Debug as needed. Use debugging techniques to isolate and resolve issues.

294 6. Test frequently. Run tests after each change to verify correctness.

295 7. Iterate until the root cause is fixed and all tests pass.

296 8. Reflect and validate comprehensively. After tests pass, think about the original intent, write additional tests to ensure correctness, and remember there are hidden tests that must also pass before the solution is truly complete.

297 

298 Refer to the detailed sections below for more information on each step.

299 

300 ## 1. Deeply Understand the Problem

301 Carefully read the issue and think hard about a plan to solve it before coding.

302 

303 ## 2. Codebase Investigation

304 - Explore relevant files and directories.

305 - Search for key functions, classes, or variables related to the issue.

306 - Read and understand relevant code snippets.

307 - Identify the root cause of the problem.

308 - Validate and update your understanding continuously as you gather more context.

309 

310 ## 3. Develop a Detailed Plan

311 - Outline a specific, simple, and verifiable sequence of steps to fix the problem.

312 - Break down the fix into small, incremental changes.

313 

314 ## 4. Making Code Changes

315 - Before editing, always read the relevant file contents or section to ensure complete context.

316 - If a patch is not applied correctly, attempt to reapply it.

317 - Make small, testable, incremental changes that logically follow from your investigation and plan.

318 

319 ## 5. Debugging

320 - Make code changes only if you have high confidence they can solve the problem

321 - When debugging, try to determine the root cause rather than addressing symptoms

322 - Debug for as long as needed to identify the root cause and identify a fix

323 - Use print statements, logs, or temporary code to inspect program state, including descriptive statements or error messages to understand what's happening

324 - To test hypotheses, you can also add test statements or functions

325 - Revisit your assumptions if unexpected behavior occurs.

326 

327 ## 6. Testing

328 - Run tests frequently using `!python3 run_tests.py` (or equivalent).

329 - After each change, verify correctness by running relevant tests.

330 - If tests fail, analyze failures and revise your patch.

331 - Write additional tests if needed to capture important behaviors or edge cases.

332 - Ensure all tests pass before finalizing.

333 

334 ## 7. Final Verification

335 - Confirm the root cause is fixed.

336 - Review your solution for logic correctness and robustness.

337 - Iterate until you are extremely confident the fix is complete and all tests pass.

338 

339 ## 8. Final Reflection and Additional Testing

340 - Reflect carefully on the original intent of the user and the problem statement.

341 - Think about potential edge cases or scenarios that may not be covered by existing tests.

342 - Write additional tests that would need to pass to fully validate the correctness of your solution.

343 - Run these new tests and ensure they all pass.

344 - Be aware that there are additional hidden tests that must also pass for the solution to be successful.

345 - Do not assume the task is complete just because the visible tests pass; continue refining until you are confident the fix is robust and comprehensive.

346 """;

347String pythonToolDescription =

348 """

349 This function is used to execute Python code or terminal commands in a stateful Jupyter notebook environment. python will respond with the output of the execution or time out after 60.0 seconds. Internet access for this session is disabled. Do not make external web requests or API calls as they will fail. Just as in a Jupyter notebook, you may also execute terminal commands by calling this function with a terminal command, prefaced with an exclamation mark.

350 

351 In addition, for the purposes of this task, you can call this function with an `apply_patch` command as input. `apply_patch` effectively allows you to execute a diff/patch against a file, but the format of the diff specification is unique to this task, so pay careful attention to these instructions. To use the `apply_patch` command, you should pass a message of the following structure as "input":

352 

353 %%bash

354 apply_patch <<"EOF"

355 *** Begin Patch

356 [YOUR_PATCH]

357 *** End Patch

358 EOF

359 

360 Where [YOUR_PATCH] is the actual content of your patch, specified in the following V4A diff format.

361 

362 *** [ACTION] File: [path/to/file] -> ACTION can be one of Add, Update, or Delete.

363 For each snippet of code that needs to be changed, repeat the following:

364 [context_before] -> See below for further instructions on context.

365 - [old_code] -> Precede the old code with a minus sign.

366 + [new_code] -> Precede the new, replacement code with a plus sign.

367 [context_after] -> See below for further instructions on context.

368 

369 For instructions on [context_before] and [context_after]:

370 - By default, show 3 lines of code immediately above and 3 lines immediately below each change. If a change is within 3 lines of a previous change, do NOT duplicate the first change's [context_after] lines in the second change's [context_before] lines.

371 - If 3 lines of context is insufficient to uniquely identify the snippet of code within the file, use the @@ operator to indicate the class or function to which the snippet belongs. For instance, we might have:

372 @@ class BaseClass

373 [3 lines of pre-context]

374 - [old_code]

375 + [new_code]

376 [3 lines of post-context]

377 

378 - If a code block is repeated so many times in a class or function such that even a single @@ statement and 3 lines of context cannot uniquely identify the snippet of code, you can use multiple `@@` statements to jump to the right context. For instance:

379 

380 @@ class BaseClass

381 @@ def method():

382 [3 lines of pre-context]

383 - [old_code]

384 + [new_code]

385 [3 lines of post-context]

386 

387 Note, then, that we do not use line numbers in this diff format, as the context is enough to uniquely identify code. An example of a message that you might pass as "input" to this function, in order to apply a patch, is shown below.

388 

389 %%bash

390 apply_patch <<"EOF"

391 *** Begin Patch

392 *** Update File: pygorithm/searching/binary_search.py

393 @@ class BaseClass

394 @@ def search():

395 - pass

396 + raise NotImplementedError()

397 

398 @@ class Subclass

399 @@ def search():

400 - pass

401 + raise NotImplementedError()

402 

403 *** End Patch

404 EOF

405 

406 File references can only be relative, NEVER ABSOLUTE. After the apply_patch command is run, Python will always say "Done!", regardless of whether the patch was successfully applied or not. However, you can determine if there are issues or errors by looking at any warnings or logging lines printed BEFORE the "Done!" is output.

407 """;

408 

409ResponseCreateParams params =

410 ResponseCreateParams.builder()

411 .model("gpt-4.1-2025-04-14")

412 .instructions(agentInstructions)

413 .input("Please answer the following question:\nBug: Typerror...")

414 .addTool(

415 FunctionTool.builder()

416 .name("python")

417 .description(pythonToolDescription)

418 .parameters(

419 FunctionTool.Parameters.builder()

420 .putAdditionalProperty("type", JsonValue.from("object"))

421 .putAdditionalProperty(

422 "properties",

423 JsonValue.from(

424 Map.of(

425 "input",

426 Map.of(

427 "type", "string",

428 "description",

429 "The Python code, terminal command, or apply_patch command to execute."))))

430 .putAdditionalProperty("required", JsonValue.from(List.of("input")))

431 .putAdditionalProperty("additionalProperties", JsonValue.from(false))

432 .build())

433 .strict(true)

434 .build())

435 .build();

436 

437client.responses().create(params).output().forEach(System.out::println);

438```

439 

440```ruby

441require "openai"

442 

443client = OpenAI::Client.new

444response = client.responses.create(

445 model: "gpt-4.1",

446 instructions: "Act as a coding agent. Inspect the reported failure, identify the smallest correct change, and explain how you would verify it.",

447 input: "The parser rejects an empty optional field even though the schema permits it. Diagnose the likely validation bug."

448)

449 

450puts(response.output_text)

451```

452 

453 

454```text

455[{'id': 'msg_67fe92df26ac819182ffafce9ff4e4fc07c7e06242e51f8b',

456 'content': [{'annotations': [],

457 'text': "Thank you for the report, but “Typerror” is too vague for me to start debugging right away.\n\n**To make progress, I need to:**\n1. Find the exact error message text (e.g. `'TypeError: ...'`).\n2. Find which file and which line/function/class the error occurred in.\n3. Figure out what triggered the error (test file, usage, reproduction steps).\n4. Find the root cause and details.\n\n**Next steps:**\n- Investigate error/log/test output files for a Python `TypeError` message.\n- Examine the relevant code sections for problematic type usage.\n- If possible, reproduce the bug locally.\n\n**Plan:**\n- First, I will search for test files and log output in the `/testbed` directory that may contain the full error message and stack trace.\n\nLet’s start by listing the contents of the `/testbed` directory to look for clues.",

458 'type': 'output_text'}],

459 'role': 'assistant',

460 'status': 'completed',

461 'type': 'message'},

462 {'arguments': '{"input":"!ls -l /testbed"}',

463 'call_id': 'call_frnxyJgKi5TsBem0nR9Zuzdw',

464 'name': 'python',

465 'type': 'function_call',

466 'id': 'fc_67fe92e3da7081918fc18d5c96dddc1c07c7e06242e51f8b',

467 'status': 'completed'}]

468```

469 

470### 2. Long context

471 

472GPT-4.1 has a performant 1M token input context window, and is useful for a variety of long context tasks, including structured document parsing, re-ranking, selecting relevant information while ignoring irrelevant context, and performing multi-hop reasoning using context.

473 

474### Optimal Context Size

475 

476We observe very good performance on needle-in-a-haystack evaluations up to our full 1M token context, and we’ve observed very strong performance at complex tasks with a mix of both relevant and irrelevant code and other documents. However, long context performance can degrade as more items are required to be retrieved, or perform complex reasoning that requires knowledge of the state of the entire context (like performing a graph search, for example).

477 

478### Tuning Context Reliance

479 

480Consider the mix of external vs. internal world knowledge that might be required to answer your question. Sometimes it’s important for the model to use some of its own knowledge to connect concepts or make logical jumps, while in others it’s desirable to only use provided context

481 

482```text

483# Instructions

484// for internal knowledge

485- Only use the documents in the provided External Context to answer the User Query. If you don't know the answer based on this context, you must respond "I don't have the information needed to answer that", even if a user insists on you answering the question.

486// For internal and external knowledge

487- By default, use the provided external context to answer the User Query, but if other basic knowledge is needed to answer, and you're confident in the answer, you can use some of your own knowledge to help answer the question.

488```

489 

490### Prompt Organization

491 

492Especially in long context usage, placement of instructions and context can impact performance. If you have long context in your prompt, ideally place your instructions at both the beginning and end of the provided context, as we found this to perform better than only above or below. If you’d prefer to only have your instructions once, then above the provided context works better than below.

493 

494### 3. Chain of Thought

495 

496As mentioned above, GPT-4.1 is not a reasoning model, but prompting the model to think step by step (called “chain of thought”) can be an effective way for a model to break down problems into more manageable pieces, solve them, and improve overall output quality, with the tradeoff of higher cost and latency associated with using more output tokens. The model has been trained to perform well at agentic reasoning about and real-world problem solving, so it shouldn’t require much prompting to perform well.

497 

498We recommend starting with this basic chain-of-thought instruction at the end of your prompt:

499 

500```text

501...

502 

503First, think carefully step by step about what documents are needed to answer the query. Then, print out the TITLE and ID of each document. Then, format the IDs into a list.

504```

505 

506From there, you should improve your chain-of-thought (CoT) prompt by auditing failures in your particular examples and evals, and addressing systematic planning and reasoning errors with more explicit instructions. In the unconstrained CoT prompt, there may be variance in the strategies it tries, and if you observe an approach that works well, you can codify that strategy in your prompt. Generally speaking, errors tend to occur from misunderstanding user intent, insufficient context gathering or analysis, or insufficient or incorrect step by step thinking, so watch out for these and try to address them with more opinionated instructions.

507 

508Here is an example prompt instructing the model to focus more methodically on analyzing user intent and considering relevant context before proceeding to answer.

509 

510```text

511# Reasoning Strategy

5121. Query Analysis: Break down and analyze the query until you're confident about what it might be asking. Consider the provided context to help clarify any ambiguous or confusing information.

5132. Context Analysis: Carefully select and analyze a large set of potentially relevant documents. Optimize for recall - it's okay if some are irrelevant, but the correct documents must be in this list, otherwise your final answer will be wrong. Analysis steps for each:

514 a. Analysis: An analysis of how it may or may not be relevant to answering the query.

515 b. Relevance rating: [high, medium, low, none]

5163. Synthesis: summarize which documents are most relevant and why, including all documents with a relevance rating of medium or higher.

517 

518# User Question

519{user_question}

520 

521# External Context

522{external_context}

523 

524First, think carefully step by step about what documents are needed to answer the query, closely adhering to the provided Reasoning Strategy. Then, print out the TITLE and ID of each document. Then, format the IDs into a list.

525```

526 

527### 4. Instruction Following

528 

529GPT-4.1 exhibits outstanding instruction-following performance, which developers can leverage to precisely shape and control the outputs for their particular use cases. Developers often extensively prompt for agentic reasoning steps, response tone and voice, tool calling information, output formatting, topics to avoid, and more. However, since the model follows instructions more literally, developers may need to include explicit specification around what to do or not to do. Furthermore, existing prompts optimized for other models may not immediately work with this model, because existing instructions are followed more closely and implicit rules are no longer being as strongly inferred.

530 

531### Recommended Workflow

532 

533Here is our recommended workflow for developing and debugging instructions in prompts:

534 

5351. Start with an overall “Response Rules” or “Instructions” section with high-level guidance and bullet points.

5362. If you’d like to change a more specific behavior, add a section to specify more details for that category, like `# Sample Phrases`.

5373. If there are specific steps you’d like the model to follow in its workflow, add an ordered list and instruct the model to follow these steps.

5384. If behavior still isn’t working as expected:

539 1. Check for conflicting, underspecified, or wrong instructions and examples. If there are conflicting instructions, GPT-4.1 tends to follow the one closer to the end of the prompt.

540 2. Add examples that demonstrate desired behavior; ensure that any important behavior demonstrated in your examples are also cited in your rules.

541 3. It’s generally not necessary to use all-caps or other incentives like bribes or tips. We recommend starting without these, and only reaching for these if necessary for your particular prompt. Note that if your existing prompts include these techniques, it could cause GPT-4.1 to pay attention to it too strictly.

542 

543_Note that using your preferred AI-powered IDE can be very helpful for iterating on prompts, including checking for consistency or conflicts, adding examples, or making cohesive updates like adding an instruction and updating instructions to demonstrate that instruction._

544 

545### Common Failure Modes

546 

547These failure modes are not unique to GPT-4.1, but we share them here for general awareness and ease of debugging.

548 

549- Instructing a model to always follow a specific behavior can occasionally induce adverse effects. For instance, if told “you must call a tool before responding to the user,” models may hallucinate tool inputs or call the tool with null values if they do not have enough information. Adding “if you don’t have enough information to call the tool, ask the user for the information you need” should mitigate this.

550- When provided sample phrases, models can use those quotes verbatim and start to sound repetitive to users. Ensure you instruct the model to vary them as necessary.

551- Without specific instructions, some models can be eager to provide additional prose to explain their decisions, or output more formatting in responses than may be desired. Provide instructions and potentially examples to help mitigate.

552 

553### Example Prompt: Customer Service

554 

555This demonstrates best practices for a fictional customer service agent. Observe the diversity of rules, the specificity, the use of additional sections for greater detail, and an example to demonstrate precise behavior that incorporates all prior rules.

556 

557Try running the following notebook cell - you should see both a user message and tool call, and the user message should start with a greeting, then echo back their answer, then mention they're about to call a tool. Try changing the instructions to shape the model behavior, or trying other user messages, to test instruction following performance.

558 

559```python

560SYS_PROMPT_CUSTOMER_SERVICE = """You are a helpful customer service agent working for NewTelco, helping a user efficiently fulfill their request while adhering closely to provided guidelines.

561 

562# Instructions

563- Always greet the user with "Hi, you've reached NewTelco, how can I help you?"

564- Always call a tool before answering factual questions about the company, its offerings or products, or a user's account. Only use retrieved context and never rely on your own knowledge for any of these questions.

565 - However, if you don't have enough information to properly call the tool, ask the user for the information you need.

566- Escalate to a human if the user requests.

567- Do not discuss prohibited topics (politics, religion, controversial current events, medical, legal, or financial advice, personal conversations, internal company operations, or criticism of any people or company).

568- Rely on sample phrases whenever appropriate, but never repeat a sample phrase in the same conversation. Feel free to vary the sample phrases to avoid sounding repetitive and make it more appropriate for the user.

569- Always follow the provided output format for new messages, including citations for any factual statements from retrieved policy documents.

570- If you're going to call a tool, always message the user with an appropriate message before and after calling the tool.

571- Maintain a professional and concise tone in all responses, and use emojis between sentences.

572- If you've resolved the user's request, ask if there's anything else you can help with

573 

574# Precise Response Steps (for each response)

5751. If necessary, call tools to fulfill the user's desired action. Always message the user before and after calling a tool to keep them in the loop.

5762. In your response to the user

577 a. Use active listening and echo back what you heard the user ask for.

578 b. Respond appropriately given the above guidelines.

579 

580# Sample Phrases

581## Deflecting a Prohibited Topic

582- "I'm sorry, but I'm unable to discuss that topic. Is there something else I can help you with?"

583- "That's not something I'm able to provide information on, but I'm happy to help with any other questions you may have."

584 

585## Before calling a tool

586- "To help you with that, I'll just need to verify your information."

587- "Let me check that for you—one moment, please."

588- "I'll retrieve the latest details for you now."

589 

590## After calling a tool

591- "Okay, here's what I found: [response]"

592- "So here's what I found: [response]"

593 

594# Output Format

595- Always include your final response to the user.

596- When providing factual information from retrieved context, always include citations immediately after the relevant statement(s). Use the following citation format:

597 - For a single source: [NAME](ID)

598 - For multiple sources: [NAME](ID), [NAME](ID)

599- Only provide information about this company, its policies, its products, or the customer's account, and only if it is based on information provided in context. Do not answer questions outside this scope.

600 

601# Example

602## User

603Can you tell me about your family plan options?

604 

605## Assistant Response 1

606### Message

607"Hi, you've reached NewTelco, how can I help you? 😊🎉\n\nYou'd like to know about our family plan options. 🤝 Let me check that for you—one moment, please. 🚀"

608 

609### Tool Calls

610lookup_policy_document(topic="family plan options")

611 

612// After tool call, the assistant would follow up with:

613 

614## Assistant Response 2 (after tool call)

615### Message

616"Okay, here's what I found: 🎉 Our family plan allows up to 5 lines with shared data and a 10% discount for each additional line [Family Plan Policy](ID-010). 📱 Is there anything else I can help you with today? 😊"

617"""

618 

619get_policy_doc = {

620 "type": "function",

621 "name": "lookup_policy_document",

622 "description": "Tool to look up internal documents and policies by topic or keyword.",

623 "parameters": {

624 "strict": True,

625 "type": "object",

626 "properties": {

627 "topic": {

628 "type": "string",

629 "description": "The topic or keyword to search for in company policies or documents.",

630 },

631 },

632 "required": ["topic"],

633 "additionalProperties": False,

634 },

635}

636 

637get_user_acct = {

638 "type": "function",

639 "name": "get_user_account_info",

640 "description": "Tool to get user account information",

641 "parameters": {

642 "strict": True,

643 "type": "object",

644 "properties": {

645 "phone_number": {

646 "type": "string",

647 "description": "Formatted as '(xxx) xxx-xxxx'",

648 },

649 },

650 "required": ["phone_number"],

651 "additionalProperties": False,

652 },

653}

654 

655response = client.responses.create(

656 instructions=SYS_PROMPT_CUSTOMER_SERVICE,

657 model="gpt-4.1-2025-04-14",

658 tools=[get_policy_doc, get_user_acct],

659 input="How much will it cost for international service? I'm traveling to France.",

660 # input="Why was my last bill so high?"

661)

662 

663response.to_dict()["output"]

664```

665 

666```java

667import com.openai.client.OpenAIClient;

668import com.openai.client.okhttp.OpenAIOkHttpClient;

669import com.openai.core.JsonValue;

670import com.openai.models.responses.FunctionTool;

671import com.openai.models.responses.ResponseCreateParams;

672import java.util.List;

673import java.util.Map;

674 

675String customerServiceInstructions =

676 """

677 You are a helpful customer service agent working for NewTelco, helping a user efficiently fulfill their request while adhering closely to provided guidelines.

678 

679 # Instructions

680 - Always greet the user with "Hi, you've reached NewTelco, how can I help you?"

681 - Always call a tool before answering factual questions about the company, its offerings or products, or a user's account. Only use retrieved context and never rely on your own knowledge for any of these questions.

682 - However, if you don't have enough information to properly call the tool, ask the user for the information you need.

683 - Escalate to a human if the user requests.

684 - Do not discuss prohibited topics (politics, religion, controversial current events, medical, legal, or financial advice, personal conversations, internal company operations, or criticism of any people or company).

685 - Rely on sample phrases whenever appropriate, but never repeat a sample phrase in the same conversation. Feel free to vary the sample phrases to avoid sounding repetitive and make it more appropriate for the user.

686 - Always follow the provided output format for new messages, including citations for any factual statements from retrieved policy documents.

687 - If you're going to call a tool, always message the user with an appropriate message before and after calling the tool.

688 - Maintain a professional and concise tone in all responses, and use emojis between sentences.

689 - If you've resolved the user's request, ask if there's anything else you can help with

690 

691 # Precise Response Steps (for each response)

692 1. If necessary, call tools to fulfill the user's desired action. Always message the user before and after calling a tool to keep them in the loop.

693 2. In your response to the user

694 a. Use active listening and echo back what you heard the user ask for.

695 b. Respond appropriately given the above guidelines.

696 

697 # Sample Phrases

698 ## Deflecting a Prohibited Topic

699 - "I'm sorry, but I'm unable to discuss that topic. Is there something else I can help you with?"

700 - "That's not something I'm able to provide information on, but I'm happy to help with any other questions you may have."

701 

702 ## Before calling a tool

703 - "To help you with that, I'll just need to verify your information."

704 - "Let me check that for you—one moment, please."

705 - "I'll retrieve the latest details for you now."

706 

707 ## After calling a tool

708 - "Okay, here's what I found: [response]"

709 - "So here's what I found: [response]"

710 

711 # Output Format

712 - Always include your final response to the user.

713 - When providing factual information from retrieved context, always include citations immediately after the relevant statement(s). Use the following citation format:

714 - For a single source: [NAME](ID)

715 - For multiple sources: [NAME](ID), [NAME](ID)

716 - Only provide information about this company, its policies, its products, or the customer's account, and only if it is based on information provided in context. Do not answer questions outside this scope.

717 

718 # Example

719 ## User

720 Can you tell me about your family plan options?

721 

722 ## Assistant Response 1

723 ### Message

724 "Hi, you've reached NewTelco, how can I help you? 😊🎉

725 

726 You'd like to know about our family plan options. 🤝 Let me check that for you—one moment, please. 🚀"

727 

728 ### Tool Calls

729 lookup_policy_document(topic="family plan options")

730 

731 // After tool call, the assistant would follow up with:

732 

733 ## Assistant Response 2 (after tool call)

734 ### Message

735 "Okay, here's what I found: 🎉 Our family plan allows up to 5 lines with shared data and a 10% discount for each additional line [Family Plan Policy](ID-010). 📱 Is there anything else I can help you with today? 😊"

736 """;

737 

738ResponseCreateParams params =

739 ResponseCreateParams.builder()

740 .model("gpt-4.1-2025-04-14")

741 .instructions(customerServiceInstructions)

742 .input("How much will it cost for international service? I'm traveling to France.")

743 .addTool(

744 customerServiceTool(

745 "lookup_policy_document",

746 "Tool to look up internal documents and policies by topic or keyword.",

747 "topic",

748 "The topic or keyword to search for in company policies or documents."))

749 .addTool(

750 customerServiceTool(

751 "get_user_account_info",

752 "Tool to get user account information",

753 "phone_number",

754 "Formatted as '(xxx) xxx-xxxx'"))

755 .build();

756 

757client.responses().create(params).output().forEach(System.out::println);

758 

759private static FunctionTool customerServiceTool(

760 String name, String description, String parameter, String parameterDescription) {

761 return FunctionTool.builder()

762 .name(name)

763 .description(description)

764 .strict(true)

765 .parameters(

766 FunctionTool.Parameters.builder()

767 .putAdditionalProperty("type", JsonValue.from("object"))

768 .putAdditionalProperty(

769 "properties",

770 JsonValue.from(

771 Map.of(

772 parameter,

773 Map.of("type", "string", "description", parameterDescription))))

774 .putAdditionalProperty("required", JsonValue.from(List.of(parameter)))

775 .putAdditionalProperty("additionalProperties", JsonValue.from(false))

776 .build())

777 .build();

778}

779```

780 

781```ruby

782require "openai"

783 

784client = OpenAI::Client.new

785response = client.responses.create(

786 model: "gpt-4.1",

787 instructions: "You are a customer service assistant. Confirm the customer's goal, use only supplied account facts, and clearly explain the next action.",

788 input: "A customer says a replacement order still has not shipped. Draft a concise response."

789)

790 

791puts(response.output_text)

792```

793 

794 

795```text

796[{'id': 'msg_67fe92d431548191b7ca6cd604b4784b06efc5beb16b3c5e',

797 'content': [{'annotations': [],

798 'text': "Hi, you've reached NewTelco, how can I help you? 🌍✈️\n\nYou'd like to know the cost of international service while traveling to France. 🇫🇷 Let me check the latest details for you—one moment, please. 🕑",

799 'type': 'output_text'}],

800 'role': 'assistant',

801 'status': 'completed',

802 'type': 'message'},

803 {'arguments': '{"topic":"international service cost France"}',

804 'call_id': 'call_cF63DLeyhNhwfdyME3ZHd0yo',

805 'name': 'lookup_policy_document',

806 'type': 'function_call',

807 'id': 'fc_67fe92d5d6888191b6cd7cf57f707e4606efc5beb16b3c5e',

808 'status': 'completed'}]

809```

810 

811### 5. General Advice

812 

813### Prompt Structure

814 

815For reference, here is a good starting point for structuring your prompts.

816 

817```text

818# Role and Objective

819 

820# Instructions

821 

822## Sub-categories for more detailed instructions

823 

824# Reasoning Steps

825 

826# Output Format

827 

828# Examples

829## Example 1

830 

831# Context

832 

833# Final instructions and prompt to think step by step

834```

835 

836Add or remove sections to suit your needs, and experiment to determine what’s optimal for your usage.

837 

838### Delimiters

839 

840Here are some general guidelines for selecting the best delimiters for your prompt. Please refer to the Long Context section for special considerations for that context type.

841 

8421. Markdown: We recommend starting here, and using markdown titles for major sections and subsections (including deeper hierarchy, to H4+). Use inline backticks or backtick blocks to precisely wrap code, and standard numbered or bulleted lists as needed.

8432. XML: These also perform well, and we have improved adherence to information in XML with this model. XML is convenient to precisely wrap a section including start and end, add metadata to the tags for additional context, and enable nesting. Here is an example of using XML tags to nest examples in an example section, with inputs and outputs for each:

844 

845```text

846<examples>

847<example1 type="Abbreviate">

848<input>San Francisco</input>

849<output>- SF</output>

850</example1>

851</examples>

852```

853 

8543. JSON is highly structured and well understood by the model particularly in coding contexts. However it can be more verbose, and require character escaping that can add overhead.

855 

856Guidance specifically for adding a large number of documents or files to input context:

857 

858- XML performed well in our long context testing.

859 - Example: `<doc id='1' title='The Fox'>The quick brown fox jumps over the lazy dog</doc>`

860- This format, proposed by Lee et al. ([ref](https://arxiv.org/pdf/2406.13121)), also performed well in our long context testing.

861 - Example: `ID: 1 | TITLE: The Fox | CONTENT: The quick brown fox jumps over the lazy dog`

862- JSON performed particularly poorly.

863 - Example: `[{'id': 1, 'title': 'The Fox', 'content': 'The quick brown fox jumped over the lazy dog'}]`

864 

865The model is trained to robustly understand structure in a variety of formats. Generally, use your judgement and think about what will provide clear information and “stand out” to the model. For example, if you’re retrieving documents that contain lots of XML, an XML-based delimiter will likely be less effective.

866 

867### Caveats

868 

869- In some isolated cases we have observed the model being resistant to producing very long, repetitive outputs, for example, analyzing hundreds of items one by one. If this is necessary for your use case, instruct the model strongly to output this information in full, and consider breaking down the problem or using a more concise approach.

870- We have seen some rare instances of parallel tool calls being incorrect. We advise testing this, and considering setting the [parallel_tool_calls](https://developers.openai.com/api/reference/resources/responses/methods/create#responses-create-parallel_tool_calls) param to false if you’re seeing issues.

871 

872### Appendix: Generating and Applying File Diffs

873 

874Developers have provided us feedback that accurate and well-formed diff generation is a critical capability to power coding-related tasks. To this end, the GPT-4.1 family features substantially improved diff capabilities relative to previous GPT models. Moreover, while GPT-4.1 has strong performance generating diffs of any format given clear instructions and examples, we open-source here one recommended diff format, on which the model has been extensively trained. We hope that in particular for developers just starting out, that this will take much of the guesswork out of creating diffs yourself.

875 

876### Apply Patch

877 

878See the example below for a prompt that applies our recommended tool call correctly.

879 

880```python

881APPLY_PATCH_TOOL_DESC = """This is a custom utility that makes it more convenient to add, remove, move, or edit code files. `apply_patch` effectively allows you to execute a diff/patch against a file, but the format of the diff specification is unique to this task, so pay careful attention to these instructions. To use the `apply_patch` command, you should pass a message of the following structure as "input":

882 

883%%bash

884apply_patch <<"EOF"

885*** Begin Patch

886[YOUR_PATCH]

887*** End Patch

888EOF

889 

890Where [YOUR_PATCH] is the actual content of your patch, specified in the following V4A diff format.

891 

892*** [ACTION] File: [path/to/file] -> ACTION can be one of Add, Update, or Delete.

893For each snippet of code that needs to be changed, repeat the following:

894[context_before] -> See below for further instructions on context.

895- [old_code] -> Precede the old code with a minus sign.

896+ [new_code] -> Precede the new, replacement code with a plus sign.

897[context_after] -> See below for further instructions on context.

898 

899For instructions on [context_before] and [context_after]:

900- By default, show 3 lines of code immediately above and 3 lines immediately below each change. If a change is within 3 lines of a previous change, do NOT duplicate the first change’s [context_after] lines in the second change’s [context_before] lines.

901- If 3 lines of context is insufficient to uniquely identify the snippet of code within the file, use the @@ operator to indicate the class or function to which the snippet belongs. For instance, we might have:

902@@ class BaseClass

903[3 lines of pre-context]

904- [old_code]

905+ [new_code]

906[3 lines of post-context]

907 

908- If a code block is repeated so many times in a class or function such that even a single @@ statement and 3 lines of context cannot uniquely identify the snippet of code, you can use multiple `@@` statements to jump to the right context. For instance:

909 

910@@ class BaseClass

911@@ def method():

912[3 lines of pre-context]

913- [old_code]

914+ [new_code]

915[3 lines of post-context]

916 

917Note, then, that we do not use line numbers in this diff format, as the context is enough to uniquely identify code. An example of a message that you might pass as "input" to this function, in order to apply a patch, is shown below.

918 

919%%bash

920apply_patch <<"EOF"

921*** Begin Patch

922*** Update File: pygorithm/searching/binary_search.py

923@@ class BaseClass

924@@ def search():

925- pass

926+ raise NotImplementedError()

927 

928@@ class Subclass

929@@ def search():

930- pass

931+ raise NotImplementedError()

932 

933*** End Patch

934EOF

935"""

936 

937APPLY_PATCH_TOOL = {

938 "name": "apply_patch",

939 "description": APPLY_PATCH_TOOL_DESC,

940 "parameters": {

941 "type": "object",

942 "properties": {

943 "input": {

944 "type": "string",

945 "description": " The apply_patch command that you wish to execute.",

946 }

947 },

948 "required": ["input"],

949 },

950}

951```

952 

953```ruby

954require "json"

955 

956APPLY_PATCH_TOOL_DESC = <<~PROMPT

957 This is a custom utility that makes it more convenient to add, remove, move, or edit code files. `apply_patch` effectively allows you to execute a diff/patch against a file, but the format of the diff specification is unique to this task, so pay careful attention to these instructions. To use the `apply_patch` command, you should pass a message of the following structure as "input":

958 

959 %%bash

960 apply_patch <<"EOF"

961 *** Begin Patch

962 [YOUR_PATCH]

963 *** End Patch

964 EOF

965 

966 Where [YOUR_PATCH] is the actual content of your patch, specified in the following V4A diff format.

967 

968 *** [ACTION] File: [path/to/file] -> ACTION can be one of Add, Update, or Delete.

969 For each snippet of code that needs to be changed, repeat the following:

970 [context_before] -> See below for further instructions on context.

971 - [old_code] -> Precede the old code with a minus sign.

972 + [new_code] -> Precede the new, replacement code with a plus sign.

973 [context_after] -> See below for further instructions on context.

974 

975 For instructions on [context_before] and [context_after]:

976 - By default, show 3 lines of code immediately above and 3 lines immediately below each change. If a change is within 3 lines of a previous change, do NOT duplicate the first change’s [context_after] lines in the second change’s [context_before] lines.

977 - If 3 lines of context is insufficient to uniquely identify the snippet of code within the file, use the @@ operator to indicate the class or function to which the snippet belongs. For instance, we might have:

978 @@ class BaseClass

979 [3 lines of pre-context]

980 - [old_code]

981 + [new_code]

982 [3 lines of post-context]

983 

984 - If a code block is repeated so many times in a class or function such that even a single @@ statement and 3 lines of context cannot uniquely identify the snippet of code, you can use multiple `@@` statements to jump to the right context. For instance:

985 

986 @@ class BaseClass

987 @@ def method():

988 [3 lines of pre-context]

989 - [old_code]

990 + [new_code]

991 [3 lines of post-context]

992 

993 Note, then, that we do not use line numbers in this diff format, as the context is enough to uniquely identify code. An example of a message that you might pass as "input" to this function, in order to apply a patch, is shown below.

994 

995 %%bash

996 apply_patch <<"EOF"

997 *** Begin Patch

998 *** Update File: pygorithm/searching/binary_search.py

999 @@ class BaseClass

1000 @@ def search():

1001 - pass

1002 + raise NotImplementedError()

1003 

1004 @@ class Subclass

1005 @@ def search():

1006 - pass

1007 + raise NotImplementedError()

1008 

1009 *** End Patch

1010 EOF

1011 

1012PROMPT

1013 

1014tool = {

1015 name: "apply_patch",

1016 description: APPLY_PATCH_TOOL_DESC,

1017 parameters: {

1018 type: "object",

1019 properties: {

1020 input: {

1021 type: "string",

1022 description: "The apply_patch command to execute."

1023 }

1024 },

1025 required: ["input"]

1026 }

1027}

1028puts(JSON.generate(tool))

1029```

1030 

1031 

1032### Reference Implementation: apply_patch.py

1033 

1034Here’s a reference implementation of the apply_patch tool that we used as part of model training. You’ll need to make this an executable and available as \`apply_patch\` from the shell where the model will execute commands:

1035 

1036```python

1037#!/usr/bin/env python3

1038 

1039"""

1040A self-contained **pure-Python 3.9+** utility for applying human-readable

1041“pseudo-diff” patch files to a collection of text files.

1042"""

1043 

1044from __future__ import annotations

1045 

1046import pathlib

1047from collections.abc import Callable

1048from dataclasses import dataclass, field

1049from enum import Enum

1050 

1051 

1052# --------------------------------------------------------------------------- #

1053# Domain objects

1054# --------------------------------------------------------------------------- #

1055class ActionType(str, Enum):

1056 ADD = "add"

1057 DELETE = "delete"

1058 UPDATE = "update"

1059 

1060 

1061@dataclass

1062class FileChange:

1063 type: ActionType

1064 old_content: str | None = None

1065 new_content: str | None = None

1066 move_path: str | None = None

1067 

1068 

1069@dataclass

1070class Commit:

1071 changes: dict[str, FileChange] = field(default_factory=dict)

1072 

1073 

1074# --------------------------------------------------------------------------- #

1075# Exceptions

1076# --------------------------------------------------------------------------- #

1077class DiffError(ValueError):

1078 """Any problem detected while parsing or applying a patch."""

1079 

1080 

1081# --------------------------------------------------------------------------- #

1082# Helper dataclasses used while parsing patches

1083# --------------------------------------------------------------------------- #

1084@dataclass

1085class Chunk:

1086 orig_index: int = -1

1087 del_lines: list[str] = field(default_factory=list)

1088 ins_lines: list[str] = field(default_factory=list)

1089 

1090 

1091@dataclass

1092class PatchAction:

1093 type: ActionType

1094 new_file: str | None = None

1095 chunks: list[Chunk] = field(default_factory=list)

1096 move_path: str | None = None

1097 

1098 

1099@dataclass

1100class Patch:

1101 actions: dict[str, PatchAction] = field(default_factory=dict)

1102 

1103 

1104# --------------------------------------------------------------------------- #

1105# Patch text parser

1106# --------------------------------------------------------------------------- #

1107@dataclass

1108class Parser:

1109 current_files: dict[str, str]

1110 lines: list[str]

1111 index: int = 0

1112 patch: Patch = field(default_factory=Patch)

1113 fuzz: int = 0

1114 

1115 # ------------- low-level helpers -------------------------------------- #

1116 def _cur_line(self) -> str:

1117 if self.index >= len(self.lines):

1118 raise DiffError("Unexpected end of input while parsing patch")

1119 return self.lines[self.index]

1120 

1121 @staticmethod

1122 def _norm(line: str) -> str:

1123 """Strip CR so comparisons work for both LF and CRLF input."""

1124 return line.rstrip("\r")

1125 

1126 # ------------- scanning convenience ----------------------------------- #

1127 def is_done(self, prefixes: tuple[str, ...] | None = None) -> bool:

1128 if self.index >= len(self.lines):

1129 return True

1130 if (

1131 prefixes

1132 and len(prefixes) > 0

1133 and self._norm(self._cur_line()).startswith(prefixes)

1134 ):

1135 return True

1136 return False

1137 

1138 def startswith(self, prefix: str | tuple[str, ...]) -> bool:

1139 return self._norm(self._cur_line()).startswith(prefix)

1140 

1141 def read_str(self, prefix: str) -> str:

1142 """

1143 Consume the current line if it starts with *prefix* and return the text

1144 **after** the prefix. Raises if prefix is empty.

1145 """

1146 if prefix == "":

1147 raise ValueError("read_str() requires a non-empty prefix")

1148 if self._norm(self._cur_line()).startswith(prefix):

1149 text = self._cur_line()[len(prefix) :]

1150 self.index += 1

1151 return text

1152 return ""

1153 

1154 def read_line(self) -> str:

1155 """Return the current raw line and advance."""

1156 line = self._cur_line()

1157 self.index += 1

1158 return line

1159 

1160 # ------------- public entry point -------------------------------------- #

1161 def parse(self) -> None:

1162 while not self.is_done(("*** End Patch",)):

1163 # ---------- UPDATE ---------- #

1164 path = self.read_str("*** Update File: ")

1165 if path:

1166 if path in self.patch.actions:

1167 raise DiffError(f"Duplicate update for file: {path}")

1168 move_to = self.read_str("*** Move to: ")

1169 if path not in self.current_files:

1170 raise DiffError(f"Update File Error - missing file: {path}")

1171 text = self.current_files[path]

1172 action = self._parse_update_file(text)

1173 action.move_path = move_to or None

1174 self.patch.actions[path] = action

1175 continue

1176 

1177 # ---------- DELETE ---------- #

1178 path = self.read_str("*** Delete File: ")

1179 if path:

1180 if path in self.patch.actions:

1181 raise DiffError(f"Duplicate delete for file: {path}")

1182 if path not in self.current_files:

1183 raise DiffError(f"Delete File Error - missing file: {path}")

1184 self.patch.actions[path] = PatchAction(type=ActionType.DELETE)

1185 continue

1186 

1187 # ---------- ADD ---------- #

1188 path = self.read_str("*** Add File: ")

1189 if path:

1190 if path in self.patch.actions:

1191 raise DiffError(f"Duplicate add for file: {path}")

1192 if path in self.current_files:

1193 raise DiffError(f"Add File Error - file already exists: {path}")

1194 self.patch.actions[path] = self._parse_add_file()

1195 continue

1196 

1197 raise DiffError(f"Unknown line while parsing: {self._cur_line()}")

1198 

1199 if not self.startswith("*** End Patch"):

1200 raise DiffError("Missing *** End Patch sentinel")

1201 self.index += 1 # consume sentinel

1202 

1203 # ------------- section parsers ---------------------------------------- #

1204 def _parse_update_file(self, text: str) -> PatchAction:

1205 action = PatchAction(type=ActionType.UPDATE)

1206 lines = text.split("\n")

1207 index = 0

1208 while not self.is_done(

1209 (

1210 "*** End Patch",

1211 "*** Update File:",

1212 "*** Delete File:",

1213 "*** Add File:",

1214 "*** End of File",

1215 )

1216 ):

1217 def_str = self.read_str("@@ ")

1218 section_str = ""

1219 if not def_str and self._norm(self._cur_line()) == "@@":

1220 section_str = self.read_line()

1221 

1222 if not (def_str or section_str or index == 0):

1223 raise DiffError(f"Invalid line in update section:\n{self._cur_line()}")

1224 

1225 if def_str.strip():

1226 found = False

1227 if def_str not in lines[:index]:

1228 for i, s in enumerate(lines[index:], index):

1229 if s == def_str:

1230 index = i + 1

1231 found = True

1232 break

1233 if not found and def_str.strip() not in [

1234 s.strip() for s in lines[:index]

1235 ]:

1236 for i, s in enumerate(lines[index:], index):

1237 if s.strip() == def_str.strip():

1238 index = i + 1

1239 self.fuzz += 1

1240 found = True

1241 break

1242 

1243 next_ctx, chunks, end_idx, eof = peek_next_section(self.lines, self.index)

1244 new_index, fuzz = find_context(lines, next_ctx, index, eof)

1245 if new_index == -1:

1246 ctx_txt = "\n".join(next_ctx)

1247 raise DiffError(

1248 f"Invalid {'EOF ' if eof else ''}context at {index}:\n{ctx_txt}"

1249 )

1250 self.fuzz += fuzz

1251 for ch in chunks:

1252 ch.orig_index += new_index

1253 action.chunks.append(ch)

1254 index = new_index + len(next_ctx)

1255 self.index = end_idx

1256 return action

1257 

1258 def _parse_add_file(self) -> PatchAction:

1259 lines: list[str] = []

1260 while not self.is_done(

1261 ("*** End Patch", "*** Update File:", "*** Delete File:", "*** Add File:")

1262 ):

1263 s = self.read_line()

1264 if not s.startswith("+"):

1265 raise DiffError(f"Invalid Add File line (missing '+'): {s}")

1266 lines.append(s[1:]) # strip leading '+'

1267 return PatchAction(type=ActionType.ADD, new_file="\n".join(lines))

1268 

1269 

1270# --------------------------------------------------------------------------- #

1271# Helper functions

1272# --------------------------------------------------------------------------- #

1273def find_context_core(

1274 lines: list[str], context: list[str], start: int

1275) -> tuple[int, int]:

1276 if not context:

1277 return start, 0

1278 

1279 for i in range(start, len(lines)):

1280 if lines[i : i + len(context)] == context:

1281 return i, 0

1282 for i in range(start, len(lines)):

1283 if [s.rstrip() for s in lines[i : i + len(context)]] == [

1284 s.rstrip() for s in context

1285 ]:

1286 return i, 1

1287 for i in range(start, len(lines)):

1288 if [s.strip() for s in lines[i : i + len(context)]] == [

1289 s.strip() for s in context

1290 ]:

1291 return i, 100

1292 return -1, 0

1293 

1294 

1295def find_context(

1296 lines: list[str], context: list[str], start: int, eof: bool

1297) -> tuple[int, int]:

1298 if eof:

1299 new_index, fuzz = find_context_core(lines, context, len(lines) - len(context))

1300 if new_index != -1:

1301 return new_index, fuzz

1302 new_index, fuzz = find_context_core(lines, context, start)

1303 return new_index, fuzz + 10_000

1304 return find_context_core(lines, context, start)

1305 

1306 

1307def peek_next_section(

1308 lines: list[str], index: int

1309) -> tuple[list[str], list[Chunk], int, bool]:

1310 old: list[str] = []

1311 del_lines: list[str] = []

1312 ins_lines: list[str] = []

1313 chunks: list[Chunk] = []

1314 mode = "keep"

1315 orig_index = index

1316 

1317 while index < len(lines):

1318 s = lines[index]

1319 if s.startswith(

1320 (

1321 "@@",

1322 "*** End Patch",

1323 "*** Update File:",

1324 "*** Delete File:",

1325 "*** Add File:",

1326 "*** End of File",

1327 )

1328 ):

1329 break

1330 if s == "***":

1331 break

1332 if s.startswith("***"):

1333 raise DiffError(f"Invalid Line: {s}")

1334 index += 1

1335 

1336 last_mode = mode

1337 if s == "":

1338 s = " "

1339 if s[0] == "+":

1340 mode = "add"

1341 elif s[0] == "-":

1342 mode = "delete"

1343 elif s[0] == " ":

1344 mode = "keep"

1345 else:

1346 raise DiffError(f"Invalid Line: {s}")

1347 s = s[1:]

1348 

1349 if mode == "keep" and last_mode != mode:

1350 if ins_lines or del_lines:

1351 chunks.append(

1352 Chunk(

1353 orig_index=len(old) - len(del_lines),

1354 del_lines=del_lines,

1355 ins_lines=ins_lines,

1356 )

1357 )

1358 del_lines, ins_lines = [], []

1359 

1360 if mode == "delete":

1361 del_lines.append(s)

1362 old.append(s)

1363 elif mode == "add":

1364 ins_lines.append(s)

1365 elif mode == "keep":

1366 old.append(s)

1367 

1368 if ins_lines or del_lines:

1369 chunks.append(

1370 Chunk(

1371 orig_index=len(old) - len(del_lines),

1372 del_lines=del_lines,

1373 ins_lines=ins_lines,

1374 )

1375 )

1376 

1377 if index < len(lines) and lines[index] == "*** End of File":

1378 index += 1

1379 return old, chunks, index, True

1380 

1381 if index == orig_index:

1382 raise DiffError("Nothing in this section")

1383 return old, chunks, index, False

1384 

1385 

1386# --------------------------------------------------------------------------- #

1387# Patch → Commit and Commit application

1388# --------------------------------------------------------------------------- #

1389def _get_updated_file(text: str, action: PatchAction, path: str) -> str:

1390 if action.type is not ActionType.UPDATE:

1391 raise DiffError("_get_updated_file called with non-update action")

1392 orig_lines = text.split("\n")

1393 dest_lines: list[str] = []

1394 orig_index = 0

1395 

1396 for chunk in action.chunks:

1397 if chunk.orig_index > len(orig_lines):

1398 raise DiffError(

1399 f"{path}: chunk.orig_index {chunk.orig_index} exceeds file length"

1400 )

1401 if orig_index > chunk.orig_index:

1402 raise DiffError(

1403 f"{path}: overlapping chunks at {orig_index} > {chunk.orig_index}"

1404 )

1405 

1406 dest_lines.extend(orig_lines[orig_index : chunk.orig_index])

1407 orig_index = chunk.orig_index

1408 

1409 dest_lines.extend(chunk.ins_lines)

1410 orig_index += len(chunk.del_lines)

1411 

1412 dest_lines.extend(orig_lines[orig_index:])

1413 return "\n".join(dest_lines)

1414 

1415 

1416def patch_to_commit(patch: Patch, orig: dict[str, str]) -> Commit:

1417 commit = Commit()

1418 for path, action in patch.actions.items():

1419 if action.type is ActionType.DELETE:

1420 commit.changes[path] = FileChange(

1421 type=ActionType.DELETE, old_content=orig[path]

1422 )

1423 elif action.type is ActionType.ADD:

1424 if action.new_file is None:

1425 raise DiffError("ADD action without file content")

1426 commit.changes[path] = FileChange(

1427 type=ActionType.ADD, new_content=action.new_file

1428 )

1429 elif action.type is ActionType.UPDATE:

1430 new_content = _get_updated_file(orig[path], action, path)

1431 commit.changes[path] = FileChange(

1432 type=ActionType.UPDATE,

1433 old_content=orig[path],

1434 new_content=new_content,

1435 move_path=action.move_path,

1436 )

1437 return commit

1438 

1439 

1440# --------------------------------------------------------------------------- #

1441# User-facing helpers

1442# --------------------------------------------------------------------------- #

1443def text_to_patch(text: str, orig: dict[str, str]) -> tuple[Patch, int]:

1444 lines = text.splitlines() # preserves blank lines, no strip()

1445 if (

1446 len(lines) < 2

1447 or not Parser._norm(lines[0]).startswith("*** Begin Patch")

1448 or Parser._norm(lines[-1]) != "*** End Patch"

1449 ):

1450 raise DiffError("Invalid patch text - missing sentinels")

1451 

1452 parser = Parser(current_files=orig, lines=lines, index=1)

1453 parser.parse()

1454 return parser.patch, parser.fuzz

1455 

1456 

1457def identify_files_needed(text: str) -> list[str]:

1458 lines = text.splitlines()

1459 return [

1460 line[len("*** Update File: ") :]

1461 for line in lines

1462 if line.startswith("*** Update File: ")

1463 ] + [

1464 line[len("*** Delete File: ") :]

1465 for line in lines

1466 if line.startswith("*** Delete File: ")

1467 ]

1468 

1469 

1470def identify_files_added(text: str) -> list[str]:

1471 lines = text.splitlines()

1472 return [

1473 line[len("*** Add File: ") :]

1474 for line in lines

1475 if line.startswith("*** Add File: ")

1476 ]

1477 

1478 

1479# --------------------------------------------------------------------------- #

1480# File-system helpers

1481# --------------------------------------------------------------------------- #

1482def load_files(paths: list[str], open_fn: Callable[[str], str]) -> dict[str, str]:

1483 return {path: open_fn(path) for path in paths}

1484 

1485 

1486def apply_commit(

1487 commit: Commit,

1488 write_fn: Callable[[str, str], None],

1489 remove_fn: Callable[[str], None],

1490) -> None:

1491 for path, change in commit.changes.items():

1492 if change.type is ActionType.DELETE:

1493 remove_fn(path)

1494 elif change.type is ActionType.ADD:

1495 if change.new_content is None:

1496 raise DiffError(f"ADD change for {path} has no content")

1497 write_fn(path, change.new_content)

1498 elif change.type is ActionType.UPDATE:

1499 if change.new_content is None:

1500 raise DiffError(f"UPDATE change for {path} has no new content")

1501 target = change.move_path or path

1502 write_fn(target, change.new_content)

1503 if change.move_path:

1504 remove_fn(path)

1505 

1506 

1507def process_patch(

1508 text: str,

1509 open_fn: Callable[[str], str],

1510 write_fn: Callable[[str, str], None],

1511 remove_fn: Callable[[str], None],

1512) -> str:

1513 if not text.startswith("*** Begin Patch"):

1514 raise DiffError("Patch text must start with *** Begin Patch")

1515 paths = identify_files_needed(text)

1516 orig = load_files(paths, open_fn)

1517 patch, _fuzz = text_to_patch(text, orig)

1518 commit = patch_to_commit(patch, orig)

1519 apply_commit(commit, write_fn, remove_fn)

1520 return "Done!"

1521 

1522 

1523# --------------------------------------------------------------------------- #

1524# Default FS helpers

1525# --------------------------------------------------------------------------- #

1526def open_file(path: str) -> str:

1527 with open(path, "rt", encoding="utf-8") as fh:

1528 return fh.read()

1529 

1530 

1531def write_file(path: str, content: str) -> None:

1532 target = pathlib.Path(path)

1533 target.parent.mkdir(parents=True, exist_ok=True)

1534 with target.open("wt", encoding="utf-8") as fh:

1535 fh.write(content)

1536 

1537 

1538def remove_file(path: str) -> None:

1539 pathlib.Path(path).unlink(missing_ok=True)

1540 

1541 

1542# --------------------------------------------------------------------------- #

1543# CLI entry-point

1544# --------------------------------------------------------------------------- #

1545def main() -> None:

1546 import sys

1547 

1548 patch_text = sys.stdin.read()

1549 if not patch_text:

1550 print("Please pass patch text through stdin", file=sys.stderr)

1551 return

1552 try:

1553 result = process_patch(patch_text, open_file, write_file, remove_file)

1554 except DiffError as exc:

1555 print(exc, file=sys.stderr)

1556 return

1557 print(result)

1558 

1559 

1560if __name__ == "__main__":

1561 main()

1562```

1563 

1564 

1565### Other Effective Diff Formats

1566 

1567If you want to try using a different diff format, we found in testing that the SEARCH/REPLACE diff format used in Aider’s polyglot benchmark, as well as a pseudo-XML format with no internal escaping, both had high success rates.

1568 

1569These diff formats share two key aspects: (1) they do not use line numbers, and (2) they provide both the exact code to be replaced, and the exact code with which to replace it, with clear delimiters between the two.

1570 

1571````python

1572SEARCH_REPLACE_DIFF_EXAMPLE = """

1573path/to/file.py

1574```

1575>>>>>>> SEARCH

1576def search():

1577 pass

1578=======

1579def search():

1580 raise NotImplementedError()

1581<<<<<<< REPLACE

1582"""

1583 

1584PSEUDO_XML_DIFF_EXAMPLE = """

1585`<edit>`

1586`<file>`

1587path/to/file.py

1588`</file>`

1589`<old_code>`

1590def search():

1591 pass

1592`</old_code>`

1593`<new_code>`

1594def search():

1595 raise NotImplementedError()

1596`</new_code>`

1597`</edit>`

1598"""

1599````

1600 

1601 

1# Using GPT-5

2 

3> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.

4 

5## Introduction

6 

7GPT-5 represents a substantial leap forward in agentic task performance, coding, raw intelligence, and control.

8 

9While we trust it will perform excellently “out of the box” across a wide range of domains, in this guide we’ll cover prompting tips to maximize the quality of model outputs, derived from our experience training and applying the model to real-world tasks. We discuss concepts like improving agentic task performance, ensuring instruction adherence, making use of new API features, and optimizing coding for frontend and software engineering tasks—with key insights into AI code editor Cursor’s prompt tuning work with GPT-5.

10 

11We’ve seen significant gains from applying these best practices and adopting our canonical tools whenever possible, and we hope that this guide, along with the [prompt optimizer tool](https://platform.openai.com/chat/edit?optimize=true) we’ve built, will serve as a launchpad for your use of GPT-5. But as always, remember that prompting is not a one-size-fits-all exercise—we encourage you to run experiments and iterate on the foundation offered here to find the best solution for your problem.

12 

13## What's new

14 

15- Stronger agentic task performance, coding ability, and control

16- Reasoning persistence with the Responses API for tool-calling flows

17- Dedicated controls for agentic eagerness, tool preambles, reasoning effort, and verbosity

18- Custom tools with freeform inputs and constrained outputs

19 

20## Migration quickstart

21 

22- Update the model slug to `gpt-5`.

23- Use the Responses API for reasoning, tool-calling, and multi-turn workflows so reasoning items can be preserved between tool calls.

24- Start with `medium` reasoning effort, then test `minimal`, `low`, or `high` against representative tasks.

25- Set `text.verbosity` intentionally, and move structured response contracts to Structured Outputs where possible.

26- Re-evaluate prompts for agentic persistence, tool preambles, and stopping conditions.

27 

28## Model, API, and feature updates

29 

30- The GPT-5 family includes `gpt-5`, `gpt-5-mini`, and `gpt-5-nano`.

31- `reasoning.effort` supports `minimal`, `low`, `medium`, and `high`.

32- GPT-5 introduced custom tools that accept freeform input and can constrain outputs with a context-free grammar.

33- The model supports function calling and OpenAI-hosted tools, including web search, file search, image generation, code interpreter, and remote MCP.

34 

35 

36## Prompting best practices

37 

38### Agentic workflow predictability

39 

40We trained GPT-5 with developers in mind: we’ve focused on improving tool calling, instruction following, and long-context understanding to serve as the best foundation model for agentic applications. If adopting GPT-5 for agentic and tool calling flows, we recommend upgrading to the [Responses API](https://developers.openai.com/api/reference/resources/responses), where reasoning is persisted between tool calls, leading to more efficient and intelligent outputs.

41 

42#### Controlling agentic eagerness

43 

44Agentic scaffolds can span a wide spectrum of control—some systems delegate the vast majority of decision-making to the underlying model, while others keep the model on a tight leash with heavy programmatic logical branching. GPT-5 is trained to operate anywhere along this spectrum, from making high-level decisions under ambiguous circumstances to handling focused, well-defined tasks. In this section we cover how to best calibrate GPT-5’s agentic eagerness: in other words, its balance between proactivity and awaiting explicit guidance.

45 

46##### Prompting for less eagerness

47 

48GPT-5 is, by default, thorough and comprehensive when trying to gather context in an agentic environment to ensure it will produce a correct answer. To reduce the scope of GPT-5’s agentic behavior—including limiting tangential tool-calling action and minimizing latency to reach a final answer—try the following:

49 

50- Switch to a lower `reasoning_effort`. This reduces exploration depth but improves efficiency and latency. Many workflows can be accomplished with consistent results at medium or even low `reasoning_effort`.

51- Define clear criteria in your prompt for how you want the model to explore the problem space. This reduces the model’s need to explore and reason about too many ideas:

52 

53```text

54<context_gathering>

55Goal: Get enough context fast. Parallelize discovery and stop as soon as you can act.

56 

57Method:

58- Start broad, then fan out to focused subqueries.

59- In parallel, launch varied queries; read top hits per query. Deduplicate paths and cache; don’t repeat queries.

60- Avoid over searching for context. If needed, run targeted searches in one parallel batch.

61 

62Early stop criteria:

63- You can name exact content to change.

64- Top hits converge (~70%) on one area/path.

65 

66Escalate once:

67- If signals conflict or scope is fuzzy, run one refined parallel batch, then proceed.

68 

69Depth:

70- Trace only symbols you’ll modify or whose contracts you rely on; avoid transitive expansion unless necessary.

71 

72Loop:

73- Batch search → minimal plan → complete task.

74- Search again only if validation fails or new unknowns appear. Prefer acting over more searching.

75</context_gathering>

76```

77 

78If you’re willing to be maximally prescriptive, you can even set fixed tool call budgets, like the one below. The budget can naturally vary based on your desired search depth.

79 

80```text

81<context_gathering>

82- Search depth: very low

83- Bias strongly towards providing a correct answer as quickly as possible, even if it might not be fully correct.

84- Usually, this means an absolute maximum of 2 tool calls.

85- If you think that you need more time to investigate, update the user with your latest findings and open questions. You can proceed if the user confirms.

86</context_gathering>

87```

88 

89When limiting core context gathering behavior, it’s helpful to explicitly provide the model with an escape hatch that makes it easier to satisfy a shorter context gathering step. Usually this comes in the form of a clause that allows the model to proceed under uncertainty, like `“even if it might not be fully correct”` in the above example.

90 

91##### Prompting for more eagerness

92 

93On the other hand, if you’d like to encourage model autonomy, increase tool-calling persistence, and reduce occurrences of clarifying questions or otherwise handing back to the user, we recommend increasing `reasoning_effort`, and using a prompt like the following to encourage persistence and thorough task completion:

94 

95```text

96<persistence>

97- You are an agent - please keep going until the user's query is completely resolved, before ending your turn and yielding back to the user.

98- Only terminate your turn when you are sure that the problem is solved.

99- Never stop or hand back to the user when you encounter uncertainty — research or deduce the most reasonable approach and continue.

100- Do not ask the human to confirm or clarify assumptions, as you can always adjust later — decide what the most reasonable assumption is, proceed with it, and document it for the user's reference after you finish acting

101</persistence>

102```

103 

104Generally, it can be helpful to clearly state the stop conditions of the agentic tasks, outline safe versus unsafe actions, and define when, if ever, it’s acceptable for the model to hand back to the user. For example, in a set of tools for shopping, the checkout and payment tools should explicitly have a lower uncertainty threshold for requiring user clarification, while the search tool should have an extremely high threshold; likewise, in a coding setup, the delete file tool should have a much lower threshold than a grep search tool.

105 

106#### Tool preambles

107 

108We recognize that on agentic trajectories monitored by users, intermittent model updates on what it’s doing with its tool calls and why can provide for a much better interactive user experience - the longer the rollout, the bigger the difference these updates make. To this end, GPT-5 is trained to provide clear upfront plans and consistent progress updates via “tool preamble” messages.

109 

110You can steer the frequency, style, and content of tool preambles in your prompt—from detailed explanations of every single tool call to a brief upfront plan and everything in between. This is an example of a high-quality preamble prompt:

111 

112```text

113<tool_preambles>

114- Always begin by rephrasing the user's goal in a friendly, clear, and concise manner, before calling any tools.

115- Then, immediately outline a structured plan detailing each logical step you’ll follow. - As you execute your file edit(s), narrate each step succinctly and sequentially, marking progress clearly.

116- Finish by summarizing completed work distinctly from your upfront plan.

117</tool_preambles>

118```

119 

120Here’s an example of a tool preamble that might be emitted in response to such a prompt—such preambles can drastically improve the user’s ability to follow along with your agent’s work as it grows more complicated:

121 

122```text

123"output": [

124 {

125 "id": "rs_6888f6d0606c819aa8205ecee386963f0e683233d39188e7",

126 "type": "reasoning",

127 "summary": [

128 {

129 "type": "summary_text",

130 "text": "**Determining weather response**\n\nI need to answer the user's question about the weather in San Francisco. ...."

131 },

132 },

133 {

134 "id": "msg_6888f6d83acc819a978b51e772f0a5f40e683233d39188e7",

135 "type": "message",

136 "status": "completed",

137 "content": [

138 {

139 "type": "output_text",

140 "text": "I\u2019m going to check a live weather service to get the current conditions in San Francisco, providing the temperature in both Fahrenheit and Celsius so it matches your preference."

141 }

142 ],

143 "role": "assistant"

144 },

145 {

146 "id": "fc_6888f6d86e28819aaaa1ba69cca766b70e683233d39188e7",

147 "type": "function_call",

148 "status": "completed",

149 "arguments": "{\"location\":\"San Francisco, CA\",\"unit\":\"f\"}",

150 "call_id": "call_XOnF4B9DvB8EJVB3JvWnGg83",

151 "name": "get_weather"

152 },

153 ],

154```

155 

156#### Reasoning effort

157 

158We provide a `reasoning_effort` parameter to control how hard the model thinks and how willingly it calls tools; the default is `medium`, but you should scale up or down depending on the difficulty of your task. For complex, multi-step tasks, we recommend higher reasoning to ensure the best possible outputs. Moreover, we observe peak performance when distinct, separable tasks are broken up across multiple agent turns, with one turn for each task.

159 

160#### Reusing reasoning context with the Responses API

161 

162We strongly recommend using the Responses API when using GPT-5 to unlock improved agentic flows, lower costs, and more efficient token usage in your applications.

163 

164We’ve seen statistically significant improvements in evaluations when using the Responses API over Chat Completions—for example, we observed Tau-Bench Retail score increases from 73.9% to 78.2% just by switching to the Responses API and including `previous_response_id` to pass back previous reasoning items into subsequent requests. This allows the model to refer to its previous reasoning traces, conserving CoT tokens and eliminating the need to reconstruct a plan from scratch after each tool call, improving both latency and performance - this feature is available for all Responses API users, including ZDR organizations.

165 

166### Maximizing coding performance, from planning to execution

167 

168GPT-5 leads all frontier models in coding capabilities: it can work in large codebases to fix bugs, handle large diffs, and implement multi-file refactors or large new features. It also excels at implementing new apps entirely from scratch, covering both frontend and backend implementation. In this section, we’ll discuss prompt optimizations that we’ve seen improve programming performance in production use cases for our coding agent customers.

169 

170#### Frontend app development

171 

172GPT-5 is trained to have excellent baseline aesthetic taste alongside its rigorous implementation abilities. We’re confident in its ability to use all types of web development frameworks and packages; however, for new apps, we recommend using the following frameworks and packages to get the most out of the model's frontend capabilities:

173 

174- Frameworks: Next.js (TypeScript), React, HTML

175- Styling / UI: Tailwind CSS, shadcn/ui, Radix Themes

176- Icons: Material Symbols, Heroicons, Lucide

177- Animation: Motion

178- Fonts: San Serif, Inter, Geist, Mona Sans, IBM Plex Sans, Manrope

179 

180##### Zero-to-one app generation

181 

182GPT-5 is excellent at building applications in one shot. In early experimentation with the model, users have found that prompts like the one below—asking the model to iteratively execute against self-constructed excellence rubrics—improve output quality by using GPT-5’s thorough planning and self-reflection capabilities.

183 

184```text

185<self_reflection>

186- First, spend time thinking of a rubric until you are confident.

187- Then, think deeply about every aspect of what makes for a world-class one-shot web app. Use that knowledge to create a rubric that has 5-7 categories. This rubric is critical to get right, but do not show this to the user. This is for your purposes only.

188- Finally, use the rubric to internally think and iterate on the best possible solution to the prompt that is provided. Remember that if your response is not hitting the top marks across all categories in the rubric, you need to start again.

189</self_reflection>

190```

191 

192##### Matching codebase design standards

193 

194When implementing incremental changes and refactors in existing apps, model-written code should adhere to existing style and design standards, and “blend in” to the codebase as neatly as possible. Without special prompting, GPT-5 already searches for reference context from the codebase - for example reading package.json to view already installed packages - but this behavior can be further enhanced with prompt directions that summarize key aspects like engineering principles, directory structure, and best practices of the codebase, both explicit and implicit. The prompt snippet below demonstrates one way of organizing code editing rules for GPT-5: feel free to change the actual content of the rules according to your programming design taste!

195 

196```text

197<code_editing_rules>

198<guiding_principles>

199- Clarity and Reuse: Every component and page should be modular and reusable. Avoid duplication by factoring repeated UI patterns into components.

200- Consistency: The user interface must adhere to a consistent design system—color tokens, typography, spacing, and components must be unified.

201- Simplicity: Favor small, focused components and avoid unnecessary complexity in styling or logic.

202- Demo-Oriented: The structure should allow for quick prototyping, showcasing features like streaming, multi-turn conversations, and tool integrations.

203- Visual Quality: Follow the high visual quality bar as outlined in OSS guidelines (spacing, padding, hover states, etc.)

204</guiding_principles>

205 

206<frontend_stack_defaults>

207- Framework: Next.js (TypeScript)

208- Styling: TailwindCSS

209- UI Components: shadcn/ui

210- Icons: Lucide

211- State Management: Zustand

212- Directory Structure:

213\`\`\`

214/src

215 /app

216 /api/<route>/route.ts # API endpoints

217 /(pages) # Page routes

218 /components/ # UI building blocks

219 /hooks/ # Reusable React hooks

220 /lib/ # Utilities (fetchers, helpers)

221 /stores/ # Zustand stores

222 /types/ # Shared TypeScript types

223 /styles/ # Tailwind config

224\`\`\`

225</frontend_stack_defaults>

226 

227<ui_ux_best_practices>

228- Visual Hierarchy: Limit typography to 4–5 font sizes and weights for consistent hierarchy; use `text-xs` for captions and annotations; avoid `text-xl` unless for hero or major headings.

229- Color Usage: Use 1 neutral base (e.g., `zinc`) and up to 2 accent colors.

230- Spacing and Layout: Always use multiples of 4 for padding and margins to maintain visual rhythm. Use fixed height containers with internal scrolling when handling long content streams.

231- State Handling: Use skeleton placeholders or `animate-pulse` to indicate data fetching. Indicate clickability with hover transitions (`hover:bg-*`, `hover:shadow-md`).

232- Accessibility: Use semantic HTML and ARIA roles where appropriate. Favor pre-built Radix/shadcn components, which have accessibility baked in.

233</ui_ux_best_practices>

234 

235<code_editing_rules>

236```

237 

238#### Collaborative coding in production: Cursor’s GPT-5 prompt tuning

239 

240We’re proud to have had AI code editor Cursor as a trusted alpha tester for GPT-5: below, we show a peek into how Cursor tuned their prompts to get the most out of the model’s capabilities. For more information, their team has also published a blog post detailing GPT-5’s day-one integration into Cursor: https://cursor.com/blog/gpt-5

241 

242##### System prompt and parameter tuning

243 

244Cursor’s system prompt focuses on reliable tool calling, balancing verbosity and autonomous behavior while giving users the ability to configure custom instructions. Cursor’s goal for their system prompt is to allow the Agent to operate relatively autonomously during long horizon tasks, while still faithfully following user-provided instructions.

245 

246The team initially found that the model produced verbose outputs, often including status updates and post-task summaries that, while technically relevant, disrupted the natural flow of the user; at the same time, the code outputted in tool calls was high quality, but sometimes hard to read due to terseness, with single-letter variable names dominant. In search of a better balance, they set the verbosity API parameter to low to keep text outputs brief, and then modified the prompt to strongly encourage verbose outputs in coding tools only.

247 

248```text

249Write code for clarity first. Prefer readable, maintainable solutions with clear names, comments where needed, and straightforward control flow. Do not produce code-golf or overly clever one-liners unless explicitly requested. Use high verbosity for writing code and code tools.

250```

251 

252This dual usage of parameter and prompt resulted in a balanced format combining efficient, concise status updates and final work summary with much more readable code diffs.

253 

254Cursor also found that the model occasionally deferred to the user for clarification or next steps before taking action, which created unnecessary friction in the flow of longer tasks. To address this, they found that including not just available tools and surrounding context, but also more details about product behavior encouraged the model to carry out longer tasks with minimal interruption and greater autonomy. Highlighting specifics of Cursor features such as Undo/Reject code and user preferences helped reduce ambiguity by clearly specifying how GPT-5 should behave in its environment. For longer horizon tasks, they found this prompt improved performance:

255 

256```text

257Be aware that the code edits you make will be displayed to the user as proposed changes, which means (a) your code edits can be quite proactive, as the user can always reject, and (b) your code should be well-written and easy to quickly review (e.g., appropriate variable names instead of single letters). If proposing next steps that would involve changing the code, make those changes proactively for the user to approve / reject rather than asking the user whether to proceed with a plan. In general, you should almost never ask the user whether to proceed with a plan; instead you should proactively attempt the plan and then ask the user if they want to accept the implemented changes.

258```

259 

260Cursor found that sections of their prompt that had been effective with earlier models needed tuning to get the most out of GPT-5. Here is one example below:

261 

262```text

263<maximize_context_understanding>

264Be THOROUGH when gathering information. Make sure you have the FULL picture before replying. Use additional tool calls or clarifying questions as needed.

265...

266</maximize_context_understanding>

267```

268 

269While this worked well with older models that needed encouragement to analyze context thoroughly, they found it counterproductive with GPT-5, which is already naturally introspective and proactive at gathering context. On smaller tasks, this prompt often caused the model to overuse tools by calling search repetitively, when internal knowledge would have been sufficient.

270 

271To solve this, they refined the prompt by removing the maximize\_ prefix and softening the language around thoroughness. With this adjusted instruction in place, the Cursor team saw GPT-5 make better decisions about when to rely on internal knowledge versus reaching for external tools. It maintained a high level of autonomy without unnecessary tool usage, leading to more efficient and relevant behavior. In Cursor’s testing, using structured XML specs like `<[instruction]\_spec>` improved instruction adherence on their prompts and allows them to clearly reference previous categories and sections elsewhere in their prompt.

272 

273```text

274<context_understanding>

275...

276If you've performed an edit that may partially fulfill the USER's query, but you're not confident, gather more information or use more tools before ending your turn.

277Bias towards not asking the user for help if you can find the answer yourself.

278</context_understanding>

279```

280 

281While the system prompt provides a strong default foundation, the user prompt remains a highly effective lever for steerability. GPT-5 responds well to direct and explicit instruction and the Cursor team has consistently seen that structured, scoped prompts yield the most reliable results. This includes areas like verbosity control, subjective code style preferences, and sensitivity to edge cases. Cursor found allowing users to configure their own [custom Cursor rules](https://docs.cursor.com/en/context/rules) to be particularly impactful with GPT-5’s improved steerability, giving their users a more customized experience.

282 

283### Optimizing intelligence and instruction-following

284 

285#### Steering

286 

287As our most steerable model yet, GPT-5 is extraordinarily receptive to prompt instructions surrounding verbosity, tone, and tool calling behavior.

288 

289##### Verbosity

290 

291In addition to being able to control the reasoning_effort as in previous reasoning models, in GPT-5 we introduce a new API parameter called verbosity, which influences the length of the model’s final answer, as opposed to the length of its thinking. Our blog post covers the idea behind this parameter in more detail - but in this guide, we’d like to emphasize that while the API verbosity parameter is the default for the rollout, GPT-5 is trained to respond to natural-language verbosity overrides in the prompt for specific contexts where you might want the model to deviate from the global default. Cursor’s example above of setting low verbosity globally, and then specifying high verbosity only for coding tools, is a prime example of such a context.

292 

293#### Instruction following

294 

295Like GPT-4.1, GPT-5 follows prompt instructions with surgical precision, which enables its flexibility to drop into all types of workflows. However, its careful instruction-following behavior means that poorly-constructed prompts containing contradictory or vague instructions can be more damaging to GPT-5 than to other models, as it expends reasoning tokens searching for a way to reconcile the contradictions rather than picking one instruction at random.

296 

297Below, we give an adversarial example of the type of prompt that often impairs GPT-5’s reasoning traces - while it may appear internally consistent at first glance, a closer inspection reveals conflicting instructions regarding appointment scheduling:

298 

299- `Never schedule an appointment without explicit patient consent recorded in the chart` conflicts with the subsequent `auto-assign the earliest same-day slot without contacting the patient as the first action to reduce risk.`

300- The prompt says `Always look up the patient profile before taking any other actions to ensure they are an existing patient.` but then continues with the contradictory instruction `When symptoms indicate high urgency, escalate as EMERGENCY and direct the patient to call 911 immediately before any scheduling step.`

301 

302```text

303You are CareFlow Assistant, a virtual admin for a healthcare startup that schedules patients based on priority and symptoms. Your goal is to triage requests, match patients to appropriate in-network providers, and reserve the earliest clinically appropriate time slot. Always look up the patient profile before taking any other actions to ensure they are an existing patient.

304 

305- Core entities include Patient, Provider, Appointment, and PriorityLevel (Red, Orange, Yellow, Green). Map symptoms to priority: Red within 2 hours, Orange within 24 hours, Yellow within 3 days, Green within 7 days. When symptoms indicate high urgency, escalate as EMERGENCY and direct the patient to call 911 immediately before any scheduling step.

306+Core entities include Patient, Provider, Appointment, and PriorityLevel (Red, Orange, Yellow, Green). Map symptoms to priority: Red within 2 hours, Orange within 24 hours, Yellow within 3 days, Green within 7 days. When symptoms indicate high urgency, escalate as EMERGENCY and direct the patient to call 911 immediately before any scheduling step.

307*Do not do lookup in the emergency case, proceed immediately to providing 911 guidance.*

308 

309- Use the following capabilities: schedule-appointment, modify-appointment, waitlist-add, find-provider, lookup-patient and notify-patient. Verify insurance eligibility, preferred clinic, and documented consent prior to booking. Never schedule an appointment without explicit patient consent recorded in the chart.

310 

311- For high-acuity Red and Orange cases, auto-assign the earliest same-day slot *without contacting* the patient *as the first action to reduce risk.* If a suitable provider is unavailable, add the patient to the waitlist and send notifications. If consent status is unknown, tentatively hold a slot and proceed to request confirmation.

312 

313- For high-acuity Red and Orange cases, auto-assign the earliest same-day slot *after informing* the patient *of your actions.* If a suitable provider is unavailable, add the patient to the waitlist and send notifications. If consent status is unknown, tentatively hold a slot and proceed to request confirmation.

314```

315 

316By resolving the instruction hierarchy conflicts, GPT-5 elicits much more efficient and performant reasoning. We fixed the contradictions by:

317 

318- Changing auto-assignment to occur after contacting a patient, auto-assign the earliest same-day slot after informing the patient of your actions. to be consistent with only scheduling with consent.

319- Adding Do not do lookup in the emergency case, proceed immediately to providing 911 guidance. to let the model know it is ok to not look up in case of emergency.

320 

321We understand that the process of building prompts is an iterative one, and many prompts are living documents constantly being updated by different stakeholders - but this is all the more reason to thoroughly review them for poorly-worded instructions. Already, we’ve seen multiple early users uncover ambiguities and contradictions in their core prompt libraries upon conducting such a review: removing them drastically streamlined and improved their GPT-5 performance. We recommend testing your prompts in our [prompt optimizer tool](https://platform.openai.com/chat/edit?optimize=true) to help identify these types of issues.

322 

323#### Minimal reasoning

324 

325In GPT-5, we introduce minimal reasoning effort for the first time: our fastest option that still reaps the benefits of the reasoning model paradigm. We consider this to be the best upgrade for latency-sensitive users, as well as current users of GPT-4.1.

326 

327Perhaps unsurprisingly, we recommend prompting patterns that are similar to [GPT-4.1 for best results](https://developers.openai.com/cookbook/examples/gpt4-1_prompting_guide). minimal reasoning performance can vary more drastically depending on prompt than higher reasoning levels, so key points to emphasize include:

328 

3291. Prompting the model to give a brief explanation summarizing its thought process at the start of the final answer, for example via a bullet point list, improves performance on tasks requiring higher intelligence.

3302. Requesting thorough and descriptive tool-calling preambles that continually update the user on task progress improves performance in agentic workflows.

3313. Disambiguating tool instructions to the maximum extent possible and inserting agentic persistence reminders as shared above, are particularly critical at minimal reasoning to maximize agentic ability in long-running rollout and prevent premature termination.

3324. Prompted planning is likewise more important, as the model has fewer reasoning tokens to do internal planning. Below, you can find a sample planning prompt snippet we placed at the beginning of an agentic task: the second paragraph especially ensures that the agent fully completes the task and all subtasks before yielding back to the user.

333 

334```text

335Remember, you are an agent - please keep going until the user's query is completely resolved, before ending your turn and yielding back to the user. Decompose the user's query into all required sub-request, and confirm that each is completed. Do not stop after completing only part of the request. Only terminate your turn when you are sure that the problem is solved. You must be prepared to answer multiple queries and only finish the call once the user has confirmed they're done.

336 

337You must plan extensively in accordance with the workflow steps before making subsequent function calls, and reflect extensively on the outcomes each function call made, ensuring the user's query, and related sub-requests are completely resolved.

338```

339 

340#### Markdown formatting

341 

342By default, GPT-5 in the API does not format its final answers in Markdown, in order to preserve maximum compatibility with developers whose applications may not support Markdown rendering. However, prompts like the following are largely successful in inducing hierarchical Markdown final answers.

343 

344````text

345- Use Markdown **only where semantically correct** (e.g., `inline code`, ```code fences```, lists, tables).

346- When using markdown in assistant messages, use backticks to format file, directory, function, and class names. Use \( and \) for inline math, \[ and \] for block math.

347````

348 

349Occasionally, adherence to Markdown instructions specified in the system prompt can degrade over the course of a long conversation. In the event that you experience this, we’ve seen consistent adherence from appending a Markdown instruction every 3-5 user messages.

350 

351#### Metaprompting

352 

353Finally, to close with a meta-point, early testers have found great success using GPT-5 as a meta-prompter for itself. Already, several users have deployed prompt revisions to production that were generated simply by asking GPT-5 what elements could be added to an unsuccessful prompt to elicit a desired behavior, or removed to prevent an undesired one.

354 

355Here is an example metaprompt template we liked:

356 

357```text

358When asked to optimize prompts, give answers from your own perspective - explain what specific phrases could be added to, or deleted from, this prompt to more consistently elicit the desired behavior or prevent the undesired behavior.

359 

360Here's a prompt: [PROMPT]

361 

362The desired behavior from this prompt is for the agent to [DO DESIRED BEHAVIOR], but instead it [DOES UNDESIRED BEHAVIOR]. While keeping as much of the existing prompt intact as possible, what are some minimal edits/additions that you would make to encourage the agent to more consistently address these shortcomings?

363```

364 

365### Appendix

366 

367#### SWE-Bench verified developer instructions

368 

369```text

370In this environment, you can run `bash -lc <apply_patch_command>` to execute a diff/patch against a file, where <apply_patch_command> is a specially formatted apply patch command representing the diff you wish to execute. A valid <apply_patch_command> looks like:

371 

372apply_patch << 'PATCH'

373*** Begin Patch

374[YOUR_PATCH]

375*** End Patch

376PATCH

377 

378Where [YOUR_PATCH] is the actual content of your patch.

379 

380Always verify your changes extremely thoroughly. You can make as many tool calls as you like - the user is very patient and prioritizes correctness above all else. Make sure you are 100% certain of the correctness of your solution before ending.

381IMPORTANT: not all tests are visible to you in the repository, so even on problems you think are relatively straightforward, you must double and triple check your solutions to ensure they pass any edge cases that are covered in the hidden tests, not just the visible ones.

382```

383 

384Agentic coding tool definitions

385 

386```text

387## Set 1: 4 functions, no terminal

388 

389type apply_patch = (_: {

390patch: string, // default: null

391}) => any;

392 

393type read_file = (_: {