AgentEvolver orchestrates specialist agents, evolves reusable components, and captures reward-annotated trajectories for SFT/RL—connecting task execution to a future train, evaluate, and serve loop.
Specialists act in one project
Trace every meaningful event
Tests, judges and benchmarks
Versioned capabilities, reversible
Rewarded SFT/RL trajectories
Update weights, gate, feed back
The MetaAgent delegates today's work. When tests or review expose a reusable gap, an evolution loop can turn the missing method into a component for tomorrow.
Evolution is constrained and evaluated. The current release captures training-oriented SFT/RL records but does not yet update weights, manage checkpoints, and feed a trained model back into serving inside one run.
The value is not a large capability count. It is the way orchestration, evaluation, inspectability, and rollback fit together.
A failed check, recurring structural defect, or measured quality ceiling must establish the need. The normal response to a first fixable error is still to fix it.
Prompts, workflows, task documents, memory reports and per-step snapshots are complete HTML documents — executable by the runtime and browsable, diffable, reviewable by a human.
Hand-written built-ins remain in the package. Evolved components are staged, versioned, promoted, and rolled back outside it, limiting the mutation surface.
Step, token and wall-time limits aren't just kill-switches: the remaining budget is rendered into the prompt every step as NORMAL / TIGHT / CRITICAL, so the agent plans around it instead of being cut off.
Chat, a visual flow canvas, real VS Code in the browser, and a Science workstation with a live Jupyter kernel — all editing the same workspace, over one WebSocket protocol.
TrajectoryHook records the effective prompt, native tool-calling target, observations, token use, and late-arriving reward—then exports SFT or pluggable RL formats such as VERL.
A long command, a terminal send, or a delegated sub-agent starts in the background and hands back a job id; the agent collects the output when it wants it. A step spent blocking is a decision the agent never got to make.
The model can write a program instead of emitting one tool call per turn. Its calls return through a guarded dispatch, and the program runs in its own interpreter — no framework object is one import away from model-written code.
In plan mode a run may read, search and reason, and nothing else. The gate reads what a capability declared about itself — mutates: false, or a read-only permission mode — never its name. One that declared neither is refused, bash_tool included.
The capability catalogs are frozen at their first render and sent ahead of the volatile agent state, with a cache breakpoint after them. Measured on one run: 72,647 of about 98,800 input tokens per step served from cache, against none before.
AgentEvolver is designed for work where reusable methods, specialist coordination, and auditability matter more than minimum latency.
Extensions compound over time, but their contracts, evaluation data, and versions need ownership.
Specialist agents and baseline comparisons improve coverage while increasing model calls and wall time.
Reversible changes reduce risk. They do not make an unverified extension safe or correct.
The MetaAgent plans and dispatches work over the Agent Bus to specialist sub-agents that run in parallel and return results for evaluation.
Runtime is how messages move; protocol is what a conversation means. Spawning an agent wraps it in a handle with its own inbox and a pump that drains it — which is what makes a running agent something you can talk to, pause, and pick back up.
spawnWrap a live agent in a ref: inbox, pump task, status, pending reply.sendFire-and-forget a message into the inbox.ask · invokeRun it and await a typed Response.suspend · resumePark a coroutine on a key; anyone elsewhere can wake it by that key.publish · subscribeFan a message out to every running subscriber of a topic.stop · cancel · pauseGraceful stop drains first; control messages reach a mid-flight agent.Escalation is the clearest use of suspend/resume: a blocked sub-agent asks its parent and parks itself, costing nothing while it waits, and carries on the moment an answer arrives.
EscalationMessage to its parent — reason, situation, and what it suggests doing.task_id. The coroutine holds no loop and burns no budget while it waits.reply(task_id, guidance) resolves that future, and tells the caller whether anyone was actually still waiting.One detail that had to be got right: a caller's timeout on ask must not cancel the future the agent owns. Cancelling the shared future would turn a normal late completion into an InvalidStateError and take the long-lived pump down with it — so the wait is shielded, and a slow answer is merely late, not fatal.
For each evolvable component type, specialized agents create, judge, and refine extensions without treating the hand-written core as mutable working memory.
extension/; an optimizer rewrites an existing evolvable one in place. Both take the target by name.Absence of visible defects is not evidence the work is good — usually it means nobody looked. Until a check has run and failed, the right move is to go get the signal, never to evolve.
The task needs an operation no tool, skill or connector provides, and retrying with the existing ones cannot work. "The agent didn't think to do it" does not count.
The same agent fails the same way twice or more despite corrective guidance. One dispatch can never satisfy this — re-dispatch with explicit guidance first and see if it returns.
Output is systematically below bar on a dimension you have actually measured, because no method exists to do better. If you cannot name the measurement, you have signal-gathering to do.
enable_evolving blocks it at registration; generate an extension/ capability instead.Hand-written built-ins live in agentevolver/. Evolved components live in an external extension/ tree, loaded and versioned by the ExtensionManager. This limits where evolution writes and makes rollback possible; evaluation is still required.
Trajectory is the bridge between using a model and improving one: it preserves the exact behavior seen at inference, attaches evaluation rewards, and projects the result into SFT or RL records.
z_tThe effective messages actually sent to the modela_tReasoning plus native tool calls—the byte-faithful assistant targeto_tResults and errors returned by every actionr_tA benchmark or evaluator reward, backfilled after the runComponent evolution gives agents new methods immediately. Model training internalizes successful behavior over time. AgentEvolver's end-state connects both through the same tasks, rewards, evaluations, and deployment controls.
Status: capture, reward backfill, JSONL persistence, SFT export, and RLFormat/VERL export exist today. The in-system trainer, checkpoint lifecycle, and trained-model feedback are planned integrations.
Prompts, workflows, task documents and step snapshots are complete HTML documents — executed by the runtime and rendered in a browser from the same bytes. There is no "export to HTML" step that can drift.
prompt/default/<agent>.html — run by prompt_manager, styled by prompt.cssworkflow/default/<name>.html — compiled by WorkflowCompiler into the runtimeexamples/tasks/*.html — loaded by task/loader.pyFileSystemMemory — a JSON twin backs the runtime, the HTML is for you<log_root>/messages/<agent>/NNNN.html — every step, in the same stylesheet as the promptEvery callable manager implements the same get_schema() — json returns the exact function-calling object sent to the model, md returns a human-readable contract. The prompt carries only a compact roster; full schemas travel in the request.
Reasoning + execution loop: 8 actors, 7 generators, 7 evaluators, 7 optimizers.
One atomic operation — bash, file r/w/edit, git, grep, web fetch, background jobs, persistent terminals, language-server queries, deploy.
Filesystem-backed SOPs (SKILL.md + scripts) across 11 categories.
An external MCP server, each action projected as its own function.
Stateful worlds with @action methods — browser, Linux desktop, SSH, artifact renderer.
An executable HTML multi-agent program, compiled and run on the shared runtime.
Pluggable per-session memory, tiered — and itself evolvable.
One outside service each (OpenAI, Tavily, Chroma, Composio…), exposing 332 datasource tools.
RAG over named corpora (bm25, tfidf…) and pure record/text transforms.
Each self-registers with an mmengine registry — discoverable, swappable, evolvable:
A React workbench talks to the Python Gateway over a WebSocket: four workspaces on one session, a live capability catalogue, a desktop the agent can actually use, and a conversation column carrying the goal, the jobs still running, and every step of a run.
A task sandbox usually needs some network — the agent's brain has to reach a model endpoint — while the work itself must not reach the open internet. A boolean flag cannot express that.
default_allow=False a forgotten host fails closed.*_API_BASE, never hardcoded.Three more layers sit around this one: six sandbox backends for isolation, a permission manager that classifies command intent before anything runs, and a write-ahead ledger that force-removes containers a dead run leaked.
Datasets are read locally first, then snapshot-downloaded from HuggingFace on demand.
Everything above is what this is and why. These are how — written, bilingual, and kept next to the code they describe.
Six steps from an empty machine to reading the trajectory a run produced — each one verifiable before the next.
The four mechanisms the system rests on, with diagrams — including why one append-only log has two different readings.
All fifty-six modules and what each one owns, grouped into seven families.
The contributor guide: the module contract, how work is verified, and the invariants that were paid for in defects.
The state model and operating guide for Chat, Canvas, browser IDE, and the shared-kernel Science workstation.
Install the core, configure one model provider, and run locally. Add Docker, browser automation, or the Web UI only when you need them.
# 1 · core + dev environment bash scripts/install.sh conda activate agentos # no conda? use uv bash scripts/install.sh --uv # optional capability sets bash scripts/install.sh --extras browser bash scripts/install.sh --extras sandbox
# 2 · set one provider in .env GOOGLE_API_KEY='...' # 3 · run an inline task python examples/run_meta_agent.py \ --task "Reverse a string + add unit tests" # run from a task document python examples/run_meta_agent.py \ --task-file examples/tasks/qsar_egfr_experiment.html
The full setup, including Model X, Vault, provider variables, and optional dependencies, is documented in scripts/INSTALL.md →