From nothing to a trajectory

00Build the right mental model first

AgentEvolver is not just a chat interface and not a trainer. It is an agent runtime that connects four loops: execute work, observe every important event, evaluate the result, and preserve reusable improvements. The current release evolves capabilities and produces training-ready records; integrated weight training and model feedback are the destination, not a hidden feature.

The end-to-end direction

01Install

Python 3.11 or newer. The editable install is the one to use while reading the code, because every module is discovered by import and an editable tree keeps that honest.

git clone https://github.com/DVampire/AgentEvolver.git
cd AgentEvolver
pip install -e ".[dev]"

Verify. The suite should be green before you change anything, so that the first red you see is yours:

pytest -q

02Configure a model

Models are selected by role rather than by name at each call site, so swapping the model behind "the main one" is a config change and not a search-and-replace.

# .env
OPENAI_API_KEY=sk-...
# or any provider the model registry knows — see agentevolver/model/

03Choose the entry point that matches your goal

All interactive surfaces converge on one Gateway backend, but they serve different workflows. Start with the smallest surface that can prove your setup.

04Run a task

Two development processes, one backend path: Gateway owns runtime state and the Vite server serves the UI. The browser opens the UI port and connects to Gateway's WebSocket port; the convenience script starts and shuts down both together.

# terminal 1
agentevolver serve --transport websocket --port 9876

# terminal 2
cd frontend && npm install && npm run dev

Open the UI, type a task, and watch the middle column. What you are seeing is not a transcript being streamed at you — it is the log being rendered as it is written.

05Read the session output tree

A run should be inspectable without the UI that created it. Paths are resolved centrally and rebound to the session, so generated state stays under output/ while promoted, shareable extensions stay under extension/.

• Use identifiers, not timestamps, to correlate. Session id groups a project interaction; task id names one run and is the key used for trajectory reward/export.
• Do not edit generated state as configuration. Change configs/*.py or versioned extensions; output/ is evidence and runtime state.
• Do not put promoted extensions in the package tree. Separation keeps generated changes reviewable and reversible.

06Add a tool

One file, one export, one test. The agent can use it on the next run — there is no registry file to edit.

# agentevolver/tool/default/word_count.py
class WordCountTool(Tool):
    """Count the words in a file."""

    name: str = Field(default="word_count")          # a CLASS field
    description: str = Field(default="Count words in a UTF-8 text file.")
    mutates: bool = Field(default=False)             # reports only; never writes

    async def __call__(self, path: str, ctx=None, **kwargs) -> Response:
        with open(path, encoding="utf-8") as handle:
            count = len(handle.read().split())
        return Response(type=ResponseType.TOOL, success=True,
                        message=f"{count} words", data={"words": count})

# agentevolver/tool/default/__init__.py
from .word_count import WordCountTool

Verify. Registration is what to check, not the import:

python -c "
import asyncio
from agentevolver.tool import tool_manager
asyncio.run(tool_manager.initialize())
print('word_count' in asyncio.run(tool_manager.list()))"

07Read and export the trajectory

This is the step that explains the project. A run leaves a step-level record — what the model saw, what it decided, what came back, what it cost, and what the attempt was ultimately worth.

output/<owner>/sessions/<session>/log/trajectory/<task>.jsonl

line 1   the header: session, task, agent, outcome, reward
line 2+  one step each: messages sent · reasoning · actions · usage

Two properties are worth checking yourself, because they are what make the record usable as training data rather than as telemetry:

• Failures are in there. A model call that failed twice and succeeded on the third try records all three. A record that showed only the success would describe a model that got it right first time — a sample that lies about what happened.
• The reward reaches every step. A benchmark scores a run after it ends, and the score is backfilled to the steps that produced it. A trajectory with no reward is a run the corpus counts as worth nothing.

What one step means

{
  "step_number": 2,
  "messages_sent": [...],   // z_t: effective prompt, after hooks/compaction
  "reasoning": "...",       // model text/thinking used as assistant target
  "actions": [...],         // a_t: native tool calls, names + JSON arguments
  "observations": [...],    // o_t: result/error for every attempted action
  "usage": {...},           // input/output/cache tokens and cost when available
  "reward": 0.8             // r_t: task score, backfilled after evaluation
}

Load a finished run and export both formats

import json
from agentevolver.trajectory import trajectory_manager, VerlFormat

trajectory = trajectory_manager.load("output/.../log/trajectory/<task-id>.jsonl")
assert trajectory is not None

# One OpenAI-chat record per step; assistant tool_calls stay native.
sft_records = trajectory.to_sft_records()

# Text-level VERL episodes. A trainer provider adds tokenizer-specific ids/masks.
rl_records = trajectory.to_rl_records(VerlFormat())

print(json.dumps(sft_records[0], ensure_ascii=False, indent=2))

08Operate the Web UI

The four surfaces are views of one project, not four copies. Chat observes the event log, Canvas authors workflows, IDE edits the workspace, and Science shares a live Jupyter kernel.

Open the complete Web UI guide, including startup, state model, Canvas, IDE and Science →

09Choose sandbox and permission boundaries deliberately

Permission answers whether an operation is allowed; Sandbox contains where it can act; Plan mode prevents mutation before approval. These layers complement one another and should not be treated as aliases.

10Understand a component evolution round

Evolution is evidence-driven component engineering, not arbitrary self-modification. A recurring or measured gap justifies a candidate; the candidate stays outside the core and must cross explicit gates.

11Troubleshoot from the boundary inward

Recommended order: reproduce with the smallest entry point → inspect Gateway/manager initialization → inspect Trace → inspect the owning module’s README and schema → then inspect provider or sandbox logs.

12Where to go next