DOCSEARCHbyAlgolia
Submit Docs

AGB Cloud SDK

repository·master·Indexed 43 days ago

https://github.com/agbcloud/agbcloud-sdk

Client libraries for Python (v0.11.0) and TypeScript to interact with the AGB cloud service. The SDK enables managing cloud sessions, executing code and shell commands, and performing browser automation. Key features include natural language page interaction, structured data extraction, browser fingerprinting to avoid detection, and bidirectional file synchronization between local machines and remote sessions.

Tokens
120.7K
Snippets
353
Records
503
Agent score
52%

What's inside AGB Cloud SDK

  1. Overview of AGB SDK Features

    master

    The AGB TypeScript SDK provides several core capabilities for interacting with the AGB cloud service:

    • Session management: Create, list, get, and delete cloud sessions.
    • Code execution: Run Python, JavaScript, Java, or R code in the cloud.
    • Command execution: Execute shell commands directly.
    • File system operations: Read, write, edit, search, and transfer files.
    • Browser automation: Use BrowserAgent for automation, take screenshots, and manage browser fingerprints.
    • Computer control: Control mouse, keyboard, windows, apps, and screens.
    • Context management: Use persistent data and sync policies to maintain state.

  2. Overview of AGB SDK capabilities

    master

    The AGB SDK provides a suite of tools for cloud-based automation, including session management, code execution, browser automation, and file system operations.

    Key functional categories include:

    • Session Management: Managing the lifecycle of remote sessions.
    • Code Execution: Running multiple languages (Python, JavaScript, Java, R) in the cloud.
    • Command Execution: Running shell commands and system tools.
    • File Operations: Managing files (read, write, upload) in the cloud.
    • Browser Automation: Navigating URLs, interacting with elements, taking screenshots, and extracting structured data via AI.
    • Advanced Automation: Managing Chrome extensions, syncing local context to remote sessions, and real-time directory monitoring.

  3. Perform browser automation with AGB

    master

    The AGB SDK allows you to control a remote browser within an AGB session. You can perform tasks such as basic navigation, executing natural language commands, and extracting structured data.

    Important Notes:

    • Browser sessions consume more memory than standard code execution sessions.
    • Always initialize the browser before attempting to take screenshots to avoid BrowserError.
    • Screenshots are returned as raw bytes from session.browser.screenshot().

  4. Automate a desktop environment with Computer automation

    master
    Computer automation allows you to automate a desktop environment within an AGB session. You can perform mouse and keyboard actions, capture screenshots, manage the application lifecycle, and control window management (listing, activating, resizing, focusing, or closing windows).

  5. AGB Python SDK Features Overview

    master

    The AGB Python SDK provides the following capabilities for managing cloud-based environments:

    • Session management: Create, list, get, and delete sessions.
    • Code execution: Run Python, JavaScript, Java, or R in the cloud.
    • Command execution: Execute shell commands.
    • File management: Read, write, edit, search, and transfer files.
    • Browser automation: Perform automation, take screenshots, and manage fingerprints.
    • Computer control: Control mouse, keyboard, windows, applications, and the screen.
    • Context: Manage persistent data and sync policies.

  6. What is an AGB Session and how to use it

    master

    A session is the core abstraction in the AGB SDK, representing an isolated cloud environment. Within a session, you can execute code, run shell commands, manage files, and interact with cloud storage.

    Prerequisites

    • AGB_API_KEY environment variable configured.
    • A valid image_id (e.g., agb-code-space-1) available in your AGB account. You can manage these in the AGB Console Image Management page.
    • Appropriate permissions to create sessions in your account.

    Core Lifecycle

    1. Create: Initialize a session using agb.create() with CreateSessionParams specifying an image_id.
    2. Execute: Use the session object (e.g., session.code.run()) to perform tasks.
    3. Cleanup: Always call agb.delete(session) when finished to free up resources, including in error handling paths.
    from agb import AGB
from agb.session_params import CreateSessionParams

agb = AGB()
create_result = agb.create(CreateSessionParams(image_id="agb-code-space-1"))
if not create_result.success:
    raise SystemExit(f"Session creation failed: {create_result.error_message}")

session = create_result.session
session.code.run("print('Hello from AGB')", "python")
agb.delete(session)

  7. Handle browser automation challenges with Call For User

    master

    The Call For User feature is designed for scenarios where browser automation cannot proceed without human intervention. This is triggered when the system encounters authentication challenges, complex verification processes (like CAPTCHAs that require manual input), security measures, or user information requests.

    When a challenge occurs, the system emits a wuying-call-for-user message via the browser console. To handle this, you should monitor console events, detect this specific message type, and use the resource_url provided in the session info to open a browser window for the user to complete the task.

  8. Manage session auto-release and timeouts

    master

    Sessions are automatically released after a period of inactivity to conserve resources.

    • idle_release_timeout: A parameter set during session creation that defines how long a session can remain idle before being automatically released. Any API call made to the session resets this timer.
    • keep_alive(): To prevent a session from being auto-released during long-running tasks or while waiting for external events, call the keep_alive() method periodically.

    Note: Once a session is released, it will no longer appear in agb.list() and its session ID becomes invalid. For data persistence, do not rely on the session lifetime; use Context synchronization instead.

  9. Maintain execution context across commands

    master

    Each call to execute() runs in a fresh shell session, meaning shell-level state like the current working directory (cd) and environment variables (export) are lost between separate calls. However, filesystem changes (files created, tools installed) persist within the session.

    To maintain state across multiple operations, use one of these three methods:

    1. Chain commands with &&: Run multiple commands in a single execute() call.
    2. Use a shell script: Write your logic to a file using session.file.write() and then execute that file.
    3. Use computer.app.start(): For long-running processes on supported computer images (e.g., agb-computer-use-ubuntu-2204).

    Prerequisites:

    • AGB_API_KEY
    • A valid image_id that supports command execution (e.g., agb-code-space-1).
    from agb import AGB
from agb.session_params import CreateSessionParams

agb = AGB()
create_result = agb.create(CreateSessionParams(image_id="agb-code-space-1"))
if not create_result.success:
    raise SystemExit(f"Session creation failed: {create_result.error_message}")

session = create_result.session
try:
    result = session.command.execute("cd /app && ls -la")
    if not result.success:
        raise RuntimeError(f"Command failed: {result.error_message}")
    print("Output:", result.output)
finally:
    agb.delete(session)

  10. How browser automation works in AGB

    master

    AGB browser automation follows a specific workflow:

    1. Session Creation: You create a browser session in AGB using a specific image_id via agb.create().
    2. Initialization: You initialize the browser instance within that session (e.g., using session.browser.initialize() or session.browser.initialize_async()).
    3. CDP Connection: AGB provides a CDP (Chrome DevTools Protocol) endpoint URL via session.browser.get_endpoint_url(). You use a local automation library like Playwright or Puppeteer to connect to this URL.
    4. Automation: Once connected, you can perform standard automation tasks (navigating, clicking, extracting data) or use AGB's AI Agent capabilities (Act/Observe/Extract).
    5. Cleanup: Always ensure you call agb.delete(session) to release resources.

  11. Synchronize files between local machine and AGB sessions

    master

    AGB provides a synchronization mechanism to ensure data persistence across sessions. You can manage data flow using three primary modes:

    • Upload: Automatically upload local files to the remote cloud session.
    • Download: Automatically download files generated in the cloud session back to your local machine.
    • Watch: (Optional) Continuously monitor and sync changes as they occur.

    Common use cases include persisting generated charts, logs, or processed datasets.

  12. Access session connectivity properties

    master

    When a session is created, it exposes properties for advanced connectivity, such as long-polling and real-time streaming. You can access these properties directly as attributes or via explicit getter methods.

    Available Properties

    Property (Python)Property (TypeScript)Description
    link_urllinkUrlDirect HTTP endpoint for long-polling connections (used for MCP tool calls)
    ws_urlwsUrlWebSocket endpoint for real-time streaming
    tokentokenAuthentication token for WebSocket connections

    When to use them

    • link_url: Use for direct HTTP routing for MCP tool calls (typically handled internally by the SDK).
    • ws_url + token: Use for real-time streaming, such as when executing code with stream_beta=True.
    # Access session properties after creation
create_result = agb.create(CreateSessionParams(image_id="agb-code-space-1"))
session = create_result.session

# Access via attributes
print("Link URL:", session.link_url)
print("WebSocket URL:", session.ws_url)
print("Token:", session.token)

# Access via explicit getters
link_url = session.get_link_url()
token = session.get_token()