AgentBay SDK for Java

Execute commands, operate files, and run code in cloud environments

📦 Installation

Note: Please check Maven Central for the latest version number and replace LATEST_VERSION below.

Maven

<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>agentbay-sdk</artifactId>
    <version>LATEST_VERSION</version>
</dependency>

Gradle

implementation 'com.aliyun:agentbay-sdk:LATEST_VERSION'

🚀 Prerequisites

Before using the SDK, you need to:

1. Register an Alibaba Cloud account: https://aliyun.com
2. Get API credentials: AgentBay Console
3. Set environment variable: export AGENTBAY_API_KEY=your_api_key

🚀 Quick Start

import com.aliyun.agentbay.*;

// Create session
AgentBay agentBay = new AgentBay();
CreateSessionParams params = new CreateSessionParams();
SessionResult result = agentBay.create(params);

if (result.isSuccess()) {
    Session session = result.getSession();

    // Execute command
    CommandResult cmdResult = session.getCommand().executeCommand("ls -la");
    System.out.println(cmdResult.getOutput());

    // File operations
    session.getFileSystem().writeFile("/tmp/test.txt", "Hello World");
    FileContentResult content = session.getFileSystem().readFile("/tmp/test.txt");
    System.out.println(content.getContent());  // Hello World

    // Clean up
    session.delete();
}

⚙️ Configuration

Using Environment Variables (Recommended)

The SDK automatically reads configuration from environment variables:

export AGENTBAY_API_KEY=your_api_key
export AGENTBAY_REGION_ID=cn-hangzhou   # Optional, default: cn-hangzhou. Endpoint is derived from region.
export AGENTBAY_TIMEOUT_MS=60000        # Optional, default: 60000

AgentBay agentBay = new AgentBay();

Explicit Configuration

You can also provide configuration explicitly:

String apiKey = "your_api_key";
// Endpoint is derived from regionId via the multi-region mapping.
Config config = new Config("cn-hangzhou", 60000);
AgentBay agentBay = new AgentBay(apiKey, config);

Or just override the API key:

AgentBay agentBay = new AgentBay("your_api_key");

Configuration Priority

The SDK uses the following precedence order (highest to lowest):

1. Explicitly passed configuration in code
2. Environment variables
3. Default configuration

📖 Complete Documentation

🆕 New Users

• 📚 Quick Start Tutorial - Get started in 5 minutes
• 🎯 Core Concepts - Understand cloud environments and sessions

🚀 Experienced Users

Choose Your Cloud Environment:

• 🌐 Browser Use - Web scraping, browser testing, form automation
• 🖥️ Computer Use - Windows desktop automation, UI testing
• 📱 Mobile Use - Android UI testing, mobile app automation
• 💻 CodeSpace - Code execution, development environments

Additional Resources:

• 📖 Feature Guides - Complete feature introduction
• 🔧 Java API Reference - Detailed API documentation
• 💻 Java Examples - Complete example code
• 📋 Logging Configuration - Configure logging levels and output

🔧 Core Features Quick Reference

Session Management

// Create session
SessionResult result = agentBay.create(new CreateSessionParams());
Session session = result.getSession();

// List sessions by labels
Map<String, String> labels = new HashMap<>();
labels.put("environment", "production");
SessionListResult listResult = agentBay.list(labels, 10);

// Delete session
session.delete();

File Operations

// Read and write files
session.getFileSystem().writeFile("/path/file.txt", "content");
FileContentResult content = session.getFileSystem().readFile("/path/file.txt");
System.out.println(content.getContent());

// List directory
DirectoryListResult files = session.getFileSystem().listDirectory("/path");

Command Execution

// Execute command
CommandResult result = session.getCommand().executeCommand("java MyClass.java");
System.out.println(result.getOutput());

Data Persistence

// Create context
Context context = agentBay.getContext().get("my-project", true).getContext();

// Create session with context
ContextSync contextSync = ContextSync.create(
    context.getId(),
    "/tmp/data",
    SyncPolicy.defaultPolicy()
);
CreateSessionParams params = new CreateSessionParams()
    .setContextSyncs(Arrays.asList(contextSync));
Session session = agentBay.create(params).getSession();

Code Execution

// Run code in isolated environment
CreateSessionParams params = new CreateSessionParams().setImageId("code_latest");
Session session = agentBay.create(params).getSession();

CodeExecutionResult result = session.getCode().runCode("print('Hello World')", "python");
if (result.isSuccess()) {
    System.out.println(result.getResult());  // Hello World
}

🆘 Get Help

• GitHub Issues
• Documentation

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.