agentbay-lite

agentbay-lite

Minimal cloud browser SDK for AgentBay (Alibaba Cloud Wuying) — session lifecycle management via CDP.

• Lightweight: only httpx + pydantic, no Alibaba Cloud SDK dependency
• Sync & Async: AgentBayCloud and AsyncAgentBayCloud clients
• Context manager: sessions auto-delete on exit
• Alibaba Cloud RPC: proper Bearer token auth with Timestamp/SignatureNonce
• Unified interface: same API shape as browser-use-lite, skyvern-lite, airtop-lite

Install

pip install agentbay-lite

Quick Start

from agentbay_lite import AgentBayCloud

client = AgentBayCloud(api_key="...")  # or set AGENTBAY_API_KEY env var

# Create a cloud browser session (3-step RPC: CreateMcpSession -> InitBrowser -> GetCdpLink)
session = client.sessions.create()
print(session.cdp_url)   # wss://...
print(session.session_id)

# Use with Playwright (or any CDP client)
from playwright.sync_api import sync_playwright
with sync_playwright() as pw:
    browser = pw.chromium.connect_over_cdp(session.cdp_url)
    page = browser.contexts[0].new_page()
    page.goto("https://example.com")

# Cleanup
client.sessions.delete(session.session_id)
client.close()

Context Manager

with AgentBayCloud(api_key="...") as client:
    with client.sessions.create() as session:
        ...  # session auto-deleted on exit

Async

import asyncio
from agentbay_lite import AsyncAgentBayCloud

async def main():
    async with AsyncAgentBayCloud(api_key="...") as client:
        session = await client.sessions.create()
        print(session.cdp_url)
        await client.sessions.delete(session.session_id)

asyncio.run(main())

Features

Session CRUD

# Create
session = client.sessions.create()

# Get
info = client.sessions.get(session.session_id)

# List
sessions = client.sessions.list(status="RUNNING")

# Delete (idempotent)
client.sessions.delete(session.session_id)

Configuration

Exception Hierarchy

CloudBrowserError          # Base exception
├── AuthenticationError    # 401/403 — invalid or expired API key
├── QuotaExceededError     # 429 — rate limit (has .retry_after attribute)
├── SessionNotFoundError   # 404 — session doesn't exist
├── ProviderError          # 5xx — server error (has .status_code, .request_id)
├── TimeoutError           # Operation timed out
└── NetworkError           # Connection failure

License

MIT