Quickstart

Opik Agent Optimizer Quickstart gives you the fastest path from “hello world” to a successful optimization run. If you already walked through the main Opik Quickstart (tracing + evaluation), this is the next stop—it layers on the opik-optimizer SDK so you can automatically improve prompts and agents. Prefer a UI workflow? Use Optimization Studio instead.

Why Opik Agent Optimizer?

• Production-grade workflows – reuse the same datasets, metrics, and tracing you already have in Opik.
• Multiple strategies – swap between MetaPrompt, Hierarchical Reflective Prompt Optimizer (HRPO), Evolutionary, GEPA, and more with one API.
• Deep analysis – every trial is logged to Opik so you can inspect prompts, tool calls, and failure modes.

Prerequisites

• Python 3.10+
• Opik account
• Access to an OpenAI-compatible LLM via LiteLLM (OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.)

1. Install and authenticate

$
pip install --upgrade opik opik-optimizer
$
opik configure  # paste your API key
$
export OPIK_PROJECT_NAME="optimization-quickstart"

Setting OPIK_PROJECT_NAME ensures all traces, experiments, and optimization runs are logged to the same project without having to pass project_name to every SDK call.

2. Create a dataset and metric

1
import opik
2
from opik.evaluation.metrics import LevenshteinRatio
3
4
client = opik.Opik()
5
dataset = client.get_or_create_dataset(name="agent-opt-quickstart")
6
dataset.insert([
7
    {"question": "What is Opik?", "answer": "Opik is an LLM observability and optimization platform."},
8
    {"question": "How do I reduce hallucinations?", "answer": "Use evaluations and prompt optimization to enforce grounding."},
9
])
10
11
def answer_quality(item, output):
12
    metric = LevenshteinRatio()
13
    return metric.score(reference=item["answer"], output=output)

3. Run the optimizer

1
from opik_optimizer import MetaPromptOptimizer, ChatPrompt
2
3
prompt = ChatPrompt(
4
    messages=[
5
        {"role": "system", "content": "You are a precise assistant."},
6
        {"role": "user", "content": "{question}"},
7
    ],
8
    model="openai/gpt-5-nano"  # The model your prompt runs on
9
)
10
11
optimizer = MetaPromptOptimizer(model="openai/gpt-5-nano")  # The model that improves your prompt
12
result = optimizer.optimize_prompt(
13
    prompt=prompt,
14
    dataset=dataset,
15
    metric=answer_quality,
16
    max_trials=3,
17
    n_samples=2,
18
)
19
20
result.display()

4. Inspect results

• Run opik dashboard or open https://www.comet.com/opik.
• In the left nav, go to Evaluation → Optimization runs, then select your latest run.
• Review the optimization-progress chart, trial table, and per-trial traces to decide whether to ship the new prompt.

Common first issues

Next steps

• Prefer notebooks? Launch the Quickstart notebook.
• Dive deeper into Define datasets and Define metrics.
• Explore the Optimization Algorithms overview to pick the best strategy for your workload.