> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mutagent.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Optimization Overview

> Automatically improve prompts with AI-driven optimization

# Prompt Optimization

MutagenT's optimization engine automatically improves prompts using AI-driven mutation and evaluation cycles. Instead of manually tweaking prompts, let the system find better variations for you.

## How It Works

The optimization process follows an evolutionary approach:

<Mermaid
  chart={`
flowchart LR
A["1. ANALYZE<br/>Baseline scoring"] --> B["2. MUTATE<br/>Generate variants"]
B --> C["3. TEST<br/>Evaluate variants"]
C --> D["4. SELECT<br/>Keep best"]
D --> E{Converged?}
E -->|No| A
E -->|Yes| F["Best Prompt"]

style A fill:#06B6D4,color:#000
style B fill:#7C3AED,color:#fff
style C fill:#F59E0B,color:#000
style D fill:#10B981,color:#000
style F fill:#10B981,color:#000
`}
/>

### The Four Steps

1. **Analyze** - Evaluate the current prompt against the dataset to establish a baseline score
2. **Mutate** - Use AI to generate prompt variations (rewording, restructuring, adding/removing content)
3. **Test** - Evaluate each variation against the same dataset using the evaluation criteria
4. **Select** - Keep the best performing version as the new baseline

The cycle repeats until:

* Target score is reached
* Max iterations hit
* No improvement found (patience exceeded)

## Key Concepts

<CardGroup cols={2}>
  <Card title="Evaluation Criteria" icon="chart-line">
    The metrics defined in your evaluation that score each prompt variant. Optimization improves scores across selected criteria.
  </Card>

  <Card title="Target Score" icon="bullseye">
    The goal score to achieve. Optimization stops early when this threshold is reached.
  </Card>

  <Card title="Patience" icon="hourglass">
    Number of iterations without improvement before stopping early. Prevents wasted compute.
  </Card>

  <Card title="Iterations" icon="repeat">
    Maximum number of mutation-evaluation cycles. More iterations = better results (to a point).
  </Card>
</CardGroup>

## Key Features

<CardGroup cols={2}>
  <Card title="Optimization Jobs" icon="gears" href="/platform/optimization/jobs">
    Configure, run, and manage optimization jobs with full lifecycle control.
  </Card>

  <Card title="Real-time Streaming" icon="bolt" href="/platform/optimization/streaming">
    Watch optimization progress in real-time via WebSocket updates.
  </Card>
</CardGroup>

## Quick Start

<CodeGroup>
  ```bash CLI theme={null}
  # Start optimization
  mutagent prompts optimize start 123 \
    --dataset 456 \
    --max-iterations 10 \
    --model claude-sonnet-4-6

  # Check status
  mutagent prompts optimize status <job-id>

  # Get results
  mutagent prompts optimize results <job-id>
  ```

  ```typescript TypeScript theme={null}
  import { Mutagent } from '@mutagent/sdk';

  const client = new Mutagent({
    security: { apiKey: process.env.MUTAGENT_API_KEY },
  });

  // Start optimization
  const job = await client.optimization.optimizePrompt({
    id: 123,  // Prompt ID
    body: {
      datasetId: 456,
      config: {
        maxIterations: 10,
        targetScore: 0.9,
        model: 'claude-sonnet-4-6',
      },
    },
  });

  console.log('Job started:', job.id);
  console.log('Status:', job.status);
  ```

  ```bash cURL theme={null}
  # Start optimization
  curl -X POST https://api.mutagent.io/api/prompt/123/optimize \
    -H "x-api-key: mt_xxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "datasetId": 456,
      "config": {
        "maxIterations": 10,
        "targetScore": 0.9,
        "model": "claude-sonnet-4-6"
      }
    }'
  ```
</CodeGroup>

## Prerequisites for Optimization

Before running optimization, ensure you have:

<Steps>
  <Step title="A Prompt">
    The prompt you want to optimize, with defined variables and content
  </Step>

  <Step title="A Dataset">
    Test cases with inputs and expected outputs (20+ items recommended)
  </Step>

  <Step title="Evaluation Criteria">
    An evaluation definition with criteria (metrics, weights, thresholds) linked to the prompt
  </Step>

  <Step title="Configured LLM Provider">
    At least one LLM provider configured in **Settings > Providers** (e.g., OpenAI, Anthropic). The CLI runs a provider pre-flight check before starting optimization.
  </Step>
</Steps>

## Optimization Strategies

Choose the right approach based on your needs:

### Conservative

Small, incremental changes. Lower risk of breaking existing behavior. Good for production prompts.

```bash theme={null}
mutagent prompts optimize start 123 \
  --dataset 456 \
  --max-iterations 20 \
  --model claude-sonnet-4-6
```

**Best for:**

* Prompts already in production
* Risk-sensitive applications
* Fine-tuning existing prompts

### Balanced

Moderate changes with balanced exploration. Good default for most use cases.

```bash theme={null}
mutagent prompts optimize start 123 \
  --dataset 456 \
  --max-iterations 10 \
  --model claude-sonnet-4-6
```

**Best for:**

* New prompt development
* General improvement
* Unknown optimization potential

### Aggressive

Larger, more experimental changes. May find significantly better prompts but requires more iterations.

```bash theme={null}
mutagent prompts optimize start 123 \
  --dataset 456 \
  --max-iterations 10 \
  --model claude-sonnet-4-6
```

**Best for:**

* Prompts with low baseline scores
* Exploring new approaches
* When conservative optimization plateaus

## When to Optimize

<AccordionGroup>
  <Accordion title="After creating a new prompt baseline">
    Once you have a working prompt, dataset, and evaluation criteria, run optimization to improve it before going to production.
  </Accordion>

  <Accordion title="When evaluation scores drop">
    If your prompt's scores decline (due to model changes, new edge cases, etc.), optimization can help recover.
  </Accordion>

  <Accordion title="Before major deployments">
    As part of your release process, optimize prompts to ensure they're performing at their best.
  </Accordion>

  <Accordion title="Periodically as maintenance">
    Schedule regular optimization runs to prevent gradual degradation and capture improvement opportunities.
  </Accordion>
</AccordionGroup>

## Optimization vs Manual Tuning

| Aspect             | Manual Tuning            | Automated Optimization         |
| ------------------ | ------------------------ | ------------------------------ |
| Time               | Hours to days            | Minutes to hours               |
| Consistency        | Subjective               | Objective, metric-driven       |
| Coverage           | Limited variations tried | Many variations explored       |
| Reproducibility    | Hard to reproduce        | Fully tracked and reproducible |
| Expertise required | High                     | Low (once dataset is ready)    |

## What's Next?

<CardGroup cols={2}>
  <Card title="Optimization Jobs" icon="gears" href="/platform/optimization/jobs">
    Learn to configure, run, and manage optimization jobs
  </Card>

  <Card title="Streaming Updates" icon="bolt" href="/platform/optimization/streaming">
    Get real-time progress updates via WebSocket
  </Card>
</CardGroup>