Skip to main content
MIPRO optimizes prompts through systematic instruction proposal and evaluation.

​
Quick Start (Online Mode)

MIPRO supports online optimization where you drive rollouts locally and the backend provides prompt candidates: 
[prompt_learning]
algorithm = "mipro"
container_url = "https://your-tunnel.trycloudflare.com"

[prompt_learning.mipro]
mode = "online"
bootstrap_train_seeds = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
val_seeds = [100, 101, 102, 103, 104]
online_pool = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
online_proposer_mode = "inline"
online_proposer_min_rollouts = 20
online_rollouts_per_candidate = 10

[prompt_learning.mipro.proposer]
mode = "instruction_only"
model = "gpt-4o-mini"
provider = "openai"
temperature = 0.7
max_tokens = 512

[prompt_learning.policy]
model = "gpt-4o-mini"
provider = "openai"
temperature = 0.0
max_completion_tokens = 256
Run with: 
import os
from synth_ai import SynthClient

def run_mipro():
    client = SynthClient(api_key=os.environ["SYNTH_API_KEY"])
    job = client.optimization.offline.create(
        config_path="my_config.toml",
        kind="mipro_offline",
    )
    job.submit()
    result = job.poll_until_complete()
    print(f"Best score: {result.best_score}")

​
Online vs Offline Mode

MIPRO supports two optimization modes:

​
Online Mode

  • You control rollouts: Drive the rollout loop locally
  • No tunneling required: Backend never calls your container
  • Real-time evolution: Prompts evolve as rewards are reported
  • Proxy URL: Backend provides a proxy URL that selects prompt candidates for each LLM call

​
Offline Mode

  • Backend drives rollouts: Backend calls your container
  • Tunneling required: Container must be publicly accessible
  • Environment API key: ENVIRONMENT_API_KEY must be registered with backend

​
Required Fields

FieldDescription
container_urlURL of your container (for offline mode) or any URL (for online mode)
mipro.modeOptimization mode: "online" or "offline"
mipro.bootstrap_train_seedsInitial training seeds for bootstrap phase
mipro.val_seedsValidation seeds for evaluation
mipro.online_poolPool of seeds for online optimization (online mode only)
mipro.online_proposer_modeProposer mode: "inline" (online mode only)
mipro.online_proposer_min_rolloutsMinimum rollouts before generating new proposals (online mode only)
mipro.online_rollouts_per_candidateNumber of rollouts per candidate before switching (online mode only)
mipro.proposer.modeProposer generation mode: "instruction_only"
mipro.proposer.modelModel for generating proposals
mipro.proposer.providerProvider for proposer model
policy.modelModel for policy execution
policy.providerProvider for policy model

​
Proposer Configuration

The proposer generates new prompt instructions. Key parameters:
  • proposer.mode: Currently supports "instruction_only" for instruction-level proposals
  • proposer.model: Model used for generating proposals (typically gpt-4o-mini or gpt-4o)
  • proposer.temperature: Controls randomness (0.7 recommended)
  • proposer.max_tokens: Maximum tokens for proposal output (512 recommended)
The proposer API key is automatically resolved from the backend’s environment (OPENAI_API_KEY or PROD_OPENAI_API_KEY).

​
Online Mode Workflow

  1. Create job: Submit MIPRO job with mode: "online"
  2. Get proxy URL: Backend returns a proxy URL endpoint
  3. Run rollouts: For each rollout:
    • Call proxy URL with your task input
    • Proxy selects best prompt candidate
    • Execute LLM call with selected prompt
    • Report reward back to backend
  4. Automatic evolution: Backend generates new proposals based on rewards

​
Tunnels

MIPRO offline mode requires your container to be reachable over HTTPS (the backend drives rollouts). MIPRO online mode does not require tunneling since you drive rollouts locally. No external binary required: 
from synth_ai.core.tunnels import SynthTunnel

tunnel = await SynthTunnel.create(local_port=8001, api_key="sk_live_...")

# Pass worker_token for SynthTunnel auth
job = OfflineJob.from_config(
    "config.toml",
    api_key=os.environ["SYNTH_API_KEY"],
    container_url=tunnel.url,
    container_worker_token=tunnel.worker_token,
)

​
Offline Mode — Cloudflare

Requires cloudflared installed. Use container_api_key instead of worker_token: 
from synth_ai.core.tunnels import SynthTunnel, TunnelBackend

tunnel = await SynthTunnel.create(
    local_port=8001,
    backend=TunnelBackend.CloudflareQuickTunnel,
)

​
Online Mode — No Tunnel Needed

In online mode, the backend provides a proxy URL and you drive rollouts locally. No tunnel is required: 
from synth_ai import SynthClient

client = SynthClient(api_key="sk_live_...")
session = client.optimization.online.create(kind="mipro_online", config_body=config)
proxy_url = session.get_prompt_urls()["online_url"]
# Use proxy_url in your local rollout loop
See Tunnels for the full comparison.

​
See Also