Environments

Environment Introduction

AEnvironment is an Environment-as-Code development framework that enables you to define reusable environments using Python for agent construction and reinforcement learning training. The framework supports the MCP protocol and enables one-click deployment to the cloud.

Core Philosophy: Abstract complex runtime environments into programmable, version-controlled, and reusable environment units. Developers can define complete agent runtime environments through declarative Python code—from toolsets and reward functions to custom functional modules—achieving one-click cloud deployment with seamless MCP protocol integration.

Environment Configuration

Configuration File

Each environment project contains a core configuration file: config.json

{
  "name": "aenv",
  "version": "1.0.0",
  "tags": ["linux"],
  "status": "Ready",
  "codeUrl": "",
  "artifacts": [],
  "buildConfig": {
    "dockerfile": "./Dockerfile",
    "context": "."
  },
  "testConfig": {
    "script": ""
  },
  "deployConfig": {
    "cpu": "1",
    "memory": "2Gi",
    "os": "linux",
    "ephemeralStorage": "5Gi",
    "environmentVariables": {},
    "service": {
      "replicas": 1,
      "port": 8081,
      "enableStorage": false,
      "storageName": "aenv",
      "storageSize": "10Gi",
      "mountPath": "/home/admin/data"
    }
  }
}

Note: This is the default template from aenv init. Optional fields like imagePrefix and podTemplate can be added in deployConfig for advanced deployment scenarios.

Configuration Fields

Field	Type	Required	Description
name	string	Yes	Unique environment identifier
version	string	Yes	Semantic version number
description	string	No	Human-readable environment description
tags	string[]	No	Searchable tag collection
status	string	No	Environment status identifier
codeUrl	string	No	URL or path to the environment source code (e.g., OSS path, Git URL)
artifacts	object[]	No	Build artifacts list
buildConfig	object	Yes	Build configuration
testConfig	object	No	Test configuration
deployConfig	object	Yes	Deployment configuration

Build Artifacts

Currently supports Docker images as build artifacts. After successful aenv build execution, artifacts content is automatically updated:

"artifacts": [
  {
    "id": "",
    "type": "image",
    "content": "reg.example.com/faas-swe/image:search-1.0.0-v3"
  }
]

Extension Note: Additional artifact types are continuously being expanded.

Build Configuration (BuildConfig)

Supports custom build parameters including image name, tags, etc. These parameters can also be temporarily specified via the aenv build command line:

{
  "buildConfig": {
    "dockerfile": "./Dockerfile",
    "context": ".",
    "image_name": "helloworld",
    "image_tag": "latest"
  }
}

Deployment Configuration (DeployConfig)

Default Configuration (from official template):

{
  "deployConfig": {
    "cpu": "1",
    "memory": "2Gi",
    "os": "linux",
    "ephemeralStorage": "5Gi",
    "environmentVariables": {},
    "service": {
      "replicas": 1,
      "port": 8081,
      "enableStorage": false,
      "storageName": "aenv",
      "storageSize": "10Gi",
      "mountPath": "/home/admin/data"
    }
  }
}

Extended Configuration (with optional fields):

{
  "deployConfig": {
    "cpu": "2",
    "memory": "4Gi",
    "os": "linux",
    "ephemeralStorage": "5Gi",
    "imagePrefix": "registry.example.com/envs",
    "podTemplate": "Default",
    "environmentVariables": {
      "MODEL_PATH": "/models/llm"
    },
    "service": {
      "replicas": 1,
      "port": 8081,
      "enableStorage": false,
      "storageName": "my-env",
      "storageSize": "10Gi",
      "mountPath": "/home/admin/data"
    }
  }
}

Core Deployment Parameters:

• cpu: CPU resource specification (used as both request and limit), defaults to "1"
  • Example: "1", "2", "4"
• memory: Memory specification (used as both request and limit), defaults to "2Gi"
  • Example: "2Gi", "4Gi", "8Gi"
• ephemeralStorage: Ephemeral storage specification (used as both request and limit), defaults to "5Gi"
  • Example: "5Gi", "10Gi", "20Gi"
• os: Operating system, currently only supports "linux"
• environmentVariables: Environment variable configuration as key-value pairs, defaults to {}

Optional Deployment Parameters:

• imagePrefix: (Optional) Image prefix used to constrain common prefixes for multiple images associated with the current environment
  • Not included in default template
  • Add this when you need to specify a custom image registry prefix
• podTemplate: (Optional) Pod template, defaults to "singleContainer" (single container mode)
  • Not included in default template
  • Add this when using custom pod templates like "DualContainer"

Service Configuration (service):

The service block contains configuration for long-running service deployments:

• replicas: Number of replicas, defaults to 1
  • Used by aenv service create command
  • Must be 1 when storage is enabled
• port: Service port, defaults to 8081
  • The port exposed by the service for external access
• enableStorage: Enable persistent storage by default, defaults to false
  • Can be overridden by --enable-storage CLI flag
• storageName: Storage name, defaults to environment name
  • Used as PVC (PersistentVolumeClaim) name
• storageSize: Storage size like "10Gi", "20Gi"
  • Required when storage is enabled
  • Cannot be changed after creation
• mountPath: Mount path for persistent storage, defaults to "/home/admin/data"
  • Where the persistent volume is mounted in the container

Legacy Support:

For backward compatibility, the following legacy parameters are still supported:

• cpuRequest / cpuLimit: If not set, both use cpu value
• memoryRequest / memoryLimit: If not set, both use memory value
• ephemeralStorageRequest / ephemeralStorageLimit: If not set, both use ephemeralStorage value

Recommended: Use the simplified parameters (cpu, memory, ephemeralStorage) instead of the legacy separate request/limit parameters.

Environment Architecture Types

Single Container Environment

Architecture Features: Integrated design combining business logic and tool execution environments in a single container.

Core Components:

• Business Logic Engine: Handles core business processes and user requests
• Built-in Toolset: Pre-installed all required tool scripts and command-line tools
• Shared Runtime Environment: Business code and tool scripts share the same runtime environment
• Integrated Data Storage: Local storage for business data and temporary files

flowchart TB
    User["External User/System"]

    subgraph "Single Container Workflow"
        direction TB

        subgraph "Environment Instance"
            A["FastMCP Service Entry"]
            B["MCP Tool Calls"]
            C["Business Process Handling"]
            D["Local Runtime Environment"]
        end

        User -->|HTTP/API Request| A
        A --> B
        B --> C
        C -->|Direct Call| D
        D -->|Return Result| C
        C -->|Response Data| B
        B -->|Business Response| User

        classDef unifiedContainer fill:#9C27B0,stroke:#4A148C,color:white
        class UnifiedContainer unifiedContainer
    end

    style User fill:#FF9800,stroke:#E65100,color:white

Use Cases:

• Lightweight environment requirements
• Rapid prototyping development
• Resource-constrained scenarios
• Simple tool integration

Dual Container Environment

Architecture Features: Adopts dual container deployment architecture by separating business logic from execution environments, achieving highly scalable and flexible AI agent runtime environments.

Architecture Components

Main Container

• Responsible for core business logic execution
• Handles user requests and business process orchestration
• Serves as the unified entry point for the environment

Execution Container (Second Container)

• Acts as independent data and runtime environment carrier
• Pre-installed with various tool scripts and dependency environments
• Provides isolated execution sandbox
• Focuses on tool calls and data processing tasks

Collaboration Mechanism

• On-demand Invocation: Main container dynamically invokes execution container when specific tools need execution
• Environment Isolation: Tool execution environment is completely isolated from main business logic, ensuring system stability
• Resource Sharing: Necessary data exchange through mounted volumes or network communication
• Security Boundary: Execution container runs under restricted permissions, reducing security risks

flowchart TB
    subgraph "Dual Container Workflow"
        direction TB

        subgraph "Environment Instance"
            subgraph "Main Container"
                A["FastMCP Service Entry"]
                B["MCP Tool Calls"]
                C["Business Process Handling"]
                D["Execution Container Caller"]
            end

            subgraph "Execution Container"
                E["Tool Script Collection"]
                F["Python Virtual Environment"]
                G["Data Storage"]
                H["Execution Sandbox"]
            end
        end

        Rollout["Training/Agent Framework"] -->|Function Call Request| A
        A --> B
        B --> C
        C --> D
        D -->|Call Instruction + Data Parameters| H
        H --> F
        F --> E
        E --> G
        G -->|Execution Result| H
        H -->|Return Result| D
        D --> C
        C -->|Response Data| B
        B -->|Tool Call Result| Rollout
    end

    style Rollout fill:#FF9800,stroke:#E65100,color:white

Dual Container Configuration Guide

1. Modify Environment Configuration File

{
  "deployConfig": {
    "podTemplate": "DualContainer",
    "imagePrefix": "registry.example.com/envs"
  }
}

• podTemplate: Select templates supporting dual containers (e.g., DualContainer)
• imagePrefix: Constrains the common prefix for second container images associated with the current environment

2. Specify Data Source When Creating Environment Instance

env = Environment(
    env_name="swe-env",
    datasource=""
)

datasource specifies the suffix for the current environment instance's second container image. The complete second container image is: imagePrefix + datasource

Usage Scenarios

Scenario 1: Direct Full Image Path Specification

When datasource contains the complete second container image path, imagePrefix configuration can be omitted:

env = Environment(
    env_name="swe-env",
    datasource="swebench/sweb.eval.x86_64.{instance_id}_1776_p5.js-5771:latest"
)
# Full image name: swebench/sweb.eval.x86_64.{instance_id}_1776_p5.js-5771:latest

Scenario 2: Image Concatenation Logic

Sync images to internal repository, distinguishing different instances by tags:

# Configure image prefix
imagePrefix = "custom_registry/swebench/common_name:"

# Only need to pass instance ID when creating environment
env = Environment(
    env_name="swe-env",
    datasource="{instance_id}"
)
# Full image name: custom_registry/swebench/common_name:{instance_id}

Advantages:

• All instances use the same image name, distinguished by different tags
• Simplifies environment creation process, only need to pass instance identifier
• Facilitates image version management and batch deployment

Environment Instance Lifecycle

Create Environment Instance

from aenv import Environment

# Create environment instance
env = Environment(
    env_name="my-env",
    ttl="1h",
    environment_variables={"DEBUG": "true"}
)

Use Environment

Environment instances can be integrated with various training frameworks for reinforcement learning training, or configured separately for agent use. Refer to the examples directory for detailed usage.

Destroy Environment Instance

# Initialize environment (create container)
await env.initialize()

# Release resources after use
await env.release()

Lifecycle Management:

• Default TTL: 30 minutes automatic recycling
• Active Release: Explicit resource release via interface
• Resource Optimization: Recommend timely release to avoid resource waste

Best Practices

import asyncio
from aenv import Environment

async def managed_environment():
    """Use context manager to ensure proper resource cleanup"""
    async with Environment("my-env", ttl="2h") as env:
        # Environment automatically initialized
        tools = await env.list_tools()

        # Execute environment tasks
        result = await env.call_tool("analyze", {"data": "sample"})

        # Automatic destruction on exit
        return result

# Run example
asyncio.run(managed_environment())