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. To try it 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 an .agentenv/config.toml in the current folder or above it; an empty one keeps every local default. Environments and agents run as containers on the local Docker daemon by default; the sandbox docs cover the other sandbox providers and the extra each needs.
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 bundle from the Hub
agent-env run also takes a bundle published in a Hugging Face Hub dataset:
agent-env run hf://<org>/<repo> # the main branch
agent-env run hf://<org>/<repo>@v1.0/bundles/hello # a tag, branch or commit, and the bundle's folder
The revision (a branch, tag or commit, percent-encoded when it holds a /; the main branch by default) resolves to a
commit, and only that commit's bundle and the dataset card are downloaded, into
$XDG_CACHE_HOME/agentenv/hf/<org>/<repo>/<commit> (~/.cache by default), where a later run of the commit finds
them. Without a path, the run takes the only bundle under bundles/, or the one the card's agentenv: default names,
else the repo's root when it has a kind folder (envs/, tasks/, ...). It prints the repo, commit and bundle, then
runs as a folder does, with ids under @hf/<org>/<repo>/<name>, so a rerun of the same commit reuses what the last one
wrote, and records the commit with each run. A bundle's <name> is its folder under bundles/, or its path for a folder
elsewhere; the root's ids are @hf/<org>/<repo>, and its name is the repo's. The card says what each bundle needs:
agentenv:
default: hello # the bundle a run without a path takes, of several under bundles/
bundles:
hello: # the bundle's <name>, or the repo's name for the root
plugins: ["agentenv-example>=1.2"] # what a bundle without a bundle.toml requires
setup: agent-env example setup # shown when a missing plugin, agent, env or artifact stops a run
Each run checks the bundle's bundle.toml, else the card's plugins, the first one before the bundle is downloaded; the
setup command is never run. A gated or private dataset needs hf auth login or HF_TOKEN.
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.
OpenEnv
Every task in a bundle is an OpenEnv env, with the openenv extra installed (pip install 'agentenv-framework[openenv]'). agent_env.openenv.build_app(bundle) returns the OpenEnv server for a bundle, a folder or an installed bundle's name, or for a mapping of split names to bundles. Any OpenEnv client resets it to a task, which deploys the task's envs and opens its agent's turn, acts through the envs' tools and an added end_turn tool, and gets the task's verifier score as its reward.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
