Source: Prompt engineering guide (OpenAI)
OpenAI's API guide to prompting: message roles, the instructions parameter, Markdown/XML structure, few-shot, prompts-in-code versioning and snapshot pinning.
Contents
- What: official API documentation page
- Publisher: OpenAI
- Date: accessed 2026-11-14
- Original: Prompt engineering
Summary
Covers prompting through the Responses API: the role model (developer, user, assistant), the instructions parameter, how to structure a developer message, few-shot examples, context/RAG, caching-friendly ordering, and how to manage prompts in production (in code, pinned to model snapshots, measured with evals). It also contrasts prompting reasoning models with non-reasoning GPT models.
Key claims
developermessages carry app-developer instructions and outrankusermessages; the guide likens developer messages to a function definition and user messages to its arguments.instructionssets high-level behaviour for one request and overrides conflictinginput; it is not carried forward when chaining withprevious_response_id.- Suggested developer-message layout: Identity, Instructions, Examples, Context (context usually last). Markdown headers mark sections; XML tags delimit documents and can carry attributes.
- Few-shot examples should cover a diverse range of inputs and usually live in the developer message.
- Put reused content at the start of the prompt to benefit from prompt caching.
- Keep production prompts in application code (typed builders, code review, tests, feature-flagged rollout). Reusable prompt objects are being deprecated: creation de-emphasised from 2026-06-03,
v1/promptsshutdown scheduled for 2026-11-30. - Pin production apps to a dated model snapshot (example given:
gpt-4.1-2025-04-14) and use evals to detect behaviour changes across prompt or model versions. - Reasoning models do well with high-level goals; GPT models need explicit, precise steps.