# scaleapi/agentenv-framework architecture

> Architecture diagram of the GitHub repository scaleapi/agentenv-framework, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/scaleapi/agentenv-framework
- Repository: https://github.com/scaleapi/agentenv-framework

## Overview

AgentEnv Framework is a Python SDK and CLI for defining, packaging, deploying, and running agent environments and graded tasks. The documented workflow starts with a user invoking the CLI, builds environments into versioned artifacts, deploys them behind a gateway, connects an agent, and evaluates its activity. The repository also provides protocol SDKs, extensible registries, persistence, and a local Explorer control plane. The workflow and capability links below rely on the README; source-level links are limited to relationships visible in the supplied excerpts or SOURCE INDEX, so some links are dashed where implementation was not sampled.

Main entry points: [`src/agent_env/cli/__main__.py`](https://github.com/scaleapi/agentenv-framework/blob/main/src/agent_env/cli/__main__.py) (CLI), [`src/agent_env/env/env.py`](https://github.com/scaleapi/agentenv-framework/blob/main/src/agent_env/env/env.py) (Environment model), [`src/agent_env/task/task.py`](https://github.com/scaleapi/agentenv-framework/blob/main/src/agent_env/task/task.py) (Task definitions), [`src/agent_env/explorer/app.py`](https://github.com/scaleapi/agentenv-framework/blob/main/src/agent_env/explorer/app.py) (Explorer API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Authoring and configuration"]
  node_cli["CLI<br/>[__main__.py]"]
  node_config["Configuration<br/>[loader.py]"]
  node_plugins["Plugin registries<br/>[_registration.py]"]
  node_artifacts["Artifact registry<br/>[registry.py]"]
  node_bundle["Bundle lifecycle"]
end

subgraph group_runtime["Environment and agent runtime"]
  node_env["Environment model<br/>[env.py]"]
  node_providers["Deployment providers<br/>[env_provider.py]"]
  node_gateway["Environment gateway<br/>[gateway.py]"]
  node_protocol["Environment protocol client<br/>[client.py]"]
  node_protocol_sdk["Protocol server SDK"]
  node_agent["A2A agent support"]
end

subgraph group_evaluation["Tasks and evaluation"]
  node_task["Task definitions<br/>[task.py]"]
  node_steps["Task steps<br/>[task_step.py]"]
  node_runner["Task runner<br/>[runner.py]"]
  node_eval["Evaluation<br/>[eval.py]"]
end

subgraph group_platform["Control plane and persistence"]
  node_explorer["Explorer API<br/>[app.py]"]
  node_explorer_ui["Explorer UI<br/>[&#91;&#91;...slug&#93;&#93;.tsx]"]
  node_stores["Store routing<br/>[routing.py]"]
  node_documents[("Document persistence<br/>[document_store.py]")]
  node_objects[("Object transfer<br/>[object_store.py]")]
end

node_user(("Developer / operator"))

node_user -.->|"invokes"| node_cli
node_cli -.->|"loads config"| node_config
node_config -.->|"builds registries"| node_plugins
node_cli -.->|"authors and runs"| node_bundle
node_bundle -.->|"materializes artifacts"| node_artifacts
node_cli -.->|"deploys environment"| node_env
node_env -->|"uses provider"| node_providers
node_env -->|"calls protocol"| node_protocol
node_providers -.->|"deploys behind"| node_gateway
node_protocol_sdk -.->|"serves protocol"| node_protocol
node_agent -.->|"communicates via"| node_protocol
node_cli -.->|"runs tasks"| node_task
node_task -.->|"defines steps"| node_steps
node_task -.->|"executes through"| node_runner
node_runner -.->|"scores activity"| node_eval
node_cli -.->|"starts control plane"| node_explorer
node_explorer -.->|"serves interface"| node_explorer_ui
node_explorer -->|"configures stores"| node_stores
node_stores -->|"routes document access"| node_documents
node_stores -.->|"routes object access"| node_objects
node_env -->|"uses authoring support"| node_bundle

click node_cli "https://github.com/scaleapi/agentenv-framework/blob/main/src/agent_env/cli/__main__.py"
click node_config "https://github.com/scaleapi/agentenv-framework/blob/main/src/agent_env/config/loader.py"
click node_plugins "https://github.com/scaleapi/agentenv-framework/blob/main/src/agent_env/plugins/_registration.py"
click node_artifacts "https://github.com/scaleapi/agentenv-framework/blob/main/src/agent_env/artifact/registry.py"
click node_bundle "https://github.com/scaleapi/agentenv-framework/tree/main/src/agent_env/bundle"
click node_env "https://github.com/scaleapi/agentenv-framework/blob/main/src/agent_env/env/env.py"
click node_providers "https://github.com/scaleapi/agentenv-framework/blob/main/src/agent_env/providers/env_providers/env_provider.py"
click node_gateway "https://github.com/scaleapi/agentenv-framework/blob/main/src/agent_env/env/gateway/gateway.py"
click node_protocol "https://github.com/scaleapi/agentenv-framework/blob/main/packages/agentenv-protocol/src/agentenv_protocol/client.py"
click node_protocol_sdk "https://github.com/scaleapi/agentenv-framework/blob/main/packages/agentenv-protocol/src/agentenv_protocol/agent_env_environment.py"
click node_agent "https://github.com/scaleapi/agentenv-framework/tree/main/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent"
click node_task "https://github.com/scaleapi/agentenv-framework/blob/main/src/agent_env/task/task.py"
click node_steps "https://github.com/scaleapi/agentenv-framework/blob/main/src/agent_env/task_step/task_step.py"
click node_runner "https://github.com/scaleapi/agentenv-framework/blob/main/src/agent_env/runner/runner.py"
click node_eval "https://github.com/scaleapi/agentenv-framework/blob/main/src/agent_env/eval/eval.py"
click node_explorer "https://github.com/scaleapi/agentenv-framework/blob/main/src/agent_env/explorer/app.py"
click node_explorer_ui "https://github.com/scaleapi/agentenv-framework/blob/main/src/agent_env/explorer/ui/src/pages/%5B%5B...slug%5D%5D.tsx"
click node_stores "https://github.com/scaleapi/agentenv-framework/blob/main/src/agent_env/store/routing.py"
click node_documents "https://github.com/scaleapi/agentenv-framework/blob/main/src/agent_env/store/document_store/document_store.py"
click node_objects "https://github.com/scaleapi/agentenv-framework/blob/main/src/agent_env/store/object_store/object_store.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_config,node_plugins,node_artifacts,node_bundle toneBlue
class node_env,node_providers,node_gateway,node_protocol,node_protocol_sdk,node_agent toneAmber
class node_task,node_steps,node_runner,node_eval toneMint
class node_explorer,node_explorer_ui,node_stores,node_documents,node_objects toneRose
class node_user toneIndigo
```

## Components

### Authoring and configuration

- [CLI](https://github.com/scaleapi/agentenv-framework/blob/main/src/agent_env/cli/__main__.py): `src/agent_env/cli/__main__.py`
- [Configuration](https://github.com/scaleapi/agentenv-framework/blob/main/src/agent_env/config/loader.py): `src/agent_env/config/loader.py`
- [Plugin registries](https://github.com/scaleapi/agentenv-framework/blob/main/src/agent_env/plugins/_registration.py): `src/agent_env/plugins/_registration.py`
- [Artifact registry](https://github.com/scaleapi/agentenv-framework/blob/main/src/agent_env/artifact/registry.py): `src/agent_env/artifact/registry.py`
- [Bundle lifecycle](https://github.com/scaleapi/agentenv-framework/tree/main/src/agent_env/bundle): `src/agent_env/bundle`

### Environment and agent runtime

- [Environment model](https://github.com/scaleapi/agentenv-framework/blob/main/src/agent_env/env/env.py): `src/agent_env/env/env.py`
- [Deployment providers](https://github.com/scaleapi/agentenv-framework/blob/main/src/agent_env/providers/env_providers/env_provider.py): `src/agent_env/providers/env_providers/env_provider.py`
- [Environment gateway](https://github.com/scaleapi/agentenv-framework/blob/main/src/agent_env/env/gateway/gateway.py): `src/agent_env/env/gateway/gateway.py`
- [Environment protocol client](https://github.com/scaleapi/agentenv-framework/blob/main/packages/agentenv-protocol/src/agentenv_protocol/client.py): `packages/agentenv-protocol/src/agentenv_protocol/client.py`
- [Protocol server SDK](https://github.com/scaleapi/agentenv-framework/blob/main/packages/agentenv-protocol/src/agentenv_protocol/agent_env_environment.py): `packages/agentenv-protocol/src/agentenv_protocol/agent_env_environment.py`
- [A2A agent support](https://github.com/scaleapi/agentenv-framework/tree/main/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent): `packages/agentenv-protocol/src/agentenv_protocol/a2a_agent`

### Tasks and evaluation

- [Task definitions](https://github.com/scaleapi/agentenv-framework/blob/main/src/agent_env/task/task.py): `src/agent_env/task/task.py`
- [Task steps](https://github.com/scaleapi/agentenv-framework/blob/main/src/agent_env/task_step/task_step.py): `src/agent_env/task_step/task_step.py`
- [Task runner](https://github.com/scaleapi/agentenv-framework/blob/main/src/agent_env/runner/runner.py): `src/agent_env/runner/runner.py`
- [Evaluation](https://github.com/scaleapi/agentenv-framework/blob/main/src/agent_env/eval/eval.py): `src/agent_env/eval/eval.py`

### Control plane and persistence

- [Explorer API](https://github.com/scaleapi/agentenv-framework/blob/main/src/agent_env/explorer/app.py): `src/agent_env/explorer/app.py`
- [Explorer UI](https://github.com/scaleapi/agentenv-framework/blob/main/src/agent_env/explorer/ui/src/pages/%5B%5B...slug%5D%5D.tsx): `src/agent_env/explorer/ui/src/pages/[[...slug]].tsx`
- [Store routing](https://github.com/scaleapi/agentenv-framework/blob/main/src/agent_env/store/routing.py): `src/agent_env/store/routing.py`
- [Document persistence](https://github.com/scaleapi/agentenv-framework/blob/main/src/agent_env/store/document_store/document_store.py): `src/agent_env/store/document_store/document_store.py`
- [Object transfer](https://github.com/scaleapi/agentenv-framework/blob/main/src/agent_env/store/object_store/object_store.py): `src/agent_env/store/object_store/object_store.py`

### Other components

- **Developer / operator**

## Connections

- Developer / operator → CLI: invokes (evidence: `README.md`)
- CLI → Configuration: loads config
- Configuration → Plugin registries: builds registries (evidence: `README.md`)
- CLI → Bundle lifecycle: authors and runs (evidence: `README.md`)
- Bundle lifecycle → Artifact registry: materializes artifacts (evidence: `README.md`)
- CLI → Environment model: deploys environment (evidence: `README.md`)
- Environment model → Deployment providers: uses provider (evidence: `src/agent_env/env/env.py`)
- Environment model → Environment protocol client: calls protocol (evidence: `src/agent_env/env/env.py`)
- Deployment providers → Environment gateway: deploys behind (evidence: `README.md`)
- Protocol server SDK → Environment protocol client: serves protocol
- A2A agent support → Environment protocol client: communicates via
- CLI → Task definitions: runs tasks (evidence: `README.md`)
- Task definitions → Task steps: defines steps
- Task definitions → Task runner: executes through (evidence: `README.md`)
- Task runner → Evaluation: scores activity (evidence: `README.md`)
- CLI → Explorer API: starts control plane (evidence: `README.md`)
- Explorer API → Explorer UI: serves interface (evidence: `src/agent_env/explorer/app.py`)
- Explorer API → Store routing: configures stores (evidence: `src/agent_env/explorer/app.py`)
- Store routing → Document persistence: routes document access (evidence: `src/agent_env/store/routing.py`)
- Store routing → Object transfer: routes object access (evidence: `src/agent_env/store/routing.py`)
- Environment model → Bundle lifecycle: uses authoring support (evidence: `src/agent_env/env/env.py`)
