AgentBay：核心概念

核心功能

AgentBay類是與雲端服務互動的主要介面，包括以下核心功能：

• 會話管理器：建立、刪除和管理雲會話。

• API 用戶端：處理與 AgentBay 雲端服務的所有通訊。

• 身分識別驗證處理常式：自動管理 API 金鑰和安全性。

基本用法

# 1. Initialize client
agent_bay = AgentBay()

# 2. Create session (uses linux_latest by default)
session = agent_bay.create().session

# 3. Use session for your tasks
# ... your automation tasks ...

# 4. Clean up resources
agent_bay.delete(session)

主要特點

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

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

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

基本用法

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

臨時資料

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

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

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

# 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