Skip to main content
This quickstart shows how to optimize coding agent instructions using GEPA. We optimize the full instruction surface: system prompts, AGENTS.md files, and skills definitions.

The Task

Implement Pokemon TCG card effects in Rust by replacing todo!() stubs with working code. The agent is evaluated on test pass rate.
// Before (stub)
pub fn grind_damage(attached_energy: u32) -> i32 { todo!() }

// After (implemented)
pub fn grind_damage(attached_energy: u32) -> i32 { (10 * attached_energy) as i32 }

Architecture

1. Install and Setup

git clone https://github.com/synth-laboratories/synth-ai
cd synth-ai
uv sync
Set credentials:
export OPENAI_API_KEY="sk-..."
export DAYTONA_API_KEY="dtn_..."
export SYNTH_API_KEY="sk_live_..."

2. Configure GEPA

enginebench_gepa.toml
[prompt_learning]
task_app_url = "http://localhost:8020"
algorithm = "gepa"

[prompt_learning.policy]
model = "gpt-4.1-mini"
provider = "openai"
inference_mode = "synth_hosted"

[prompt_learning.policy.context_override]
system_prompt = """You are an expert Rust developer implementing Pokemon TCG cards.

Your task: Implement card effects by editing Rust files with stub functions.

Key patterns:
- Use `def_id_matches(&card.def_id, "DF", NUMBER)` to identify cards
- Implement attack modifiers in `attack_override`
- Use `game.queue_prompt()` for user choices

Output requirements:
1. ACTUALLY EDIT files - replace TODO stubs with working code
2. Make sure code compiles (`cargo check`)
3. Make sure tests pass (`cargo test`)"""

[prompt_learning.gepa]
env_name = "engine_bench"

[prompt_learning.gepa.evaluation]
seeds = [0, 2, 7, 8, 9, 16, 22, 29, 35, 42, 51, 68, 77, 88, 99]
validation_seeds = [0, 9, 22, 42, 77]

[prompt_learning.gepa.population]
initial_size = 8
num_generations = 5
children_per_generation = 8

[prompt_learning.gepa.rollout]
budget = 200
max_concurrent = 6

3. Enable Unified Optimization (Optional)

Optimize AGENTS.md and skills files together:
enginebench_gepa_unified.toml
[prompt_learning.gepa.unified_optimization]
enable_task_app_context_overrides = true
optimization_target = "unified"
mutable_files = ["AGENTS.md", ".codex/skills.yaml"]

[prompt_learning.policy.context_override]
file_artifacts = { "AGENTS.md" = """# Agent Instructions

## Primary Objective
Implement Pokemon TCG card effects in Rust.

## Rules
1. Read existing code patterns first
2. Follow the engine architecture
3. Run tests after implementation
""" }

4. Run Optimization

USE_DAYTONA_SANDBOXES=1 \
uv run python demos/engine_bench/run_gepa_unified.py \
  --port 8001 \
  --task-app-url https://YOUR-SUBDOMAIN.usesynth.ai

Results

MetricBaselineOptimized
Test pass rate45%78%
Compilation success72%94%

What Gets Optimized

GEPA evolves instruction content while preserving structure:
ComponentWhat Gets Optimized
System PromptCore instructions passed to the LLM
AGENTS.mdStartup instructions for Codex/OpenCode
Skills Files.codex/skills.yaml, .opencode/skills.yaml

Supported Agents

AgentCLIInstructions Source
Codexcodex execAGENTS.md, .codex/skills.yaml
OpenCodeopencodeAGENTS.md, .opencode/skills.yaml
Claude CodeclaudeAGENTS.md

Next Steps


Ready to get started?