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

> Discover prompt optimization best practices for GPT-5 using the new optimizer. Learn how it detects and corrects inconsistencies for optimal GPT-5 performance.

- Repository: [OpenAI/openai-cookbook](https://github.com/openai/openai-cookbook)
- Tags: best-practices
- Published: 2026-03-02

---

**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

```python
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

```python
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

```python
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】.