Quickstart
Install the Agent Optimizer SDK, run your first optimization, and inspect the results in under 10 minutes.
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?
Section titled “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
Section titled “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
Section titled “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
Section titled “2. Create a dataset and metric”import opik
from opik.evaluation.metrics import LevenshteinRatio
client = opik.Opik()
dataset = client.get_or_create_dataset(name="agent-opt-quickstart")
dataset.insert([
{"question": "What is Opik?", "answer": "Opik is an LLM observability and optimization platform."},
{"question": "How do I reduce hallucinations?", "answer": "Use evaluations and prompt optimization to enforce grounding."},
])
def answer_quality(item, output):
metric = LevenshteinRatio()
return metric.score(reference=item["answer"], output=output)3. Run the optimizer
Section titled “3. Run the optimizer”from opik_optimizer import MetaPromptOptimizer, ChatPrompt
prompt = ChatPrompt(
messages=[
{"role": "system", "content": "You are a precise assistant."},
{"role": "user", "content": "{question}"},
],
model="openai/gpt-5-nano" # The model your prompt runs on
)
optimizer = MetaPromptOptimizer(model="openai/gpt-5-nano") # The model that improves your prompt
result = optimizer.optimize_prompt(
prompt=prompt,
dataset=dataset,
metric=answer_quality,
max_trials=3,
n_samples=2,
)
result.display()4. Inspect results
Section titled “4. Inspect results”- Run
opik dashboardor 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
Section titled “Common first issues”Prompt must be a ChatPrompt object
Import ChatPrompt from opik_optimizer and wrap your messages list before passing it to any optimizer.
Authentication failed
Re-run opik configure and confirm the account has Agent Optimizer access. If you changed machines, copy the ~/.opik/config file or re-enter the key.
liteLLM provider errors
Ensure provider keys (e.g., OPENAI_API_KEY) are exported in the same shell running the script, and verify the model you selected is enabled for that key.
Next steps
Section titled “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.