AgentBay：SDK接入指南

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"

擷取 API 金鑰

1. 前往無影 AgentBay 控制台。

2. 在左側導覽列選擇服務管理，單擊目標API KEY的複製按鈕。

   說明

   若無可用API KEY，單擊建立API KEY，輸入名稱並單擊確定，建立一個API KEY。

設定環境變數

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")
        }
    }
}

支援的 API Gateway地區

SDK 配置指定要串連到哪個API Gateway。建議選擇距離使用者最近的網關，以獲得最佳網路效能。

切換到新加坡網關

Linux/macOS：

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

Windows：

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

Python 問題

externally-managed-environment錯誤：

# 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 問題

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 問題

checksum mismatch錯誤（最常見）：

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

匯入路徑錯誤：

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

構建失敗：

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

網路和 API 問題

連線逾時：

• 檢查網路連接。

• 驗證 API Gateway端點是否適合您的位置。

• 如果可以的話，嘗試不同的網關端點以獲得更好的串連。

API 金鑰錯誤：

• 驗證 API 金鑰是否正確且有效。

• 在控制台中檢查 API 金鑰許可權。

• 確保環境變數設定正確。

會話建立失敗：

• 驗證賬戶是否有足夠的配額。

• 在控制台檢查服務狀態。

• 幾分鐘後再試。

主要特點

• 臨時：會話在需要時建立，在完成後銷毀。

• 隔離：每個會話與其他會話完全獨立。

• 計費：需要為會話活躍的時間付費。

基本用法

# 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)

會話生命週期

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

會話釋放

完成後必須釋放會話才能釋放雲資源。釋放會話有兩種方法：

# Explicitly delete when done
agent_bay.delete(session)

官方系統鏡像

下表為AgentBay官方提供的最新系統鏡像。

選擇正確的鏡像

Windows環境樣本

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)

瀏覽器環境樣本

# 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)

代碼沙箱環境樣本

# 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)

雲手機環境樣本

# 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)

瞭解有關每個環境的更多資訊

• Browser Use

• Computer Use

• Mobile Use

• CodeSpace

臨時資料（預設行為）

• 預設情況下，會話中的所有資料都是臨時的。

• 會話結束時所有內容都會丟失。

• 適用於處理任務、臨時檔案或緩衝。

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

持久資料（上下文）

• 支援跨會話保留資料。

• 必須明確配置。

• 適用於專案檔、配置與重要結果。

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結果

當調用 AgentBay API 時，結果將封裝在結果對象中。

# 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

請求 ID

對 AgentBay 的每個 API 呼叫都會獲得一個唯一的請求 ID。結構類似"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