Agent Optimization

Opik Agent Optimizer is a turnkey, open-source agent and prompt optimization SDK. It automatically tunes prompts, tools, and agent workflows using the datasets, metrics, and traces you already log to Opik. Instead of hand-editing instructions and re-running evaluations, pick an optimizer (MetaPrompt, HRPO, Evolutionary, GEPA, etc.) and let it iterate for you online or fully offline inside Docker and Kubernetes.

<Frame> </Frame>

Why teams choose Opik Agent Optimizer

• Automatic prompt optimization – end-to-end workflow that installs in minutes and runs locally or in your stack.
• Open-source and framework agnostic – no lock-in, use Opik’s first-party optimizers or community favorites like GEPA in the same SDK.
• Agent-aware – optimize beyond system prompts, including MCP tool signatures, function-calling schemas, and multi-step agent workflows.
• Deep observability – every trial logs prompts, tool calls, traces, and metric reasons to Opik so you can explain and ship changes confidently.

Key capabilities

<CardGroup cols={2}> <Card title="Optimizer suite" href="/v1/agent_optimization/algorithms/overview" icon="fa-solid fa-diagram-project" iconPosition="left"> MetaPrompt, HRPO, Few-Shot Bayesian, Evolutionary, GEPA, Parameter tuning. Swap optimizers without changing your workflow. </Card> <Card title="Multi-agent + multi-prompt" href="/v1/agent_optimization/optimization/optimize_agents" icon="fa-solid fa-people-group" iconPosition="left"> Optimize full agent systems with multiple prompts, tools, and orchestration logic, not just a single system message. </Card> <Card title="Tool & function calling" href="/v1/agent_optimization/algorithms/tool_optimization" icon="fa-solid fa-screwdriver-wrench" iconPosition="left"> Optimize tool schemas and function calling alongside prompt text with the same metrics and datasets. </Card> <Card title="Dashboard analytics" href="/v1/agent_optimization/optimization/dashboard_results" icon="fa-solid fa-chart-line" iconPosition="left"> Track trials, candidates, datasets, and trace-level evidence to explain and ship improvements confidently. </Card> <Card title="Optimization Studio" href="/v1/agent_optimization/optimization_studio" icon="fa-solid fa-wand-magic-sparkles" iconPosition="left"> Run optimizer workflows directly from the UI with no-code configuration and result review. </Card> <Card title="Secure & offline" href="/v1/self-host/overview" icon="fa-solid fa-shield-halved" iconPosition="left"> Run the SDK locally or inside Opik Docker to keep data inside your network. </Card> </CardGroup>

How it works

<Steps> <Step title="1. Prepare data & metrics"> Use Opik datasets (CSV upload, API, or trace exports) plus deterministic metrics/`ScoreResult` functions. See [Define datasets](/v1/agent_optimization/optimization/define_datasets) and [Define metrics](/v1/agent_optimization/optimization/define_metrics). </Step> <Step title="2. Pick an optimizer"> Choose the best algorithm for your task (see [Optimization algorithms](/v1/agent_optimization/algorithms/overview)). All optimizers expose the same API, so you can swap them easily or chain runs. </Step> <Step title="3. Inspect & ship"> Results land in the Opik dashboard under **Evaluation → Optimization runs**, where you can compare prompts, failure modes, and dataset coverage before promoting the change. </Step> </Steps>

Start fast

• Want a no-code workflow? Use Optimization Studio to run optimizations from the Opik UI.
• Follow the Quickstart to run your first optimization locally.
• Prefer notebooks? Launch the Quickstart notebook.
• Need scenario-specific guidance? Explore the Cookbooks.

Optimization Algorithms

The optimizer implements both proprietary and open-source optimization algorithms. Each one has its strengths and weaknesses, we recommend first trying out either GEPA or HRPO (Hierarchical Reflective Prompt Optimizer) as a first step:

Algorithm	Description
MetaPrompt Optimization	Uses an LLM ("reasoning model") to critique and iteratively refine an initial instruction prompt. Good for general prompt wording, clarity, and structural improvements. Supports MCP tool calling optimization.
HRPO (Hierarchical Reflective Prompt Optimizer)	Uses hierarchical root cause analysis to systematically improve prompts by analyzing failures in batches, synthesizing findings, and addressing identified failure modes. Best for complex prompts requiring systematic refinement based on understanding why they fail.
Few-shot Bayesian Optimization	Specifically for chat models, this optimizer uses Bayesian optimization (Optuna) to find the optimal number and combination of few-shot examples (demonstrations) to accompany a system prompt.
Evolutionary Optimization	Employs genetic algorithms to evolve a population of prompts. Can discover novel prompt structures and supports multi-objective optimization (e.g., score vs. length). Can use LLMs for advanced mutation/crossover.
GEPA Optimization	Wraps the external GEPA package to optimize a single system prompt for single-turn tasks using a reflection model. Requires pip install gepa.
Parameter Optimization	Optimizes LLM call parameters (temperature, top_p, etc.) using Bayesian optimization. Uses Optuna for efficient parameter search with global and local search phases. Best for tuning model behavior without changing the prompt.

<Tip> Want to see numbers? Check the new [optimizer benchmarks](/v1/agent_optimization/algorithms/benchmarks) page for the latest performance table and instructions for running the benchmark suite yourself. </Tip>

Next Steps

1. Explore specific Optimizers for algorithm details.
2. Refer to the FAQ for common questions and troubleshooting.
3. Refer to the API Reference for detailed configuration options.

<Info> 🚀 Want to see Opik Agent Optimizer in action? Check out our [Example Projects & Cookbooks](/v1/agent_optimization/cookbooks/optimizer_introduction_cookbook) for runnable Colab notebooks covering real-world optimization workflows, including HotPotQA and synthetic data generation. </Info>