SDK integration guide - - Alibaba Cloud Documentation Center

The AgentBay SDK provides a comprehensive set of tools to interact with the AgentBay cloud environment. It lets you create and manage cloud sessions, execute commands, manage files, and interact with the user interface.

Get an API key

Create an API key

Note

If your account has not been verified, you must complete individual or enterprise real-name verification before you can use this feature. For more information, see individual real-name verification and enterprise real-name verification.
You can create up to 10 API keys during the public preview.

You can create an API key for a project to use the available virtualization Alibaba Cloud services and MCP images.

Log on to the AgentBay console.
In the left navigation pane, click Service Management.
On the Service Management page, click Create API Key.
In the Create API KEY dialog box, enter a name and click OK.
Important
To protect your data, do not share your API key with others.

View an API key

On the Service Management page, click the icon in the API KEY Name/Value column for the desired API key.
On the Service Management page, in the API KEY Name/Value column for the API key, click the icon to copy it.

Note

For more information about managing API keys, see Create and manage API keys.

Installation

Python

pip install wuying-agentbay-sdk

go get github.com/aliyun/wuying-agentbay-sdk/golang

Typescript

npm install wuying-agentbay-sdk

Authentication

To use the AgentBay SDK, you must configure an API key. You can set the API key in one of the following ways:

Note

For more information about obtaining an API key, see Obtain an API key.

For more information about authentication, see the Authentication Guide.

Set an environment variable

export AGENTBAY_API_KEY=your_api_key

Pass the API key directly

// Go
package main

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

func main() {
    client, _ := agentbay.NewAgentBay("your_api_key", nil)
    // Use client...
}

Python

# Python
from agentbay import AgentBay

agent_bay = AgentBay(api_key="your_api_key")

Typescript

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

const agentBay = new AgentBay({ apiKey: 'your_api_key' });

Basic usage

This topic provides basic usage examples to help you quickly understand the main features of AgentBay.

Create a session

Python

from agentbay import AgentBay

agent_bay = AgentBay()
result = agent_bay.create()

if result.success:
    session = result.session
    print(f"Session created with ID: {session.session_id}")

package main

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

func main() {
    client, err := agentbay.NewAgentBay("", nil)
    if err != nil {
        fmt.Printf("Error initializing client: %v\n", err)
        return
    }

    result, err := client.Create(nil)
    if err != nil {
        fmt.Printf("Error creating session: %v\n", err)
        return
    }

    fmt.Printf("Session created with ID: %s\n", result.Session.SessionID)
}

Typescript

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

const agentBay = new AgentBay();
const result = await agentBay.create();

if (result.success) {
    const session = result.session;
    console.log(`Session created with ID: ${session.sessionId}`);
}

Execute a command

Python

command_result = session.command.execute("ls -la")
if command_result.success:
    print(f"Output: {command_result.data.stdout}")

const commandResult = await session.command.execute('ls -la');
if (commandResult.success) {
    console.log(`Output: ${commandResult.data.stdout}`);
}

Typescript

commandResult, err := session.Command.Execute("ls -la")
if err != nil {
    fmt.Printf("Error executing command: %v\n", err)
    return
}

fmt.Printf("Output: %s\n", commandResult.Data.Stdout)

Write and read a file

Python

# Write a file
write_result = session.file_system.write_file(
    path="/tmp/test.txt",
    content="Hello, World!"
)

# Read a file
read_result = session.file_system.read_file(path="/tmp/test.txt")
if read_result.success:
    print(f"File content: {read_result.data}")

// Write a file
_, err = session.FileSystem.WriteFile(
    "/tmp/test.txt",
    []byte("Hello, World!"),
)
if err != nil {
    fmt.Printf("Error writing file: %v\n", err)
    return
}

// Read a file
readResult, err := session.FileSystem.ReadFile("/tmp/test.txt")
if err != nil {
    fmt.Printf("Error reading file: %v\n", err)
    return
}

fmt.Printf("File content: %s\n", string(readResult.Data))

Typescript

// Write a file
const writeResult = await session.fileSystem.writeFile(
    '/tmp/test.txt',
    'Hello, World!'
);

// Read a file
const readResult = await session.fileSystem.readFile('/tmp/test.txt');
if (readResult.success) {
    console.log(`File content: ${readResult.data}`);
}

Use a persistent context

Python

from agentbay import AgentBay
from agentbay.context_sync import ContextSync, SyncPolicy
from agentbay.session_params import CreateSessionParams

# Initialize the client
agent_bay = AgentBay()

# Get or create a context
context_result = agent_bay.context.get("my-persistent-context", create=True)

if context_result.success:
    context = context_result.context
    
    # Create a session with context synchronization
    context_sync = ContextSync.new(
        context_id=context.id,
        path="/mnt/data",  # Mount path in the session
        policy=SyncPolicy.default()
    )
    
    params = CreateSessionParams(context_syncs=[context_sync])
    session_result = agent_bay.create(params)

package main

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

func main() {
    // Initialize the client
    client, _ := agentbay.NewAgentBay("", nil)
    
    // Get or create a context
    contextResult, _ := client.Context.Get("my-persistent-context", true)
    
    // Create a session with context synchronization
    policy := agentbay.NewSyncPolicy()
    contextSync := agentbay.NewContextSync(
        contextResult.Context.ID,
        "/mnt/data",  // Mount path in the session
        policy,
    )
    
    params := agentbay.NewCreateSessionParams().
        AddContextSyncConfig(contextSync)
    
    sessionResult, _ := client.Create(params)
}

Typescript

import { AgentBay, ContextSync, SyncPolicy } from 'wuying-agentbay-sdk';

// Initialize the client
const agentBay = new AgentBay();

// Get or create a context
const contextResult = await agentBay.context.get('my-persistent-context', true);

if (contextResult.success) {
    const context = contextResult.context;
    
    // Create a session with context synchronization
    const contextSync = new ContextSync({
        contextId: context.id,
        path: '/mnt/data',  // Mount path in the session
        policy: SyncPolicy.default()
    });
    
    const sessionResult = await agentBay.create({
        contextSync: [contextSync]
    });
}

What to do next

Now that you understand the basics of the AgentBay SDK, you can explore more features:

Tool	Description	Environment (Image)
		ComputerUse	ComputerUse	BrowserUse	CodeSpace	MobileUse
		Windows	Ubuntu	Debian	Debian	Android
Sessions	Manages the session lifecycle.	Supported	Supported	Supported	Supported	Supported
FileSystem	Provides file system operations, such as uploading, downloading, and managing files.	Supported	Supported	Supported	Supported	Not supported
OSS	Provides Object Storage Service (OSS) integration.	Supported	Supported	Not supported	Supported	Supported
Context	Manages context data in a session.	Supported	Supported	Supported	Supported	Supported
Command	Lets you execute commands in a session.	Supported	Supported	Supported	Supported	Supported
UI	Provides UI interaction in a session.	Not supported	Not supported	Not supported	Not applicable	Supported
Application	Manages application operations and status.	Supported	Not supported	Not supported	Not supported	Supported