GEPA Reflective Optimizer
Optimize prompts, code, agent architectures and configs with LLM reflection and Pareto-efficient evolutionary search.
- Source repo
- gepa-ai/gepa
- Stars
- ★ 7.3k
- Last updated
- 1d ago
- License
- MIT
- Primary language
- Jupyter Notebook
- FA score
- 52/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex · Claude Code · OpenAI API · Claude API
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- Engineers who want to lift a prompt's accuracy on benchmarks like AIME or HotpotQA without running large-scale RL
- Not a fit if
- Tasks without any measurable evaluation metric
- Projects that cannot afford any paid model API spend
- Source review
- 52/100 · Major gaps
What does this agent do, and when should you use it?
GEPA (Genetic-Pareto) is a Python framework for optimizing any system with textual parameters against an evaluation metric — prompts, code, agent architectures, configurations, even SVGs. Instead of collapsing execution traces into a single scalar reward, it has an LLM read full traces (error messages, profiler output, reasoning logs) to diagnose why a candidate failed and propose targeted fixes. The loop selects a candidate from the Pareto frontier, executes a minibatch, reflects, mutates, and accepts improvements, with an optional system-aware merge that combines strengths of two Pareto-optimal candidates. Users plug in their own system through the GEPAAdapter interface (implement evaluate and make_reflective_dataset), and the repo ships DefaultAdapter, ConfidenceAdapter, a DSPy full-program adapter, Generic RAG, MCP, TerminalBench, AnyMaths and LangChain adapters. It is delivered both as a pip library consumed by gepa.optimize / gepa.optimize_anything (or dspy.GEPA) and as an Agent Skill that coding agents such as Claude Code can auto-discover and drive.
GEPA takes a seed candidate (for example a system_prompt string), a training set and a validation set, runs the task LM over samples while capturing traces, then uses a reflection LM to read those traces plus evaluator diagnostics (Actionable Side Information, ASI) and produce mutated candidates. Each iteration picks from the Pareto frontier, runs a minibatch, reflects, mutates, and accepts a new candidate on improvement, accumulating lessons from ancestors. The public surface includes gepa.optimize(seed_candidate, trainset, valset, task_lm, reflection_lm, max_metric_calls), dspy.GEPA, and optimize_anything(seed_candidate, evaluator, objective, config) where oa.log() feeds outputs and errors back into reflection. The adapter layer requires GEPAAdapter.evaluate and make_reflective_dataset; the output is the improved text parameter in result.best_candidate.
- Engineers who want to lift a prompt's accuracy on benchmarks like AIME or HotpotQA without running large-scale RL
- Researchers building DSPy pipelines who want to optimize whole programs via
dspy.GEPA - Developers optimizing MCP tool descriptions or LangChain/LangGraph agent prompts
- Teams using Claude Code, Cursor or Codex that want the coding agent itself to drive
optimize_anything - Systems researchers tuning non-prompt artifacts such as code, configs, scheduling policies or SVGs
- Users of MLflow, Comet ML Opik or Pydantic AI looking for a bundled prompt-optimization algorithm
How do you install or deploy this agent?
Install from PyPI (requires Python and pip):
pip install gepaFor the latest from main:
pip install git+https://github.com/gepa-ai/gepa.gitSome adapters have optional extras, for example:
pip install "gepa[confidence]"
pip install "gepa[langchain]"For the Agent Skill form, clone the repo and Claude Code (plus other agents reading .claude/skills/) will auto-discover .claude/skills/gepa-optimize-anything/, or install it as a plugin:
/plugin marketplace add gepa-ai/gepa
/plugin install gepa-optimize-anything@gepaYou need API credentials for a task LM and a reflection LM (the README examples use openai/gpt-4.1-mini and openai/gpt-5).
How do you use this agent?
Minimal prompt-optimization example on AIME:
import gepa
trainset, valset, _ = gepa.examples.aime.init_dataset()
seed_prompt = {
"system_prompt": "You are a helpful assistant. Answer the question. "
"Put your final answer in the format '### <answer>'"
}
result = gepa.optimize(
seed_candidate=seed_prompt,
trainset=trainset,
valset=valset,
task_lm="openai/gpt-4.1-mini",
max_metric_calls=150,
reflection_lm="openai/gpt-5",
)
print("Optimized prompt:", result.best_candidate['system_prompt'])Or drive it from DSPy:
import dspy
optimizer = dspy.GEPA(
metric=your_metric,
max_metric_calls=150,
reflection_lm="openai/gpt-5",
)
optimized_program = optimizer.compile(student=MyProgram(), trainset=trainset, valset=valset)To optimize arbitrary text artifacts, supply your own evaluator:
import gepa.optimize_anything as oa
from gepa.optimize_anything import optimize_anything, GEPAConfig, EngineConfig
def evaluate(candidate: str) -> float:
result = run_my_system(candidate)
oa.log(f"Output: {result.output}")
oa.log(f"Error: {result.error}")
return result.score
result = optimize_anything(
seed_candidate="<your initial artifact>",
evaluator=evaluate,
objective="Describe what you want to optimize for.",
config=GEPAConfig(engine=EngineConfig(max_metric_calls=100)),
)What are this agent's strengths and limitations?
- Reflection reads full execution traces rather than a scalar reward, so it can explain failures and produce targeted edits, keeping optimization traces human-readable
- Evaluation budget is far smaller than RL: per the README, 100–500 evaluations versus 5,000–25,000+ for GRPO
- A clear GEPAAdapter contract (
evaluate+make_reflective_dataset) with ready-made adapters for DSPy, MCP, LangChain, RAG, TerminalBench and more - Works with scarce data — as few as 3 examples per the README — and on API-only models with no weight access
- Already integrated into DSPy, MLflow, Comet ML Opik, Pydantic AI and Google ADK, lowering migration effort
optimize_anythingextends optimization beyond prompts to code, configs, agent architectures and SVGs
- Depends on paid cloud LLM APIs; task-LM and reflection-LM calls scale with evaluation count and the README gives no cost estimate
- Quality is highly sensitive to the evaluator and the richness of diagnostic feedback, so weak metrics propagate directly into results
- Non-prompt artifacts require writing your own evaluator and sometimes an adapter, which is real integration work
- Headline figures (90x cheaper, 35x faster than RL) come from linked blogs and papers; no in-repo reproducible benchmark is provided
- Runtime constraints such as Python version or supported operating systems are not documented in the README
How does this agent compare with similar options?
The repository positions GEPA against two approaches. Versus reinforcement learning (RL/GRPO), it needs roughly 100–500 evaluations instead of 5,000–25,000+ and requires no weight access, so it runs on API-served models. Versus gradient-based methods, it does not collapse traces into a scalar reward but lets an LLM read full traces. The README also recommends using GEPA for rapid initial optimization and then applying RL or fine-tuning for further gains (BetterTogether), framing the two as complementary rather than substitutes.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| GEPA Reflective Optimizer This agent | 52 · Major gaps | Library / SDKFree + model costs | ★ 7.3k | 1d ago | Jupyter Notebook | Codex · Claude Code · OpenAI API · Claude API |
| OpenEvolve | 51 · Major gaps | CLIFree + model costs | ★ 7.7k | 1d ago | Python | Claude Code · OpenAI API |
| MS-Agent | 67 · Some gaps | Web appFree + model costs | ★ 4.4k | 5d ago | Python | — |
| Weco Autoresearch | 59 · Major gaps | CLIFree + model costs | ★ 124 | 5d ago | Python | Codex · Claude Code · OpenAI API |
How does FollowAgents rate this agent?
Why each dimension lost points
Trust is thin overall. Least privilege: SKILL.md describes backends that spawn Claude Code subprocesses, run an HTTP eval server, and a code-execution adapter that runs candidate code, yet no permission scoping or sandbox constraints appear in the packet — 1. User confirmation: optimize_anything can burn many paid LLM calls, but no cost confirmation or dry-run guidance is given — 1. Data-flow transparency: SKILL.md states the evaluator is black-box and the candidate string is visible to the proposer, which is partial transparency, but trace/log destinations are unstated — 1. Sensitive data: no handling guidance for API keys or sensitive trace content — 1. Dependency security: pyproject explicitly excludes known-bad litellm versions with rationale, and CI pins action SHAs — 2. External effects: real paid API calls and possible code execution with no isolation or rollback — 1. Rollback: no versioning/rollback for optimized artifacts — 1. Source attribution: LICENSE names the author, README cites the paper and sources — 2.
Self-consistency: README, AGENTS.md and SKILL.md agree on the optimize_anything vs GEPA-backend relationship — 2. Dependency availability: core package has empty dependencies, optional extras are platform-annotated, requires-python is explicit — 2. Failure messages: conftest replay mode gives clear pytest.fail messages, but product-level error handling for LLM/evaluator failures is not visible in the sample — 1.
Audience and scenarios: README covers prompts, code, configs, agent architectures plus DSPy/LangChain/MCP adapters — 2. Capability boundaries: SKILL.md clearly states candidates must be scorable strings, black-box refers to the evaluator, and multi-component dicts exist only in the lower-level API — 2. Trigger precision: the SKILL.md description lists explicit trigger conditions — 2. Environment fit: Python 3.10–3.14, multi-platform wheel notes, uv workflow — 2.
Information architecture: README is well structured and AGENTS.md gives the directory layout — 2. Install notes: pip, source install and plugin-marketplace install are all documented — 2. Naming stability: package gepa and plugin gepa-optimize-anything are consistent, though SKILL.md admits the package name doubles as the optimizer name, a minor ambiguity — 2. Examples and FAQ: multiple runnable examples and sample optimized prompts — 2. Known limitations: only litellm wheel caveats in pyproject comments; no dedicated limitations section — 1. License: MIT, consistent across LICENSE, pyproject and marketplace — 2. Versioning/changelog: version number and release workflow exist, but no CHANGELOG — 1. Maintenance responsibility: author and bot email visible, but no CONTRIBUTING/SECURITY or explicit maintenance commitment — 1.
Output usability: examples print the optimized prompt directly and the result object is clear — 2. Marginal value: far fewer evaluations than RL, backed by a paper and multiple framework integrations — 2. Cost-benefit: README claims 90x cheaper and 35x faster, but these rest on external blogs/paper with no in-repo benchmark reproduction — 1.
Claim traceability: key results link to the paper or blog, but no reproduction data ships in the repo — 1. Cross-source corroboration: README, SKILL.md and pyproject are mutually consistent, but performance numbers come from a single external source — 1. Fact/inference separation: README mixes marketing claims with mechanism description without clearly separating measured from asserted — 1.
- optimize_anything makes real paid LLM API calls and may execute candidate code; assess cost and isolation risk before use.
- SKILL.md notes autoresearch/meta_harness backends spawn Claude Code subprocesses; no permission scoping or sandboxing is documented in the packet.
- Performance claims such as 90x cheaper and 35x faster come from external blogs and the paper; no in-repo reproduction scripts, so treat them as unverified.
- Publisher identity is not verified by the FollowAgents enterprise registry and is treated as unknown, not as a trust signal.
- No CHANGELOG or security policy file is present, so long-term maintenance commitment is unclear.
Maintain this project? Add the FARS badge to your README
[](https://followagents.com/en/agents/gepa)<a href="https://followagents.com/en/agents/gepa"><img src="https://followagents.com/badge/gepa.svg" alt="FARS review"></a>FAQ
What does running GEPA cost?
max_metric_calls and the models chosen; the README does not quote a figure.Can I use it with very little training data?
Does it only optimize prompts?
optimize_anything targets code, agent architectures, configurations, scheduling policies, SVGs and other text artifacts — provided you supply an evaluator that returns a score and log diagnostics through oa.log().Can I use closed API-only models?
openai/gpt-4.1-mini and openai/gpt-5, and the same approach applies to other API-served models.How does it connect to my existing system?
evaluate and make_reflective_dataset, and GEPA handles the search and selection. Ready-made adapters exist for DSPy, LangChain, MCP, RAG and other stacks.Thanks — we use this to improve the page.