agent-opt
library has a unique strategy, and picking the right one for your specific task will lead to better results, faster.
This cookbook provides a practical comparison and a clear decision guide to help you select the best optimizer for your use case.
Optimizer Comparison at a Glance
This table summarizes the core strategy and ideal use case for each optimizer.Optimizer | Core Strategy | When to Use It |
---|---|---|
Random Search | Broad Exploration | For quick baselines and generating a wide range of initial ideas. |
Bayesian Search | Intelligent Example Selection | When your primary goal is to find the best few-shot examples for your prompt. |
ProTeGi | Error-Driven Debugging | For systematically fixing a good prompt that has specific, identifiable failures. |
Meta-Prompt | Holistic Analysis & Rewrite | For complex reasoning tasks that require a deep, top-to-bottom refinement of the prompt’s logic. |
PromptWizard | Creative Multi-Stage Evolution | For creative tasks or when you want to explore different “thinking styles” in your prompt. |
GEPA | State-of-the-Art Evolutionary Search | For critical, production systems where achieving maximum performance is the top priority. |
A Quick Decision Guide
Follow this decision tree to find the right optimizer for your needs.1. Is your primary goal to optimize the selection of few-shot examples?
BayesianSearchOptimizer
. It’s specifically designed to find the optimal number and combination of examples to include in your prompt.2. No, I'm optimizing the main instruction. Do you just need a quick baseline or some initial ideas?
RandomSearchOptimizer
. It’s the fastest and simplest way to get a baseline and see if improvement is possible.3. No, I need a more advanced, iterative refinement. Does your prompt have specific, known failure modes?
ProTeGi
. It’s designed to function like a debugger, analyzing failures and applying targeted “textual gradient” fixes.4. No, my prompt needs a more holistic rewrite. Is it for a complex reasoning task?
MetaPromptOptimizer
. It excels at deep analysis, forming a hypothesis about your prompt’s core problem, and rewriting it from the ground up.5. Is this for a critical, production-grade application where you need the absolute best performance and have a larger budget?
GEPAOptimizer
. It’s an adapter for a state-of-the-art evolutionary algorithm that provides the most powerful (but also most computationally intensive) optimization.ProTeGi
is an excellent and powerful general-purpose choice for improving an existing prompt.Combining Optimizers for Advanced Workflows
You don’t have to stick to just one optimizer. A powerful pattern is to use them sequentially in a “funnel” approach to find the best possible prompt.Stage 1: Broad Exploration with Random Search
Stage 1: Broad Exploration with Random Search
RandomSearchOptimizer
to quickly generate 10-15 diverse prompt ideas and get a rough sense of which direction is most promising. This is fast and cheap.Stage 2: Deep Refinement with ProTeGi or Meta-Prompt
Stage 2: Deep Refinement with ProTeGi or Meta-Prompt
initial_prompts
into a more powerful refinement optimizer like ProTeGi
or MetaPromptOptimizer
. This focuses your expensive, deep analysis only on the most promising candidates.Stage 3: Few-Shot Enhancement with Bayesian Search
Stage 3: Few-Shot Enhancement with Bayesian Search
BayesianSearchOptimizer
to find the optimal set of examples to add to it.