AgentBay:基本概念

コア機能

AgentBay クラスは、Alibaba Cloud サービスと連携するための主なインターフェイスです。以下のコア機能を提供します：

• セッションマネージャー：クラウドセッションの作成、削除、および管理を行います。

• API クライアント：AgentBay クラウドサービスとのすべての通信を処理します。

• 認証ハンドラー：API キーおよびセキュリティを自動的に管理します。

基本的な使い方

# 1. クライアントを初期化
agent_bay = AgentBay()

# 2. セッションを作成（デフォルトで linux_latest を使用）
session = agent_bay.create().session

# 3. セッションをタスクに利用
# ... ご利用の自動化タスク ...

# 4. リソースをクリーンアップ
agent_bay.delete(session)

主な特徴

• 一時的：必要に応じて作成され、完了後に削除されます。

• 分離済み：各セッションは他のセッションから完全に独立しています。

• 課金対象：セッションがアクティブな時間に対して課金されます。

基本的な使い方

# セッションを作成
session = agent_bay.create().session

# セッションをタスクに利用
session.command.execute_command("echo 'Hello World'")

# 完了後は必ずリソースをクリーンアップ
agent_bay.delete(session)

セッションのライフサイクル

セッションの作成 → セッションの利用 → セッションの削除
      ↓             ↓              ↓
  リソース割り当て   操作の実行     リソース解放

セッションの解放

セッション終了後は、クラウドリソースを解放するために必ず解放処理を行う必要があります。解放方法には2 種類あります。

# 完了時に明示的に削除
agent_bay.delete(session)

公式 OS イメージ

下記の表は、AgentBay が提供する最新の公式 OS イメージの一覧です。

適切なイメージの選択

Windows 環境の例

from agentbay.session_params import CreateSessionParams

# Windows 環境を作成し、メモ帳を自動化
params = CreateSessionParams(image_id="windows_latest")
session = agent_bay.create(params).session

# メモ帳アプリケーションを起動
session.computer.start_app("notepad.exe")
# 戻り値：起動済みプロセス情報を持つ ProcessListResult

# メモ帳にテキストを入力
session.computer.input_text("Windows からこんにちは！")
# 戻り値：成功ステータスを持つ BoolResult

agent_bay.delete(session)

ブラウザ環境の例

# ブラウザ環境を作成
params = CreateSessionParams(image_id="browser_latest")
session = agent_bay.create(params).session

# 初期化およびナビゲーション
from agentbay.browser import BrowserOption
session.browser.initialize(BrowserOption())
session.browser.agent.navigate("https://www.baidu.com")
print("Web ナビゲーションが成功しました")

agent_bay.delete(session)

Code Sandbox 環境の例

# 開発環境を作成してコードを実行
params = CreateSessionParams(image_id="code_latest")
session = agent_bay.create(params).session

# コードを実行
result = session.code.run_code("print('CodeSpace からこんにちは！')", "python")
# 戻り値：出力を持つ CodeExecutionResult
# 例：result.result = "CodeSpace からこんにちは！"

agent_bay.delete(session)

Cloud Phone 環境の例

# Android 環境を作成し、HOME キーを送信
params = CreateSessionParams(image_id="mobile_latest")
session = agent_bay.create(params).session

# HOME キーを押してホーム画面に戻る
from agentbay.mobile import KeyCode
session.mobile.send_key(KeyCode.HOME)
# 戻り値：成功ステータスを持つ BoolResult
# 例：result.success = True（Android のホーム画面に戻ります）

agent_bay.delete(session)

一時データ

• デフォルトでは、セッション内のすべてのデータは一時的です。

• セッション終了時にすべてのデータが失われます。

• タスク処理、一時ファイル、キャッシュなどに利用します。

# このデータはセッション終了時に失われます
session.file_system.write_file("/tmp/temp_data.txt", "これは消えます")

永続データ

• セッション間でデータを保持できます。

• 明示的に構成する必要があります。

• プロジェクトファイル、構成、重要な結果などに利用します。

from agentbay import ContextSync

# 永続ストレージを作成
context = agent_bay.context.get("my-project", create=True).context
context_sync = ContextSync.new(context.id, "/tmp/persistent")

# 永続データ付きでセッションを作成
params = CreateSessionParams(context_syncs=[context_sync])
session = agent_bay.create(params).session

# このデータはセッション間で保存されます
session.file_system.write_file("/tmp/persistent/important.txt", "これは永続化されます")

API 結果

AgentBay の API を呼び出すと、結果は結果オブジェクトにラップされて返されます。

# 例：API 呼び出し
screenshot = session.computer.screenshot()

# 結果オブジェクトには以下のフィールドが含まれます：
print(screenshot.success)     # True/False — 操作が成功したかどうか
print(screenshot.data)        # 実際のデータ（スクリーンショットの URL など）
print(screenshot.request_id)  # トラブルシューティング用のリクエスト ID

リクエスト ID

AgentBay へのすべての API 呼び出しは、一意のリクエスト ID を返します。形式は "ABC12345-XXXX-YYYY-ZZZZ-123456789ABC" のようになります。

result = session.code.run_code("print('hello')", "python")
if not result.success:
    print(f"コード実行に失敗しました！リクエスト ID: {result.request_id}")
    # より迅速なサポートを得るために、このリクエスト ID をサポートチームにご提供ください