Quick Start Guide

Quick Start Guide#

Get started with AEnvironment in 5 minutes - complete workflow from environment creation to cloud deployment

AEnvironment Overview#

AEnvironment is a revolutionary Environment-as-Code development framework designed for modern AI applications and reinforcement learning training scenarios. Define reusable intelligent environments using native Python syntax with perfect MCP (Model Context Protocol) support and one-click cloud deployment.

🚀 5-Minute Quick Start#

Step 1: Environment Initialization#

Use the AEnvironment CLI tool to quickly create your first environment:

# Create project directory
mkdir my-aenv-project && cd my-aenv-project

# Initialize environment template
aenv init helloworld

Project Structure Analysis#

After initialization, you’ll get a standard AEnvironment project structure:

helloworld/                    # Project root directory
├── 📄 config.json            # Environment configuration file
├── 🐳 Dockerfile             # Container build file
├── 📋 requirements.txt       # Python dependencies list
└── 📁 src/                   # Source code directory
    ├── __init__.py          # Package initialization file
    └── custom_env.py        # Custom environment logic

💡 Tip: The scaffolding has generated a complete basic template for you to start development immediately

Step 2: Implement Custom Logic#

Edit the src/custom_env.py file to implement your environment functionality:

from typing import Any, Dict
from aenv import register_tool, register_reward

@register_tool
def echo_tool(content: str) -> Dict[str, Any]:
    """
    Intelligent echo tool - demonstrates basic tool development

    Function: Receives any input content and returns structured response

    Parameters:
        content: Text content to echo

    Returns:
        Dictionary containing original content and processing results
    """
    return {
        "original_content": content,
        "processed_content": f"🎯 Processing result: {content}",
        "timestamp": "2024-12-12T17:30:00Z"
    }

@register_reward
def simple_reward(task: str) -> Dict[str, Any]:
    """
    Basic reward function - demonstrates reward mechanism implementation

    Function: Provides standardized feedback for task execution

    Parameters:
        task: Task description

    Returns:
        Reward information including score and feedback
    """
    return {
        "task_name": task,
        "status": "success",
        "score": 1.0,
        "feedback": f"✅ Task '{task}' executed successfully",
        "metadata": {"execution_time": 0.1}
    }

🔧 Extension Guide: To add dependencies or custom build logic, modify requirements.txt and Dockerfile

Step 3: Local Testing#

Start the local testing environment from the project root directory (containing config.json file):

# Enter project directory
cd helloworld

# Start local environment (includes MCP server and debugging interface)
aenv run

Startup Process Logs#

Run Logs

Debug Interface Preview#

After successful startup, the system will automatically open the MCP Inspector debugging interface where you can:

  • 🔍 Tool Testing: Directly call registered tools

  • 📊 Real-time Monitoring: View tool execution status and results

  • 🎯 Interactive Debugging: Test different parameter combinations Local Runtime Environment

Step 4: Build Environment Image#

After local testing, build the environment into a deployable Docker image:

# Build environment image
aenv build

# Build and push to image registry (requires registry configuration)
aenv build --push

Build Process#

📦 Building environment image...
├── 🐳 Building Docker image: hello:1.0.0
├── 🔍 Running test suite: pytest tests/
├── ✅ All tests passed
└── 🚀 Image build complete

🔐 Image Push: To push to a private registry, ensure registry authentication is configured

Step 5: Publish to Hub#

Publish environment metadata to AEnvironment Hub for cloud sharing:

# Publish environment to registry
aenv push

# View publish results
aenv get hello --version 1.0.0

Environment Metadata Example#

{
  "id": "hello-1.0.0",
  "name": "hello",
  "description": "AEnvironment getting started example environment",
  "version": "1.0.0",
  "tags": ["getting-started", "example", "Python"],
  "artifacts": [
    {
      "type": "image",
      "content": "hello:1.0.0"
    }
  ],
  "build_config": {
    "dockerfile": "./Dockerfile"
  },
  "deploy_config": {
    "cpu": "1",
    "memory": "2G",
    "os": "linux"
  }
}

Development Workflow#

Local Runtime Environment

🎯 Environment Usage Guide#

Local Mode#

Environment Configuration#

Environment Variable

Description

Default Value

DUMMY_INSTANCE_IP

Local MCP service address

http://localhost:8081

Usage Example#

import asyncio
from aenv import Environment

async def local_usage():
    # Connect to local environment
    async with Environment("helloworld") as env:
        # Discover available tools
        tools = await env.list_tools()
        print(f"🔧 Available tools: {[t["name"] for t in tools]}")

        # Call custom tool
        result = await env.call_tool(
            "echo_tool",
            {"content": "Hello from AEnvironment!"}
        )
        print(f"📤 Tool response: {result.content}")

# Run example
if __name__ == "__main__":
    asyncio.run(local_usage())

Cloud Production Mode#

Cloud Environment Configuration#

Environment Variable

Description

Example

AENV_SCHEDULER_URL

AEnvironment platform address

https://aenv.your-company.com

AENV_API_KEY

API authentication key

sk-xxx...xxx

AENV_TIMEOUT

Request timeout

30

Cloud Usage Example#

import asyncio
import os
from aenv import Environment

async def cloud_usage():
    # Create cloud environment instance
    async with Environment("helloworld@1.0.0", timeout=60) as env:
        # Cloud environment auto-initializes
        tools = await env.list_tools()
        print(f"☁️ Cloud tools: {[t.name for t in tools]}")

        # Execute cloud task
        result = await env.call_tool(
            "echo_tool",
            {"content": "Hello from Cloud!"}
        )
        print(f"🚀 Cloud response: {result.content}")

if __name__ == "__main__":
    asyncio.run(cloud_usage())

🚀 Next Steps#

After completing the quick start, we recommend the following learning path:

📚 Learning Path#

  1. Core Concepts - Core Concepts - Deep dive into AEnvironment architecture design

  2. SDK Guide - AEnvironment Python SDK Guide - Master advanced Python SDK usage

🎉 Congratulations! You have successfully created and deployed your first AEnvironment

Deep Dive into Core Concepts →

Contents