Best Practices for Prompt Optimization with GPT-5's New Optimizer

The GPT-S Prompt Optimizer uses a multi-agent workflow to automatically detect logical contradictions, format ambiguities, and few-shot inconsistencies in developer prompts, then rewrites them for optimal performance on GPT-5 models.

The openai/openai-cookbook repository now includes a production-ready implementation of this optimization system in examples/Optimize_Prompts.ipynb. This guide covers prompt optimization with GPT-5 by leveraging a structured validation pipeline that catches common errors before inference, ensuring your prompts align with best practices for the GPT-S architecture.

Architecture of the Multi-Agent Optimizer

The optimizer is built on the openai-agents SDK and implements a specialized agent pattern where each validator focuses on a single failure mode. According to the source code in examples/Optimize_Prompts.ipynb, the system uses gpt-4.1 as the underlying model for all validation agents and enforces strict type safety through Pydantic data models including Issues, FewShotIssues, MessagesOutput, and DevRewriteOutput.

The Three Core Validation Agents

The workflow instantiates three specialized agents with constrained system prompts:

• dev_contradiction_checker – Scans developer prompts for logical conflicts, such as simultaneous instructions to "always answer in English" and "never answer in English"【1†L55-L63】.
• format_checker – Detects when prompts expect structured outputs (JSON, CSV, Markdown) but omit schema definitions, field ordering, or error-handling protocols【1†L31-L38】.
• fewshot_consistency_checker – Compares the rules stated in the developer prompt against provided few-shot examples, flagging mismatches like plain-text responses when JSON is required【1†L59-L70】.

Parallel Execution and Conditional Rewriting

The core orchestration happens in optimize_prompt_parallel, which launches all three checkers concurrently using Runner.run (async). The function gathers results and conditionally invokes the dev_rewriter and fewshot_rewriter agents only when issues are present, preserving latency for well-formed prompts. The entire pipeline is wrapped in trace("optimize_prompt_workflow") to enable step-by-step visualization in the OpenAI monitoring UI【1†L34-L36】.

Critical Issues Detected During Optimization

Understanding what the optimizer catches helps you write better initial prompts. The system targets three specific categories of errors that degrade GPT-5 performance.

Logical Contradictions in Instructions

The optimizer identifies mutually exclusive directives within the same prompt. For example, requiring both {"error":"FIELD_MISSING"} and null for missing fields constitutes a contradiction that confuses the model. The dev_contradiction_checker flags these conflicts so the dev_rewriter can resolve them into consistent logic【1†L55-L63】.

Missing or Ambiguous Format Specifications

When prompts request structured data without explicit schemas, the format_checker triggers. It validates that JSON outputs include key definitions, that CSV formats specify column headers, and that error states (like CLAIM_TOO_LARGE) have documented handling procedures【1†L31-L38】.

Few-Shot Example Misalignment

The fewshot_consistency_checker validates that every turn in your few-shot conversations adheres to the developer prompt's rules. If your instructions demand JSON with specific keys (city, population) but your assistant examples return plain text like "New York City", the optimizer flags the inconsistency and the fewshot_rewriter corrects the examples【1†L59-L70】.

Implementing the Optimization Workflow

Below are practical implementations using the optimize_prompt_parallel function from examples/Optimize_Prompts.ipynb. These snippets require the openai-agents SDK and an OPENAI_API_KEY environment variable.

Detecting Contradictory Instructions

from examples.Optimize_Prompts import optimize_prompt_parallel, ChatMessage
import asyncio

async def check_contradiction():
    prompt = """Quick-Start Card — Product Parser

Goal: Digest raw HTML and emit concise JSON.

Rules:
- If any required field is missing, short-circuit with {"error":"FIELD_MISSING"}
- It is also acceptable to output null for missing fields.  # Contradiction!"""

    
    result = await optimize_prompt_parallel(prompt, [])
    print("Issues found:", result["contradiction_issues"])
    print("Optimized prompt:", result["new_developer_message"])

asyncio.run(check_contradiction())

Validating Few-Shot Consistency

async def align_few_shot():
    prompt = "Respond **only** with JSON using keys `city` (string) and `population` (integer)."
    messages = [
        {"role": "user", "content": "Largest US city?"},
        {"role": "assistant", "content": "New York City"},  # Violation: not JSON

        {"role": "user", "content": "Largest UK city?"},
        {"role": "assistant", "content": '{"city":"London","population":9541000}'},
    ]
    
    result = await optimize_prompt_parallel(
        prompt, 
        [ChatMessage(**m) for m in messages]
    )
    
    if result["few_shot_contradiction_issues"]:
        print("Inconsistencies:", result["few_shot_contradiction_issues"])
        print("Corrected examples:", result["new_messages"])

asyncio.run(align_few_shot())

Clarifying Format Specifications

async def fix_format_specs():
    prompt = """Task: Translate patent claims into 200-word lay summaries.

Output should follow a Markdown template:
- A summary section.
- A glossary section.

If the claim exceeds 5kB, respond only with CLAIM_TOO_LARGE."""
    
    result = await optimize_prompt_parallel(prompt, [])
    if result["format_issues"]:
        print("Format problems:", result["format_issues"])
        print(" clarified prompt:", result["new_developer_message"])

asyncio.run(fix_format_specs())

Summary

• The GPT-S Prompt Optimizer in examples/Optimize_Prompts.ipynb implements a multi-agent validation pipeline using gpt-4.1 to check prompts before they reach GPT-5.
• Three specialized agents detect contradictions, format ambiguities, and few-shot misalignments through parallel execution via optimize_prompt_parallel.
• Conditional rewriting ensures rewriters only run when issues are found, maintaining low latency for production workloads.
• Pydantic schemas (Issues, DevRewriteOutput) enforce JSON-structured outputs that can be programmatically validated.
• The system includes traceability through trace("optimize_prompt_workflow") for debugging and monitoring optimization stages.

Frequently Asked Questions

What is the GPT-S Prompt Optimizer?

The GPT-S Prompt Optimizer is an automated validation system within the OpenAI Cookbook that refines developer prompts for GPT-5 models. It uses multiple specialized agents to scan for logical errors, format inconsistencies, and few-shot alignment issues before the prompt enters production inference, significantly reducing error rates in model outputs.

How does the optimizer handle well-written prompts?

When optimize_prompt_parallel detects no issues during the initial parallel scan, it skips the rewriter agents entirely and returns the original prompt unchanged. This conditional execution architecture ensures that valid prompts incur minimal latency overhead from the validation process【1†L34-L42】.

Can I extend the optimizer with custom validation rules?

Yes. The modular architecture in examples/Optimize_Prompts.ipynb allows you to instantiate additional Agent instances from the openai-agents SDK alongside the existing dev_contradiction_checker, format_checker, and fewshot_consistency_checker. Define new Pydantic output schemas (similar to Issues) and add them to the optimize_prompt_parallel orchestration logic to support custom validation such as bias detection or token-budget enforcement.

Which model powers the optimization agents?

According to the source code, the optimization agents—including the checkers and rewriters—run on gpt-4.1. The system was tuned using OpenAI Evals on a golden-set of hand-labeled examples to achieve 100% accuracy in issue detection before being integrated into the GPT-5 prompt optimization workflow【1†L90-L98】.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}