First Steps

Get Synth AI running in 5 minutes

Get your first training job running with GEPA on Banking77 intent classification.

Install

pip install synth-ai
# or
uv add synth-ai

Verify:

synth-ai --version

Quick Start: GEPA on Banking77

1. Get Credentials

uvx synth-ai setup

Opens browser to https://usesynth.ai. Fetches and saves:

• SYNTH_API_KEY - Backend authentication
• ENVIRONMENT_API_KEY - Task app authentication

2. Install Demo

uvx synth-ai demo gepa
cd demo_gepa

3. Add Inference Key

echo "GROQ_API_KEY=gsk_..." >> .env

Get a free key at https://console.groq.com

4. Run

uv run main.py

What happens:

1. Starts Banking77 task app on localhost
2. Opens Cloudflare tunnel for secure access
3. Submits GEPA optimization job
4. Streams progress in real-time
5. Saves best prompt when complete

Expected output:

[INFO] Task app running at http://127.0.0.1:8114
[INFO] Tunnel URL: https://xxx.trycloudflare.com
[INFO] Job submitted: pl_abc123
[PROGRESS] Generation 1/5: best_score=0.72
[PROGRESS] Generation 2/5: best_score=0.78
...
[COMPLETE] Best score: 0.85
[SAVED] Results: results/gepa_abc123.json

Core Concepts

Task App

FastAPI wrapper around your code. Required endpoints:

• GET / - Health check
• GET /info - Task metadata
• POST /rollout - Execute evaluation

Tunnel

Cloudflare tunnel exposes local task app to Synth backend securely.

Job

Training run submitted to Synth. Types:

• Prompt Learning (GEPA, MIPRO) - Optimize prompts
• RL (GSPO) - Train model weights via reinforcement
• SFT - Train model weights on demonstrations

CLI Commands

Command	Purpose
synth-ai setup	Get credentials
synth-ai demo <type>	Install demo (gepa, mipro, rl, sft)
synth-ai deploy	Deploy task app
synth-ai train	Submit training job
synth-ai status	Check job status
synth-ai eval	Run evaluations
synth-ai artifacts	Download results
synth-ai help	Get help

Agent Integration

Claude Code, Codex, and other coding agents can use Synth directly:

# Claude Code
uvx synth-ai claude

# OpenAI Codex
uvx synth-ai codex

See llms.txt for agent-specific instructions.

Next Steps

GEPA Quickstart

Detailed GEPA walkthrough

MIPRO Quickstart

Alternative prompt optimization

RL Quickstart

Train model weights with RL

SFT Quickstart

Fine-tune on demonstrations

References

• CLI Reference - All CLI commands
• SDK Reference - Programmatic access
• Training Config - Config parameters
• Task Apps - Build custom tasks