Skip to main content
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.
The base agent always runs. Mutations are additional variants that run alongside it.

​
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. 
// 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 TypeOverridable Fields
WebSocketEndpoint, 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)
Only override the fields you want to test. Fewer overrides make results easier to interpret.

​
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.
Archived mutations cannot be restored. Create a new mutation if you need the same configuration again.

​
API and CLI

Mutations can also be managed programmatically:

REST API

Create, list, update, and delete mutations via the v1 API

CLI

Manage mutations from the command line