Skip to main content

Evolution — Agent Self-Improvement

Evolution is FleetQ's continuous optimization loop. Based on experiment results and performance metrics, the platform generates proposals to improve agent configurations, skills, and workflows — and lets your team review them before any changes are applied.

Scenario: An agent's average cost per run has crept up 40% over two weeks. Evolution analyzes the pattern, identifies an over-specified system prompt, and proposes a leaner alternative — including an estimated cost saving. A team admin reviews and applies it in one click.

How it works

After experiments complete, the system analyzes performance metrics, cost data, and output quality. It generates EvolutionProposal records suggesting targeted improvements: better prompts, different models, adjusted parameters, or new skill combinations. Each proposal includes a rationale, expected impact, and risk level so reviewers have full context before deciding.

Proposal lifecycle

Proposals move through three states. No changes are applied without an explicit human decision.

State Description
pending Generated and waiting for analysis or team review.
analyzed Analysis complete; proposal is ready to apply or reject.
applied / rejected Terminal state — changes were applied or the proposal was dismissed.

Reviewing proposals

Navigate to Evolution in the sidebar (or /api/v1/evolution via API) to see all open proposals. Each proposal shows:

  • What changed — a diff of the proposed configuration.
  • Why — the performance signal that triggered the suggestion.
  • Expected impact — projected cost saving, quality improvement, or latency reduction.
  • Risk level — low / medium / high, based on the scope of the change.

Click Apply to commit the change or Reject to dismiss it. Only Admin and Owner roles can apply or reject proposals.

Analyzing performance

The evolution_analyze MCP tool triggers on-demand analysis for a specific agent or experiment. The system examines:

  • Response quality scores from evaluations
  • Cost per run over time
  • Latency (p50 / p95)
  • Error and retry rates
  • User feedback signals
Trigger analysis via MCP 
# Analyze a specific agent
evolution_analyze agent_id=YOUR_AGENT_ID

# Analyze a completed experiment
evolution_analyze experiment_id=YOUR_EXPERIMENT_ID

Applying proposals

evolution_apply applies the proposed changes to the agent or skill configuration. Changes are versioned and reversible — use agent config history or skill versions to roll back if the applied change doesn't perform as expected.

Apply via API 
POST /api/v1/evolution/{id}/apply
Applied changes create a new entry in the agent's config history. Use GET /api/v1/agents/{id}/config-history or the agent_rollback MCP tool to revert if needed.

MCP tools

Tool Description
evolution_proposal_list List all evolution proposals, optionally filtered by status.
evolution_analyze Trigger performance analysis for an agent or experiment.
evolution_apply Apply a proposal's suggested changes to the target entity.
evolution_reject Reject a proposal and mark it as dismissed.

API endpoints

Method Path Description
GET /api/v1/evolution List all evolution proposals (cursor-paginated).
GET /api/v1/evolution/{id} Retrieve a single proposal with full diff and rationale.
POST /api/v1/evolution/{id}/apply Apply the proposal's changes to the target entity.
POST /api/v1/evolution/{id}/reject Reject and dismiss the proposal.