Investigate. Edit. Compare.

English · Russian

Turn your agent’s failures into proposed changes to its skills and prompts. Evolution evaluates each change against your cases before selecting a version.

Try it without an API key → · Connect your agent · How it works

View the static example.

A better instruction starts with a specific failure.

The agent gives general retention advice without checking product data. Investigation identifies the missing query. The proposed skill now says to query the data and compare retention cohorts. Evolution tests the candidate; your checks decide whether it is selected.

You supply the agent, editable files, cases and scorer. Evolution preserves the selected files and the run history. A campaign can keep the current version.

Python 3.11.3+ · Beta 2.0.0b18 · Apache 2.0

Quickstart

Run a complete example without an API key. It uses a deterministic agent and scripted roles, so it verifies the wiring rather than real-agent quality. Use Python 3.11.3+ and Bash or Zsh.

1. Install this beta

git clone https://github.com/sb-ai-lab/evolution.git
cd evolution
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[tree]"
evo --version

Expect evo 2.0.0b18. Install from the documented beta checkout or a supplied wheel; a plain PyPI install may resolve to another release. If your checkout reports another version, follow that version’s documentation. Wheel installation is covered in the full guide.

2. Start the example service

In terminal 1, from the same evolution directory:

evo-target init ./demo
evo-target serve ./demo/manifest.json

Wait for a JSON line containing "status": "listening" and leave the service running. If port 8765 is busy, stop this service, change target.base_url in demo/manifest.json to an available loopback port, and restart it before the first campaign. If demo already exists, use a new directory name throughout these commands.

3. Run the campaign

Open terminal 2 in the same evolution directory and activate the same environment:

source .venv/bin/activate
evo tree conformance --manifest ./demo/manifest.json
evo tree evolve --manifest ./demo/manifest.json --run-dir ./demo/run-1 \
  > ./demo/result.json

Conformance should report "ok": true and "leaked": []. The campaign saves its result JSON in demo/result.json and its records in demo/run-1.

4. Inspect the selected files

python - <<'PYRESULT'
import json
from pathlib import Path

result = json.loads(Path("demo/result.json").read_text())
print("State:", result["terminal"])
print("Outcome:", result["finished"])
print("Champion:", result["status"]["final_champion"])
print("Files:", result["status"]["campaign_outcome"]["champion_path"])
PYRESULT
cat ./demo/seed/skills/SKILL.md
cat ./demo/run-1/artifacts/champions/v1/skills/SKILL.md

Expect a finished campaign with outcome completed, reason rounds_exhausted and Champion v1. The selected skill begins with IMPROVED; the original seed does not. The sample scorer rewards that marker, so this result demonstrates file flow and selection. It does not establish improvement for a real agent.

Stop the service with Ctrl+C in terminal 1 when finished. A continue: hint after success is optional guidance for a successor campaign. To repeat the example, start the service and use a new run directory.

The full Quickstart explains generated files and troubleshooting. For an unfamiliar failure, start with diagnosis and recovery.

What happens between an edit and selection?

The Grouper gathers observed failures; the Reflector investigates a group; the editor changes a copy of permitted files. Preliminary checks compare the Candidate on affected training cases. A finalist then faces fresh measurement across training cases and comparison with the current Champion. A campaign can finish without a promotion. Read the comparison rules.

Evolution changes instruction files, without training model weights. Training evidence guides edits and selection; held-out cases measure the fixed selected version separately.

Bring your own agent

Your agent needs a Target Service wrapper that loads each supplied file snapshot and returns the agent’s behavior. Its model-provider URL is a separate connection. The integration guide and complete offline backend show what to implement.

Keep going

• Run and inspect campaigns, including separate held-out evaluation.
• Diagnose a stopped run.
• Look up commands, campaign settings or the backend API.
• Browse all guides, contribute or report an issue.

The separate task and skill workflow uses saved versions and traces. Before upgrading this beta, read the release notes and recovery guidance.