Skip to main content
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]
OptionTypeRequiredDescription
--agent-idstringYesThe parent agent ID
--page-sizenumberNoResults per page (default: 50)
Output columns: ID, NAME, PARAMETERS, CREATED 
coval mutations list --agent-id ag_abc123

​
Get Mutation

coval mutations get --agent-id <agent_id> <mutation_id>
ArgumentTypeRequiredDescription
mutation_idstringYesThe mutation ID
OptionTypeRequiredDescription
--agent-idstringYesThe parent agent ID
coval mutations get --agent-id ag_abc123 mut_xyz789

​
Create Mutation

coval mutations create --agent-id <agent_id> [OPTIONS]
OptionTypeRequiredDescription
--agent-idstringYesThe parent agent ID
--namestringYesMutation display name
--descriptionstringNoDescription of what this mutation changes
--configstringNoJSON 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]
ArgumentTypeRequiredDescription
mutation_idstringYesThe mutation ID to update
OptionTypeRequiredDescription
--agent-idstringYesThe parent agent ID
--namestringNoNew display name
--descriptionstringNoNew description
--configstringNoNew 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>
ArgumentTypeRequiredDescription
mutation_idstringYesThe mutation ID to delete
OptionTypeRequiredDescription
--agent-idstringYesThe 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"