Mutants (AI Schema Evolution)
AI-proposed schema changes with human approval before anything touches production.
What you'll learn
- ✓GET /v1/mutants — list pending proposals
- ✓POST /v1/mutants — submit a proposal with changes array
- ✓change types: add_field (with default), rename_field, deprecate_field
- ✓POST /v1/mutants/:id/approve — human approves and applies
- ✓POST /v1/mutants/:id/reject — reject with reason
- ✓Automatic rollback if validation fails after apply
Propose a Mutant to add last_login_at to users agent. Approve it. Verify schema was updated.
Interactive Walkthrough
What you'll learn
Let an AI agent propose, test, and apply schema changes — without you writing migration scripts.
What Mutants do
A Mutant is a proposal to change how data is structured in an agent. It can: - Add a new required field with a default value - Rename a field across all records (via a new record with the new field) - Deprecate a field - Change an enum's valid values
A human administrator must approve every Mutant before it is applied. Rollback is automatic if validation fails.
List pending Mutant proposals
curl -s http://localhost:7475/v1/mutants \
-H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \
| python3 -m json.toolSubmit a Mutant proposal
curl -s -X POST http://localhost:7475/v1/mutants \
-H "Content-Type: application/json" \
-H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \
-d '{
"agent_id": "users",
"description": "Add verified_email field — default false for existing records",
"changes": [
{
"type": "add_field",
"field": "verified_email",
"default": false
}
]
}' | python3 -m json.toolApprove a Mutant
curl -s -X POST http://localhost:7475/v1/mutants/<MUTANT_ID>/approve \
-H "Authorization: Bearer spx_root_YOUR_ROOT_KEY"Reject a Mutant
curl -s -X POST http://localhost:7475/v1/mutants/<MUTANT_ID>/reject \
-H "Content-Type: application/json" \
-H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \
-d '{"reason": "Need to discuss naming in team meeting first"}'Challenge
Propose a Mutant to add a last_login_at field to the users agent. Approve it. Verify the schema was updated via GET /v1/agents/users/schema.
---