AgentBay:SDK integration guide

Python

# Create and activate virtual environment
python3 -m venv agentbay-env
source agentbay-env/bin/activate  # Linux/macOS
# agentbay-env\Scripts\activate   # Windows

# Install the package
pip install wuying-agentbay-sdk

# Verify installation
python -c "import agentbay; print('Installation successful')"

# Install with user flag (if system allows)
pip install --user wuying-agentbay-sdk

# Verify installation 
python -c "import agentbay; print('Installation successful')"

TypeScript/JavaScript

# Initialize project (if new project)
mkdir my-agentbay-project && cd my-agentbay-project
npm init -y

# Install the package
npm install wuying-agentbay-sdk

# Verify installation
node -e "const {AgentBay} = require('wuying-agentbay-sdk'); console.log('Installation successful')"

Golang

# Initialize module (if new project)
mkdir my-agentbay-project && cd my-agentbay-project  
go mod init my-agentbay-project

# Install the package
GOPROXY=direct go get github.com/aliyun/wuying-agentbay-sdk/golang/pkg/agentbay

# Verify installation
go list -m github.com/aliyun/wuying-agentbay-sdk/golang && echo "Installation successful"

Get an API key

1. Go to the AgentBay console.

2. In the navigation pane on the left, choose Service Management and click the copy icon for the target API key.

   Note

   If no API key is available, click Create API Key, enter a name, and click Confirm to create one.

Set environment variable

Linux/macOS:

export AGENTBAY_API_KEY=your_api_key_here

Windows:

setx AGENTBAY_API_KEY your_api_key_here

Python

import os
from agentbay import AgentBay

# Get API key from environment
api_key = os.getenv("AGENTBAY_API_KEY")
if not api_key:
    print("Please set AGENTBAY_API_KEY environment variable")
    exit(1)

try:
    # Initialize SDK
    agent_bay = AgentBay(api_key=api_key)
    print("SDK initialized successfully")
    
    # Create a session (requires valid API key and network)
    session_result = agent_bay.create()
    if session_result.success:
        session = session_result.session
        print(f"Session created: {session.session_id}")
        
        # Clean up
        agent_bay.delete(session)
        print("Test completed successfully")
    else:
        print(f"Session creation failed: {session_result.error_message}")
        
except Exception as e:
    print(f"Error: {e}")

TypeScript

import { AgentBay } from 'wuying-agentbay-sdk';

const apiKey = process.env.AGENTBAY_API_KEY;
if (!apiKey) {
    console.log("Please set AGENTBAY_API_KEY environment variable");
    process.exit(1);
}

async function test() {
    try {
        // Initialize SDK
        const agentBay = new AgentBay({ apiKey });
        console.log("SDK initialized successfully");
        
        // Create a session (requires valid API key and network)
        const sessionResult = await agentBay.create();
        if (sessionResult.success) {
            const session = sessionResult.session;
            console.log(`Session created: ${session.sessionId}`);
            
            // Clean up
            await agentBay.delete(session);
            console.log("Test completed successfully");
        } else {
            console.log(`Session creation failed: ${sessionResult.errorMessage}`);
        }
    } catch (error) {
        console.log(`Error: ${error}`);
    }
}

test();

Golang

package main

import (
    "fmt"
    "os"
    "github.com/aliyun/wuying-agentbay-sdk/golang/pkg/agentbay"
)

func main() {
    // Get API key from environment
    apiKey := os.Getenv("AGENTBAY_API_KEY")
    if apiKey == "" {
        fmt.Println("Please set AGENTBAY_API_KEY environment variable")
        return
    }

    // Initialize SDK
    client, err := agentbay.NewAgentBay(apiKey, nil)
    if err != nil {
        fmt.Printf("Failed to initialize SDK: %v\n", err)
        return
    }
    fmt.Println("SDK initialized successfully")

    // Create a session (requires valid API key and network)
    sessionResult, err := client.Create(nil)
    if err != nil {
        fmt.Printf("Session creation failed: %v\n", err)
        return
    }
    
    if sessionResult.Session != nil {
        fmt.Printf("Session created: %s\n", sessionResult.Session.SessionID)
        
        // Clean up
        _, err = client.Delete(sessionResult.Session, false)
        if err != nil {
            fmt.Printf("Session cleanup failed: %v\n", err)
        } else {
            fmt.Println("Test completed successfully")
        }
    }
}

Supported API Gateway regions

The SDK configuration specifies which API Gateway to connect to. For the best network performance, choose the gateway closest to your location.

Switch to the Singapore gateway

Linux/macOS:

export AGENTBAY_ENDPOINT=wuyingai.ap-southeast-1.aliyuncs.com

Windows:

set AGENTBAY_ENDPOINT=wuyingai.ap-southeast-1.aliyuncs.com

Python issues

externally-managed-environment error:

# Solution: Use virtual environment
python3 -m venv agentbay-env
source agentbay-env/bin/activate
pip install wuying-agentbay-sdk

ModuleNotFoundError: No module named 'agentbay':

# Check if virtual environment is activated
which python  # Should show venv path
# Re-install if needed
pip install --force-reinstall wuying-agentbay-sdk

TypeScript issues

Cannot find module 'wuying-agentbay-sdk':

# Ensure you're in the project directory with package.json
pwd
ls package.json  # Should exist
# Re-install if needed
npm install wuying-agentbay-sdk

require() is not defined:

# Check Node.js version (requires 14+)
node --version
# Ensure you're using CommonJS (default) or update to ES modules

Golang issues

checksum mismatch error (most common):

# Always use direct proxy for this package
GOPROXY=direct go get github.com/aliyun/wuying-agentbay-sdk/golang/pkg/agentbay

Incorrect import path:

# Check Go version (requires 1.24.4+)
go version
# Ensure module is initialized
go mod init your-project-name

Build failed:

# Clean module cache and retry
go clean -modcache
go mod tidy
go get github.com/aliyun/wuying-agentbay-sdk/golang/pkg/agentbay

Network and API issues

Connection timeout:

• Check your network connectivity.

• Verify that the API Gateway endpoint is appropriate for your location.

• If possible, try a different gateway endpoint for a better connection.

API key errors:

• Verify that the API key is correct and valid.

• Check the required API key permissions in the console.

• Ensure the environment variable is set correctly.

Session creation failed:

• Verify that your account has a sufficient quota.

• Check the service status in the console.

• Try again in a few minutes.

Key characteristics

• Temporary: Sessions are created when needed and destroyed when finished.

• Isolated: Each session is completely independent of other sessions.

• Billed: You are billed for the time a session is active.

Basic use pattern

# Create a session
session = agent_bay.create().session

# Use the session for your tasks
session.command.execute_command("echo 'Hello World'")

# Always clean up when done
agent_bay.delete(session)

Session lifecycle

Create Session → Use Session → Delete Session
      ↓             ↓              ↓
  Allocate      Execute         Release
  Resources     Operations      Resources

Session release

You must release a session when you are finished to free up cloud resources. There are two ways to release a session:

# Explicitly delete when done
agent_bay.delete(session)

Official OS images

The following table lists the latest official OS images provided by AgentBay.

Choose the right image

Windows environment example

from agentbay.session_params import CreateSessionParams

# Create Windows environment and automate notepad
params = CreateSessionParams(image_id="windows_latest")
session = agent_bay.create(params).session

# Start Notepad application
session.computer.start_app("notepad.exe")
# Returns: ProcessListResult with started process info

# Input text into notepad
session.computer.input_text("Hello from Windows!")
# Returns: BoolResult with success status

agent_bay.delete(session)

Browser environment example

# Create browser environment
params = CreateSessionParams(image_id="browser_latest")
session = agent_bay.create(params).session

# Initialize and navigate
from agentbay.browser import BrowserOption
session.browser.initialize(BrowserOption())
session.browser.agent.navigate("https://www.baidu.com")
print("Web navigation successful")

agent_bay.delete(session)

Code sandbox environment example

# Create development environment and execute code
params = CreateSessionParams(image_id="code_latest")
session = agent_bay.create(params).session

# Execute code
result = session.code.run_code("print('Hello from CodeSpace!')", "python")
# Returns: CodeExecutionResult with output
# Example: result.result = "Hello from CodeSpace!"

agent_bay.delete(session)

Cloud phone environment example

# Create Android environment and send HOME key
params = CreateSessionParams(image_id="mobile_latest")
session = agent_bay.create(params).session

# Press HOME key to return to home screen
from agentbay.mobile import KeyCode
session.mobile.send_key(KeyCode.HOME)
# Returns: BoolResult with success status
# Example: result.success = True (returns to Android home screen)

agent_bay.delete(session)

Learn more about each environment

• Browser Use

• Computer Use

• Mobile Use

• CodeSpace

Temporary data (default behavior)

• By default, all data in a session is temporary.

• All content is lost when the session ends.

• This is suitable for processing tasks, temporary files, or caches.

# This data will be LOST when session ends
session.file_system.write_file("/tmp/temp_data.txt", "This will disappear")

Persistent data (Context)

• You can retain data across sessions.

• This feature must be configured explicitly.

• This is suitable for project files, configurations, and important results.

from agentbay import ContextSync

# Create persistent storage
context = agent_bay.context.get("my-project", create=True).context
context_sync = ContextSync.new(context.id, "/tmp/persistent")

# Create session with persistent data
params = CreateSessionParams(context_syncs=[context_sync])
session = agent_bay.create(params).session

# This data will be SAVED across sessions
session.file_system.write_file("/tmp/persistent/important.txt", "This will persist")

API results

When you call an AgentBay API, the result is encapsulated in a result object.

# Example API call
screenshot = session.computer.screenshot()

# The result object contains:
print(screenshot.success)     # True/False - whether the operation succeeded
print(screenshot.data)        # Your actual data (screenshot URL)
print(screenshot.request_id)  # Request ID for troubleshooting

Request ID

Each API call to AgentBay returns a unique request ID. The structure is similar to "ABC12345-XXXX-YYYY-ZZZZ-123456789ABC".

result = session.code.run_code("print('hello')", "python")
if not result.success:
    print(f"Code execution failed! Request ID: {result.request_id}")
    # Share this Request ID with support for faster help