Documentation Index
Fetch the complete documentation index at: https://docs.coval.dev/llms.txt
Use this file to discover all available pages before exploring further.
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
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) |
coval mutations list --agent-id ag_abc123
Get Mutation
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 |
coval mutations get --agent-id ag_abc123 mut_xyz789
Create Mutation
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 |
# 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
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 |
coval mutations update --agent-id ag_abc123 mut_xyz789 \
--config '{"temperature": 0.7}'
Delete Mutation
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 |
coval mutations delete --agent-id ag_abc123 mut_xyz789
Using Mutations in Runs
Pass mutation IDs when launching a run to test agent variations:
# 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"
