Skip to main content
GEPA optimizes prompts by evaluating many candidate prompts against your container and selecting the best performers.

​
At a glance

GEPA offline loop: backend proposes candidates, evaluates them on seeds by calling your container, then selects the best prompt.

​
When to use

  • You have a dataset-backed container with multiple examples
  • You want to optimize a prompt against a reward signal
  • You can deterministically map seed → example
  • You’re optimizing offline on a fixed dataset (the backend drives /rollout calls to your container; “offline” means batch optimization, not “no rollouts”)
  • You want broad exploration and diverse prompt variants (evolutionary search)

​
What you need

  1. A container that implements /health, /task_info, and /rollout
  2. A dataset with deterministic seed mapping (seed -> example)
  3. A reward function returned as metrics.mean_return
  4. A GEPA config (TOML) with train + validation seeds

​
How evaluation works (no prompt leakage)

GEPA never sends optimized prompts to your container. The backend registers each candidate with an interceptor and passes your container an inference_url to call. The interceptor substitutes the candidate prompt at LLM time and captures traces.

​
Basic workflow

  1. Run your container (in-process, local + tunnel, or deployed)
  2. Create a GEPA config
  3. Submit a prompt optimization job
  4. Poll until complete and fetch the best prompt

​
Minimal example

import os
from synth_ai.sdk import OfflineJob

job = OfflineJob.from_config(
    "gepa.toml",
    api_key=os.environ["SYNTH_API_KEY"],
    algorithm="gepa",
)
job.submit()
result = job.poll_until_complete()
print(result.best_prompt)

​
Config essentials

Your config must include:
  • prompt_learning.container_url
  • prompt_learning.container_api_key (ENVIRONMENT_API_KEY)
  • prompt_learning.initial_prompt
  • prompt_learning.gepa.evaluation.seeds
  • prompt_learning.gepa.evaluation.validation_seeds

​
Container tips

  • Use seed to select examples deterministically
  • Return metrics.mean_return for each rollout
  • Route LLM calls through policy_config.inference_url

​
Next steps

  • Container overview: /sdk/container/overview
  • GEPA config + SDK surface: GEPA Reference