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

# Agent Mutations

> Test agent configuration variants side-by-side in a single evaluation

Agent mutations let you create configuration variants of an agent and run them alongside the base agent in a single evaluation. Instead of manually creating separate agents for each configuration you want to test, mutations override specific fields and produce side-by-side results so you can compare performance directly.

## How Mutations Work

Every agent has a base configuration: model, system prompt, temperature, voice, API key, and other settings depending on the agent type. A mutation overrides one or more of these fields while leaving the rest unchanged.

When you launch an evaluation with mutations selected, Coval runs the base agent **plus** each selected mutation as separate simulations. The results appear in the same run, grouped by variant, so you can compare metrics across configurations.

<Info>
  The base agent always runs. Mutations are additional variants that run alongside it.
</Info>

### Deep Merge

Mutation overrides are deep-merged with the base agent configuration. For nested objects (like custom headers), this means individual keys are overridden while sibling keys are preserved.

```json theme={null}
// Base agent metadata
{ "custom_sip_headers": { "X-Session-Id": "abc", "X-Routing": "prod" } }

// Mutation override
{ "custom_sip_headers": { "X-Session-Id": "override-123" } }

// Merged result at runtime
{ "custom_sip_headers": { "X-Session-Id": "override-123", "X-Routing": "prod" } }
```

For scalar values (strings, numbers), the mutation value replaces the base value entirely.

## Supported Agent Types

Mutations are available for agent types that have overridable configuration fields:

| Agent Type              | Overridable Fields                                                  |
| ----------------------- | ------------------------------------------------------------------- |
| **WebSocket**           | Endpoint, initialization JSON, authorization header, custom headers |
| **Inbound Voice (SIP)** | Custom SIP headers                                                  |

## Creating Mutations

1. Navigate to your agent's detail page
2. Scroll to the **Mutations** section
3. Click **Create**

### Mutation Form

Each mutation requires:

* **Name** -- A descriptive label (e.g., "High Temperature", "French Language", "GPT-4 Turbo")
* **Description** -- Optional context about what this variant tests

Then select which fields to override. Only fields defined for your agent type are available. For each selected field, enter the override value using the appropriate editor:

* **Text input** for simple string or number fields
* **Dropdown** for fields with predefined options (e.g., model selection, voice)
* **JSON editor** for structured data fields (e.g., custom headers)

<Tip>
  Only override the fields you want to test. Fewer overrides make results easier to interpret.
</Tip>

## Using Mutations in Evaluations

When launching an evaluation or creating a template:

1. Select a single agent
2. The **Agent Mutations** selector appears if the agent has active mutations
3. Check the mutations you want to include

The base agent is always included. Each selected mutation creates additional simulations in the same run.

### Viewing Results

After the evaluation completes:

* The **Mutation** column in the results table shows which variant produced each result
* Use the **filter dropdown** to isolate results by mutation
* On the **Dashboard**, use the "Agent Mutation" dimension to split charts by variant

This lets you directly compare metrics like latency, accuracy, or custom scores across your base agent and each mutation.

## Common Use Cases

**Model comparison** -- Create mutations for different models (GPT-4o vs GPT-4 Turbo vs Claude) to benchmark quality and latency.

**Prompt tuning** -- Test system prompt variations to find the wording that produces the best metric scores.

**Temperature sweeps** -- Run the same agent at different temperature values to find the optimal balance of creativity and consistency.

**Voice testing** -- Compare different TTS voices or providers to find the best fit for your use case.

**Header overrides** -- For SIP-based voice agents, test different routing headers or session metadata per variant.

## Managing Mutations

### Editing

Click the edit icon on any mutation card to modify its name, description, or overrides.

### Deleting

Click the delete icon to archive a mutation. If the mutation is referenced by active templates, you will see a warning listing those templates. You can cancel or force-delete, which causes those templates to skip the deleted mutation on future runs.

<Warning>
  Archived mutations cannot be restored. Create a new mutation if you need the same configuration again.
</Warning>

## API and CLI

Mutations can also be managed programmatically:

<CardGroup cols={2}>
  <Card title="REST API" icon="square-terminal" href="/api-reference/v1/mutations/mutations/list-mutations">
    Create, list, update, and delete mutations via the v1 API
  </Card>

  <Card title="CLI" icon="terminal" href="/cli/mutations">
    Manage mutations from the command line
  </Card>
</CardGroup>