Skip to main content
If you already have a task app and want to start optimizing quickly, follow the steps below. This quickstart walks you through running your first GEPA job.

​
Getting started

You’ll deploy (or run) a task app, submit a GEPA job, and read the best prompt.

​
Prerequisites

  • SYNTH_API_KEY set in your environment
  • A task app that implements /health, /task_info, /rollout
  • Python 3.11+ and uv (or your preferred virtualenv)

​
1) Install the SDK

pip install synth-ai

​
2) Run a task app

If you already have a task app running, skip this step. Otherwise, run one locally and expose it with a tunnel: 
# start your task app
uvicorn my_task_app:app --host 127.0.0.1 --port 8114

# optional: create a tunnel
python - <<'PY'
from synth_ai.core.tunnels import TunneledLocalAPI
import asyncio

async def main():
    tunnel = await TunneledLocalAPI.create(local_port=8114)
    print("Task app URL:", tunnel.url)
    print("Worker token:", tunnel.worker_token)

asyncio.run(main())
PY

​
3) Create a GEPA config

Create gepa.toml: 
[prompt_learning]
algorithm = "gepa"
task_app_url = "http://localhost:8114"
task_app_api_key = "sk_env_..."

[prompt_learning.initial_prompt]
id = "baseline"
name = "Baseline"

[[prompt_learning.initial_prompt.messages]]
role = "user"
pattern = "Classify the intent."

[prompt_learning.gepa.evaluation]
seeds = [0,1,2,3,4,5,6,7,8,9]
validation_seeds = [10,11,12,13,14]

​
4) Submit the job

import os
from synth_ai.sdk import PromptLearningClient

client = PromptLearningClient(api_key=os.environ["SYNTH_API_KEY"])
job = await client.create_job_from_toml("gepa.toml")
await client.start_job(job["id"])
result = await client.poll_until_terminal(job["id"])
print("Best prompt:", result["best_prompt"])

​
Next steps

  • Run MIPRO online: /prompt-optimization/mipro
  • Build a task app: /sdk/localapi/overview
  • Use tunnels: /sdk/tunnels/synthtunnel

​
Walkthroughs (optional)

Prefer a guided walkthrough? Start here:

GEPA Banking77 Walkthrough

Step-by-step prompt optimization on the Banking77 intent classification dataset.

​
Ready to get started?

Get Started

Sign up and start optimizing your prompts today.

Schedule Demo

See Synth in action with a personalized walkthrough.