> ## 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.

# Mutations

> Test agent variations with config overrides using the Coval CLI

Mutations let you test variations of an agent by overriding configuration values without modifying the original agent. This is useful for A/B testing prompts, parameters, or model settings.

## List Mutations

```bash theme={null}
coval mutations list --agent-id <agent_id> [OPTIONS]
```

| Option        | Type   | Required | Description                    |
| ------------- | ------ | -------- | ------------------------------ |
| `--agent-id`  | string | **Yes**  | The parent agent ID            |
| `--page-size` | number | No       | Results per page (default: 50) |

**Output columns:** ID, NAME, PARAMETERS, CREATED

```bash theme={null}
coval mutations list --agent-id ag_abc123
```

## Get Mutation

```bash theme={null}
coval mutations get --agent-id <agent_id> <mutation_id>
```

| Argument      | Type   | Required | Description     |
| ------------- | ------ | -------- | --------------- |
| `mutation_id` | string | **Yes**  | The mutation ID |

| Option       | Type   | Required | Description         |
| ------------ | ------ | -------- | ------------------- |
| `--agent-id` | string | **Yes**  | The parent agent ID |

```bash theme={null}
coval mutations get --agent-id ag_abc123 mut_xyz789
```

## Create Mutation

```bash theme={null}
coval mutations create --agent-id <agent_id> [OPTIONS]
```

| Option          | Type   | Required | Description                               |
| --------------- | ------ | -------- | ----------------------------------------- |
| `--agent-id`    | string | **Yes**  | The parent agent ID                       |
| `--name`        | string | **Yes**  | Mutation display name                     |
| `--description` | string | No       | Description of what this mutation changes |
| `--config`      | string | No       | JSON config overrides                     |

```bash theme={null}
# Create a mutation with config overrides
coval mutations create \
  --agent-id ag_abc123 \
  --name "Higher Temperature" \
  --description "Test with increased temperature" \
  --config '{"temperature": 0.9}'

# Create a prompt variation
coval mutations create \
  --agent-id ag_abc123 \
  --name "Formal Tone" \
  --description "Agent uses formal language" \
  --config '{"prompt": "You are a formal customer service agent. Always use professional language."}'
```

## Update Mutation

```bash theme={null}
coval mutations update --agent-id <agent_id> <mutation_id> [OPTIONS]
```

| Argument      | Type   | Required | Description               |
| ------------- | ------ | -------- | ------------------------- |
| `mutation_id` | string | **Yes**  | The mutation ID to update |

| Option          | Type   | Required | Description               |
| --------------- | ------ | -------- | ------------------------- |
| `--agent-id`    | string | **Yes**  | The parent agent ID       |
| `--name`        | string | No       | New display name          |
| `--description` | string | No       | New description           |
| `--config`      | string | No       | New JSON config overrides |

```bash theme={null}
coval mutations update --agent-id ag_abc123 mut_xyz789 \
  --config '{"temperature": 0.7}'
```

## Delete Mutation

```bash theme={null}
coval mutations delete --agent-id <agent_id> <mutation_id>
```

| Argument      | Type   | Required | Description               |
| ------------- | ------ | -------- | ------------------------- |
| `mutation_id` | string | **Yes**  | The mutation ID to delete |

| Option       | Type   | Required | Description         |
| ------------ | ------ | -------- | ------------------- |
| `--agent-id` | string | **Yes**  | The parent agent ID |

```bash theme={null}
coval mutations delete --agent-id ag_abc123 mut_xyz789
```

## Using Mutations in Runs

Pass mutation IDs when launching a run to test agent variations:

```bash theme={null}
# Test a single mutation
coval runs launch \
  --agent-id ag_abc123 \
  --persona-id per_xyz789 \
  --test-set-id ts_123456 \
  --mutation-id mut_001

# Test multiple mutations
coval runs launch \
  --agent-id ag_abc123 \
  --persona-id per_xyz789 \
  --test-set-id ts_123456 \
  --mutation-ids "mut_001,mut_002,mut_003"
```