rollout
Sign up free

Optimization (GEPA)

Define a target — Python

A target is the seam between GEPA and your agent. It takes one dataset task and one proposed candidate prompt, runs your real agent with that candidate applied, and returns the output for the verifier to score.

The @rollout.optimize decorator

Decorate a function with @rollout.optimize. It registers the function as a named target the CLI can discover, and records the baseline artifact GEPA starts from.

targets.py
import mv37.rollout as rolloutBASELINE_PROMPT = "You are a careful support agent."@rollout.optimize(    id="support-agent-system-prompt",    kind="prompt",    description="System prompt for the support agent",    baseline=BASELINE_PROMPT,)def run_candidate(    task: rollout.Task,    candidate: rollout.Candidate,) -> rollout.AgentResult:    answer = run_agent(        task.instruction,        system_prompt=candidate.text,        # GEPA proposes this        order_id=task.input.get("order_id"),    )    return rollout.AgentResult(output=answer)

Tip

Apply candidate.text wherever the artifact belongs in your agent — usually the system prompt, but for a tool_descriptiontarget it is the tool's description string, and so on. Everything else about your agent stays fixed so the score reflects the prompt, not other changes.

Task, Candidate, AgentResult

The decorated function receives two objects and returns a third:

TypeFieldsNotes
Taskname, instruction, input, metadata, split, expected output schemaOne dataset row. input and metadata are plain dicts.
CandidatetextThe artifact GEPA proposes. For prompt targets, use candidate.text.
AgentResultoutput, trace_id?, latency_ms?, cost_usd?, metadata?The normalized result the verifier scores. Only output is required.

Target kinds

The kind tells GEPA what artifact it is evolving. Valid kinds are:

  • prompt — a system / instruction prompt
  • tool_description — the description string of a tool
  • router_prompt — a routing / dispatch prompt
  • retrieval_prompt — a query or retrieval-shaping prompt
  • agent — a broader agent artifact

Return shapes

For convenience, the target may return any of three shapes — they all normalize to AgentResult:

  • a rollout.AgentResult instance
  • a plain str (treated as output)
  • a dict that validates as AgentResult

Automatic tracing

When the SDK is initialized, OptimizationTarget.run(...) wraps each candidate/task execution in a trace named optimize:<target id> and attaches optimization attributes. That gives the Rollout UI a trace for every evaluated example, so the trials feed on the live run page can link straight to what the agent did.

How the CLI finds it

The CLI discovers targets by importing the module you pass with --module. A single optimize run with no run id syncs the target, uploads the dataset, creates the verifier, creates the run, and executes it:

shell
rollout optimize run \  --module app.targets \  --target support-agent-system-prompt \  --dataset ./datasets/refunds \  --verifier ./verifiers/refund-quality.json \  --reflection-model openai/gpt-4.1-mini

To re-run an existing run, pass its id: rollout optimize run opt_123 --module app.targets. To prepare a run without executing it (for CI, or to launch from the UI), use rollout optimize create with the same flags.

Registry helpers

For tests and local checks, the registry is introspectable:

python
rollout.list_optimization_targets()rollout.get_optimization_target("support-agent-system-prompt")rollout.clear_optimization_targets()

Note

The SDK does not upload datasets or create verifiers — that is the CLI's job. See Datasets and Verifiers, and the full end-to-end guide.