The concepts AgentEnv Framework is built from and why each one exists, starting with environments
AgentEnv Framework lets you build environments for AI agents, run agents in them and check what
they did. Seven concepts make it up: environments, artifacts, agents, tasks, the registry,
plugins and sandboxes. This page defines each one and why it exists, in that order.
An environment is the world an agent acts in: usually a server that offers tools over the Model
Context Protocol (MCP) and holds the state they change, such as an email inbox that an agent can
search and send from. You write it as a subclass of AgentEnvEnvironment, like the EmailEnv
below, and it describes itself in an environment card. You register it as an env under an id, with
a new version on every registration, and each deployment of an env is an env instance. A multi
env composes several envs into one, such as the inbox and a contacts book.
Environments follows EmailEnv through each of these.
An artifact is data that the framework stores and versions, such as a set of emails, a file, a
Docker image or a VM image. You register artifacts on their own, independently of any environment, and every
registration adds a new version. That decoupling lets you take one set of artifacts, such as a
company's data, and load it into different environments, such as an MCP environment for
tool-calling agents and a computer-use (CUA) environment for agents that work in a browser. Because
the artifacts are separate, you can iterate on them without touching the environments that load
them. Artifacts follows one company's data through each of these.
An agent is what acts in an environment: anything that speaks the agent-to-agent protocol (A2A),
written as an AgentEnvAgent or wrapping a harness such as Claude Code, Codex, Gemini, Hermes
Agent, OpenCode, pi, OpenHands, Letta Code, Pydantic AI or Browser
Use. Agents are separate from envs and tasks, so the same task runs
unchanged with any agent, and one task can deploy several agents that message each other.
Agents covers how they plug in.
A task is a run you can repeat: a directed acyclic graph (DAG) of task steps that deploy envs and
agents, prompt the agents, grade their work with verifiers and collect what they made. The
framework ships nearly 50 built-in steps, and you can register your own as a
Python class. A task is a JSON list of steps, so you write one without code.
Tasks and steps covers how a run executes.
The registry is where the framework keeps what you register and what your runs record, in four
stores: a document store for versioned records and run history, an object store for
the bytes they point at, an image store for container images, and a secret store for the secret:
references in your config. All four are local by default, and config.toml swaps any of them for AWS or Google Cloud stores, or a
store of your own.
The AgentEnv Framework comes with some strong building blocks, but you may find the need to add more.
Plugins let you write your own custom env types (e.g a CUA env), custom task steps for your DAG, your
own custom stores, custom env topologies, and more.
A sandbox is the isolated machine or container that your env or agent can run in. Your machine's
Docker is the default sandbox provider, but you may also choose to use a sandbox provider such as
Modal's, CoreWeave, E2B, Sail,
Tensorlake, Tenki, Vercel, smol machines, boxd, Daytona, boat, Agent37, Lume, or a sandbox provider of your own creation via a
plugin. View all available sandbox providers
here.
Write the environment as an AgentEnvEnvironment.Register it under an env id. Every put adds a new version.Deploy a version on any sandbox. The deployment is an env instance.The instance’s card lists its interfaces: MCP, the data plane, /step and a CLI.The env’s EnvironmentProvider sets its topology: gateway, server, or your own.Load and read data, and drive triggers, the clock and per-role tool access.Tear it down and deploy again. Every deployment gets its own instance id.
Write the environment as an AgentEnvEnvironment.
Register it under an env id. Every put adds a new version.
Deploy a version on any sandbox. The deployment is an env instance.
The instance’s card lists its interfaces: MCP, the data plane, /step and a CLI.
The env’s EnvironmentProvider sets its topology: gateway, server, or your own.
Load and read data, and drive triggers, the clock and per-role tool access.
Tear it down and deploy again. Every deployment gets its own instance id.
Click any part to learn more
ClickTap any part to learn more
Collect a company’s data as files: its emails, its chat messages and its CRM as SQL.Put each file as an environment artifact named for its environment: email, chat, crm.Bundle the three into a universe, acme, which pins the version of each.Load acme into a support desk: each server gets the artifact with its name.Load the same acme into a sales office, and a browser office for computer-use agents.Fix a refund in the emails: acme-email v2, and acme v2 to pin it. No env changes.Load acme v2 into the same envs. acme:1 is unchanged, so old runs reproduce.
Collect a company’s data as files: its emails, its chat messages and its CRM as SQL.
Put each file as an environment artifact named for its environment: email, chat, crm.
Bundle the three into a universe, acme, which pins the version of each.
Load acme into a support desk: each server gets the artifact with its name.
Load the same acme into a sales office, and a browser office for computer-use agents.
Fix a refund in the emails: acme-email v2, and acme v2 to pin it. No env changes.
Load acme v2 into the same envs. acme:1 is unchanged, so old runs reproduce.
Click any part to learn more
ClickTap any part to learn more
Write an agent as an AgentEnvAgent, or wrap a harness you already use. Either way it speaks A2A.Register each one under an agent id with agent-env a2a-agent put. Every put adds a new version.A task’s deploy_agent step deploys a version in a sandbox of its own. The deployment is an agent instance.deploy_agent sends the agent the env’s MCP URL, so it can call email_search and send.prompt_agent messages the agent over A2A, then records its reply and its trajectory.Run the same task with another agent. Each run deploys a new instance of the same env version.Deploy several agents in one task. peer_agents tells each where the others are, and they message each other over A2A.
Write an agent as an AgentEnvAgent, or wrap a harness you already use. Either way it speaks A2A.
Register each one under an agent id with agent-env a2a-agent put. Every put adds a new version.
A task’s deploy_agent step deploys a version in a sandbox of its own. The deployment is an agent instance.
deploy_agent sends the agent the env’s MCP URL, so it can call email_search and send.
prompt_agent messages the agent over A2A, then records its reply and its trajectory.
Run the same task with another agent. Each run deploys a new instance of the same env version.
Deploy several agents in one task. peer_agents tells each where the others are, and they message each other over A2A.
Click any part to learn more
ClickTap any part to learn more
An analyst charts q3.csv; a judge agent deployed beside it grades the collected q3.png.Deploy email, load its inbox while the agent deploys, then prompt it and check what it sent.A second agent plays Dana, and prompt_agent runs their conversation for up to six turns.Two envs with an agent on each, peered so the planner can hand the email to the writer.A virtual clock runs a week in two minutes, and a trigger locks send at Friday’s deadline.25 agents in one office: 20 customers, 3 support agents and a world agent that runs triggers.
An analyst charts q3.csv; a judge agent deployed beside it grades the collected q3.png.
Deploy email, load its inbox while the agent deploys, then prompt it and check what it sent.
A second agent plays Dana, and prompt_agent runs their conversation for up to six turns.
Two envs with an agent on each, peered so the planner can hand the email to the writer.
A virtual clock runs a week in two minutes, and a trigger locks send at Friday’s deadline.
25 agents in one office: 20 customers, 3 support agents and a world agent that runs triggers.
Click any part to learn more
ClickTap any part to learn more
put builds the image on your machine, and pushes it to the image store as mcp-server-email:v1.It saves the same image as a tarball in the object store, with the files its build copied in.A docker_image artifact, mcp-server-email version 1, records both in the document store.The env email gets version 1 in envs, pinned to that image artifact. The next put adds version 2.
put builds the image on your machine, and pushes it to the image store as mcp-server-email:v1.
It saves the same image as a tarball in the object store, with the files its build copied in.
A docker_image artifact, mcp-server-email version 1, records both in the document store.
The env email gets version 1 in envs, pinned to that image artifact. The next put adds version 2.
Click any part to learn more
ClickTap any part to learn more
A plugin is a Python package whose pyproject.toml declares agent_env.* entry points: here an env, a task step and a CLI command.agent-env plugin add installs it with the installer that owns agent-env’s environment, here a uv tool, and then checks it.With no config to write, each entry point takes its place next to the built-ins, under its entry-point name.agent-env plugin list shows each package, what it provides and whether all of it took effect.A package whose task step is named deploy_env, a built-in’s name, fails the check that plugin add makes, so the add rolls the environment back.
A plugin is a Python package whose pyproject.toml declares agent_env.* entry points: here an env, a task step and a CLI command.
agent-env plugin add installs it with the installer that owns agent-env’s environment, here a uv tool, and then checks it.
With no config to write, each entry point takes its place next to the built-ins, under its entry-point name.
agent-env plugin list shows each package, what it provides and whether all of it took effect.
A package whose task step is named deploy_env, a built-in’s name, fails the check that plugin add makes, so the add rolls the environment back.
Click any part to learn more
ClickTap any part to learn more
--sandbox local, the default, runs the env and the agent as containers on your machine’s Docker.--sandbox modal runs each of the env’s servers, and the agent, in a Modal container of its own.--sandbox modal_vm boots a Modal VM for the env and one for the agent, and runs their containers inside.--sandbox coreweave boots a CoreWeave Sandbox with Docker inside for the env, and runs the agent’s own image in a Sandbox of its own.--sandbox e2b boots an E2B sandbox for the env and one for the agent, each a VM with Docker inside.--sandbox sail_vm boots Sailboxes, root VMs with Docker inside, and keeps the agent’s model key out of them.--sandbox tensorlake boots Tensorlake MicroVMs from a public image with Docker inside.--sandbox tenki boots a Tenki VM for the env and one for the agent, each with Docker inside.--sandbox vercel boots a Vercel Sandbox for the env and one for the agent, each with Docker inside.--sandbox smol_vm boots a SmolVM microVM on your own machine for the env and one for the agent, each with Docker inside.--sandbox boxd boots a boxd machine for the env and one for the agent, each a VM with Docker already running.--sandbox daytona boots a Daytona sandbox for the env and one for the agent, each running a Docker daemon of its own.--sandbox boat boots a boat sandbox for the env and one for the agent, each an Ubuntu VM with Docker already running.--sandbox agent37 boots an Agent37 VM for the env and one for the agent, each with Docker already running.A provider of your own, installed as a plugin, takes the same env and agent with --sandbox <name>.
--sandbox local, the default, runs the env and the agent as containers on your machine’s Docker.
--sandbox modal runs each of the env’s servers, and the agent, in a Modal container of its own.
--sandbox modal_vm boots a Modal VM for the env and one for the agent, and runs their containers inside.
--sandbox coreweave boots a CoreWeave Sandbox with Docker inside for the env, and runs the agent’s own image in a Sandbox of its own.
--sandbox e2b boots an E2B sandbox for the env and one for the agent, each a VM with Docker inside.
--sandbox sail_vm boots Sailboxes, root VMs with Docker inside, and keeps the agent’s model key out of them.
--sandbox tensorlake boots Tensorlake MicroVMs from a public image with Docker inside.
--sandbox tenki boots a Tenki VM for the env and one for the agent, each with Docker inside.
--sandbox vercel boots a Vercel Sandbox for the env and one for the agent, each with Docker inside.
--sandbox smol_vm boots a SmolVM microVM on your own machine for the env and one for the agent, each with Docker inside.
--sandbox boxd boots a boxd machine for the env and one for the agent, each a VM with Docker already running.
--sandbox daytona boots a Daytona sandbox for the env and one for the agent, each running a Docker daemon of its own.
--sandbox boat boots a boat sandbox for the env and one for the agent, each an Ubuntu VM with Docker already running.
--sandbox agent37 boots an Agent37 VM for the env and one for the agent, each with Docker already running.
A provider of your own, installed as a plugin, takes the same env and agent with --sandbox <name>.