Mutations - Coval Documentation

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. create and update also accept --input-json (inline JSON, @file, or - for stdin); explicit flags override fields from the JSON. See Input JSON.

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)

Output columns: ID, NAME, PARAMETERS, CREATED

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 name, unique per agent (1-200 characters)
`--description`	string	No	Description of what this mutation changes (max 2000 characters)
`--config`	JSON	No	JSON config overrides, deep-merged with the parent agent’s config (max 10 KB)

# 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 name, unique per agent (1-200 characters)
`--description`	string	No	New description (max 2000 characters)
`--config`	JSON	No	New JSON config overrides, deep-merged with the parent agent’s config (max 10 KB)

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"