Core loop
One step, and the things that make a step possible. Nothing here knows about a specific tool or model.
Defines executable agents and their lifecycle.
Owns Agent processes, mailboxes, signals, topic subscriptions, shared run budgets and lifecycle cleanup. Delegation is optional and governed by the selected capability scope.
Defines shared invocation context and session-scoped project state.
Defines provider-neutral conversation messages, multimodal content parts, tool calls, and function-call payloads.
Defines the normalized `Response` and `ResponseType` returned across Agents, Tools, Skills, Connectors, and Environments.
Context & memory
What the model is shown, and what a finished run leaves behind.
Provides the model registry, role-based selection, API-key pooling, and provider-neutral generation interface.
Loads, versions, and renders HTML-native prompts and reusable prompt modules.
Stores and retrieves durable context derived from agent execution history.
Captures structured lifecycle events, persists them, and fans them out to subscribers.
Projects authoritative Trace events to optional observability backends without changing execution.
Projects agent runs into reward-annotated, step-level training records and exports formats used by supervised fine-tuning or reinforcement learning pipelines.
Capabilities
The families of thing a model can be given. Each is a registry with the same shape.
Defines atomic callable capabilities backed by Python implementations.
Discovers and executes reusable, filesystem-backed instructions stored as `SKILL.md` plus optional scripts, references, resources, and examples.
Defines stateful execution environments and their callable actions.
Integrates external capability providers, primarily MCP servers.
Outside services — OpenAI, Chroma, Tavily, YouTube, Composio — wrapped as plugins.
Models user-facing commands, their contexts, and command dispatch.
Retrieval-augmented generation (RAG) over named knowledge bases.
Runs a model-written program in its own interpreter and bridges the calls it makes back into this process, so a batch of tool work costs one turn instead of one turn per call.
Where work happens
Where file and process work actually happens — here, in a container, or on another machine.
Defines isolated command execution, managed sandbox processes, and staged project validation.
Keeps a shell alive between tool calls, so a directory change, an activated environment, an ssh hop or a REPL survives the call that made it.
Pure record/text transforms — the transform stage of a data pipeline.
One Jupyter Server per project, and one kernel the agent, the Science REPL and JupyterLab all share.
Provides the E2B backend integration point through `e2b_manager`.
Full VS Code (openvscode-server) in the browser, one container per gateway session, editing the same workspace the agent edits.
Orchestration
Work that is more than one step, and the limits on how far it may go.
This package turns reviewable HTML into a dynamic multi-agent program.
Visual flow editor.
Models tasks and goals — their priorities, statuses and authority — loads task documents, and resolves CLI task input into normalized records.
Runs work in the background and lets the agent collect it later — and holds reminders that come due — so a long command costs a step to start rather than a step spent waiting.
Maintains a compact plan/index.md and a detailed plan.md. The index enters live context; explicit plan mode additionally restricts actions until a person approves.
Defines enforceable runtime budgets and status reporting.
Evolution
How a component is created at runtime, versioned, judged, and removed again.
Manages generated extension manifests and their promotion into the active framework.
Loads generated Python source into controlled runtime modules and derives callable metadata such as parameters, argument models, and function-calling schemas.
Tracks versions of evolvable framework entities and generates validated next versions.
Every callable Manager exposes `get_schema(name, action=None, format="json")`.
Provides versioned benchmark definitions and the manager used to load and execute them.
Contains dataset adapters used by the Benchmark module, including AIME, GPQA, GSM8K, LeetCode, HLE, DeepWeb, and ProgramBench.
Infrastructure
The parts every other module leans on, and the one door the outside world uses.
Defines the versioned boundary used by interactive clients to communicate with AgentEvolver.
Loads Python configuration files into the global `config` object and validates assembled framework configuration before runtime initialization.
Single source of truth for the on-disk layout: one table declaring every path the framework writes, resolved through path_manager.
Central port registry — names the framework's well-known default ports and hands out / records host ports, persisted to output/.runtime so bindings are de-conflicted and discoverable.
Provides the framework logger, log levels, display colors, and session-ID context used to correlate output across asynchronous operations.
Evaluates command and filesystem operations against explicit permission modes and policies.
Provides lifecycle interception points for tracing, compaction, registration, promotion, and other cross-cutting behavior.
Contains dependency-light helpers shared across modules: path assembly, file locking, concurrency, names, strings, URLs, screenshots, tokens, argument parsing, and plan models.
Pins the bytes of an image the agent read and re-attaches it to every later request, so an image enters the model's context and stays there instead of vanishing with the step that read it.
Deploys web artifacts from controlled source directories and records their URLs, health, resources, and lifecycle state.
Lines of dialogue inside a project — their transcripts and their identity.
This directory contains dependency-free browser renderers for AgentEvolver's HTML-native artifacts.
The shape they share
Reading one module tells you how to read the rest. Four files, and the manager always spells removal the same way — unregister(name) — which is what lets one scope own registrations across several of them and take them all back out.
agentevolver/<module>/
README.md # YAML frontmatter + what this module owns (gated)
types.py # the data and the contract — no I/O
server.py # the singleton manager: register / get / list / unregister
__init__.py # the public surface