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.

Both packages are on PyPI. You need Python 3.11 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 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.

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

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.

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.

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.

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.

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.

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}
}