AgentEnv Framework is a Python SDK and CLI for building, deploying and running agentic environments and the tasks that grade agents inside them. Environments are containerized servers that speak the open agentenv-framework-protocol; AgentEnv Framework builds them into versioned images, deploys them behind a gateway, points an agent at them, and scores what the agent did.
Documentation: www.agentenvframework.com/docs covers environments, artifacts, agents, tasks, the registry and plugins.
Install
Both packages are on PyPI. You need Python 3.11.4 or newer and, to run environments locally, a running Docker daemon. With uv, install the agent-env command as a tool:
uv tool install agentenv-framework
agent-env run hello
agent-env run hello runs the built-in hello task, which needs no Docker, model or configuration. agent-env run echo-mcp needs Docker: it builds an MCP server from a Dockerfile, deploys it through the gateway and checks it by calling its tool. agent-env run lists both. To try hello without installing anything, run it with uvx:
uvx --from agentenv-framework agent-env run hello
Or install it with pip, into a virtualenv:
pip install agentenv-framework
To use the SDK in your own project, add it as a dependency with uv add agentenv-framework. The explorer, agent-env up, needs the explorer extra (uv tool install 'agentenv-framework[explorer]', or the same extra with uvx or pip) and an .agentenv/config.toml in the current folder or above it; an empty one keeps every local default. The tensorlake sandbox backend needs the tensorlake extra (pip install 'agentenv-framework[tensorlake]') and an api_key in [sandbox.providers.tensorlake.config]. Its sandboxes boot from the public image agentenv-dind-host-v1; set image there to use another registered Docker-capable image. The tenki sandbox backend needs the tenki extra (pip install 'agentenv-framework[tenki]') and an api_key in [sandbox.providers.tenki.config]; see its README.
A plain install runs on local stores and needs no cloud SDK. The cloud store backends are extras: aws for S3, Secrets Manager, DynamoDB and ECR (pip install 'agentenv-framework[aws]'), and gcp for Cloud Storage, Secret Manager, Firestore and Artifact Registry (pip install 'agentenv-framework[gcp]'). A config that names a backend without its extra fails, naming the extra to install.
The distribution is named agentenv-framework, the import package is agent_env and the command is agent-env. It depends on agentenv-framework-protocol, whose import package is agentenv_protocol, and installs it too.
To work on agent-env itself, install from a clone with uv:
git clone https://github.com/scaleapi/agentenv-framework && cd agentenv-framework
uv sync --extra dev
source .venv/bin/activate
Run a task from your own loop
An episode is one run of a task in which some of its agents are played from outside AgentEnv, by a training loop's model or any code of your own. AgentEnv runs the rest exactly as agent-env run does, deploying the envs, running the other agents and scoring, and waits at each of your agent's turns:
from agent_env.task import EpisodeSpec, Task
spec = EpisodeSpec.from_task(Task.get("my-task"), turn_timeout=900)
episode = await spec.start()
while (turn := await episode.next_turn()) is not None:
async with turn.tools() as tools: # the agent's env tools, called as its role
... # your model reads turn.system_prompt and turn.prompt, and acts with tools.list() and tools.call()
await turn.end(response="Done.")
scores = await episode.result() # every score the run recorded, by step id
The scores are the ones agent-env run reports, so making a reward of them is yours. trainer_agents= names the agents you play when the task prompts several, turn_timeout is each turn's deadline in seconds (the prompt's own timeout_seconds otherwise), episode.abandon(reason) stops a run early, and from_task names any step an outside player can't stand behind. Running tasks covers the rest.
Run agents in local microVMs
Install agentenv-framework[smol] and select the smol_vm sandbox provider in
.agentenv/config.toml:
[sandbox]
default = "smol_vm"
agent_default = "smol_vm"
Each agent and environment gets its own local SmolVM machine with a Docker daemon,
so workloads are isolated from the host Docker daemon. This needs a supported
Apple Silicon macOS or Linux host; on Linux, /dev/kvm must be available. On Apple Silicon,
build images for linux/arm64 (or provide their build contexts so SmolVM can rebuild them);
this provider does not install amd64 emulation in the guest. AgentEnv can still
use its default local object and image stores: guest containers can fetch local
object grants, and the VM forwards pulls from the host's loopback registry.
Cloud image and object stores continue to work through the same provider.
Plugins
A package of your own can add env types, providers, task steps and stores to agent-env, and agent-env plugin lists, checks, adds and removes installed plugins. The plugin docs show how.
Contribute, release, license
CONTRIBUTING.md is the contributor guide: open an issue before anything larger than a bug fix, one logical change per pull request with tests, pull request titles in the form type(scope): summary, an approving review from a code owner (CODEOWNERS) and green CI. AGENTS.md is the repository map and conventions file for contributors and coding agents.
Documentation map
| Document | Covers |
|---|---|
| www.agentenvframework.com/docs | the user guide: environments, artifacts, agents, tasks, the registry and plugins |
packages/agentenv-protocol/README.md |
wire contract, environment server SDK, A2A agent framework |
CONTRIBUTING.md |
development setup, test tiers, CI jobs, pull request rules |
AGENTS.md |
repository map, configuration and extension-point summary, conventions for contributors and coding agents |
SECURITY.md |
private vulnerability reporting and supported versions |
CODE_OF_CONDUCT.md |
Contributor Covenant |
.agentenv/config.example.toml |
the all-local configuration to copy |
.env.example |
a commented reference of the AGENT_ENV_* variables; agent-env never loads this file, export what you need yourself. Its AGENT_ENV_ENVIRONMENT line is read only by an installed plugin, never by agent-env |
Versioning and compatibility
The agentenv-framework distribution and agentenv-framework-protocol are versioned separately (0.9.x and 0.1.x today), both in their pyproject.toml; agent-env releases carry a vX.Y.Z tag, and agentenv-framework-protocol is bumped in the same commit and has no separate tag today. There is no agent_env.__version__ attribute; agent-env --version prints the installed version. Protocol extensions carry their version in the URI (urn:agentenv:clock/v1, urn:agentenv:agent-config/v1, urn:agentenv:trajectory/v1). One version can take more than one request shape: under v1 the skill, trajectory, snapshot and changelog extensions accept object-transfer requests next to their older shapes, and the request field lists on an agent's card say which ones that agent takes. Renamed CLI commands are removed outright; no deprecated aliases exist at this version. A pull request that breaks the classes and entry points plugins build on fails CI unless its title marks the break with !; beyond that, a written compatibility and deprecation policy does not exist yet.
Releases
A release is a version bump in both pyproject.toml files plus a vX.Y.Z tag. Maintainers cut releases: the bump is automated when a labelled pull request merges, so contributors do not edit version or push tags (see the Releases section of CONTRIBUTING.md). Each release publishes both packages to PyPI and gets a GitHub release whose notes list the pull requests merged since the previous one; there is no CHANGELOG.md.
Support, security, license
Ask questions in Discussions Q&A, and report bugs with the bug report form. Report vulnerabilities privately through the contact in SECURITY.md, not in public issues; only the latest release is supported, so reproduce against it first. Contributors follow CONTRIBUTING.md and the Code of Conduct; every pull request needs a code-owner review. agent-env and agentenv-framework-protocol are licensed under the Apache License 2.0; see LICENSE and NOTICE. Their third-party dependencies and those dependencies' licenses are listed in THIRD_PARTY_NOTICES.md.
Citation
To cite AgentEnv Framework, use the metadata in CITATION.cff. GitHub's Cite this repository button in the repository sidebar exports it as APA or BibTeX:
@software{agentenv_framework,
author = {Arakelyan, Edgar and Polakam, Tejas and Singhal, Pratyush},
title = {AgentEnv Framework},
year = {2026},
url = {https://github.com/scaleapi/agentenv-framework},
license = {Apache-2.0}
}
1 maintainer
Metadata
1 maintainer
Release files for agentenv-framework 0.9.1331
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| agentenv_framework-0.9.1331.tar.gz | 2.7 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| agentenv_framework-0.9.1331-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 3.9 MB
Release files / agentenv_framework-0.9.1331.tar.gz
| Download URL | agentenv_framework-0.9.1331.tar.gz |
|---|---|
| Size | 2.7 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9a27392c0d666903c012fb9a2f9d05122477f1523c32068f2301ea5561d139e6
|
|
BLAKE2b-256 checksum How to use checksums |
5314f65efc97757fb290797108179b6771cb4fc254f1819ab7dd69ad490763f3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / agentenv_framework-0.9.1331-py3-none-any.whl
| Download URL | agentenv_framework-0.9.1331-py3-none-any.whl |
|---|---|
| Size | 1.3 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d6dc32bc84cee40d58aa633e84e039664a3666ef556fbf36d391ab507ab4361e
|
|
BLAKE2b-256 checksum How to use checksums |
349d7d2b86474e10b50296564761fc917ff9e389cb2928867ecee551b956a733
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
