wuying-agentbay-sdk 0.15.2
Python SDK for interacting with the Wuying AgentBay cloud runtime environment
License: Apache-2.0
Requires Python: <4.0,>=3.10

# AgentBay SDK for Python

> Execute commands, operate files, and run code in cloud environments

## 📦 Installation

```bash
pip install wuying-agentbay-sdk
```

## 🚀 Prerequisites

Before using the SDK, you need to:

1. Register an Alibaba Cloud account: [https://aliyun.com](https://aliyun.com)
2. Get API credentials: [AgentBay Console](https://agentbay.console.aliyun.com/service-management)
3. Set environment variable: `export AGENTBAY_API_KEY=your_api_key`

## 🚀 Quick Start

### Synchronous API (Default)

```python
from agentbay import AgentBay

# Create session
agent_bay = AgentBay()
result = agent_bay.create()

if result.success:
    session = result.session

    # Execute command
    cmd_result = session.command.execute_command("ls -la")
    print(cmd_result.output)

    # File operations
    session.file_system.write_file("/tmp/test.txt", "Hello World")
    content = session.file_system.read_file("/tmp/test.txt")
    print(content.content)  # Hello World

    # Clean up
    agent_bay.delete(session)
```

### Asynchronous API

```python
import asyncio
from agentbay import AsyncAgentBay

async def main():
    # Create session
    agent_bay = AsyncAgentBay()
    result = await agent_bay.create()

    if result.success:
        session = result.session

        # Execute command
        cmd_result = await session.command.execute_command("ls -la")
        print(cmd_result.output)

        # File operations
        await session.file_system.write_file("/tmp/test.txt", "Hello World")
        content = await session.file_system.read_file("/tmp/test.txt")
        print(content.content)  # Hello World

        # Clean up
        await agent_bay.delete(session)

if __name__ == "__main__":
    asyncio.run(main())
```

## 🔄 Sync vs Async: Which to Choose?

AgentBay Python SDK provides both synchronous and asynchronous APIs. Choose based on your application needs:

| Feature | Sync API (`AgentBay`) | Async API (`AsyncAgentBay`) |
|---------|----------------------|----------------------------|
| **Import** | `from agentbay import AgentBay` | `from agentbay import AsyncAgentBay` |
| **Best for** | Scripts, simple tools, CLI apps | Web servers (FastAPI/Django), high-concurrency apps |
| **Blocking** | Yes, blocks thread until complete | No, allows other tasks to run |
| **Usage** | `client.create(...)` | `await client.create(...)` |
| **Concurrency** | Sequential execution | Concurrent execution with asyncio |
| **Learning Curve** | Simpler, easier to start | Requires understanding of async/await |

### When to Use Sync API

Use the synchronous API (`AgentBay`) when:

- **Simple scripts**: One-off automation tasks or data processing scripts
- **CLI tools**: Command-line applications with sequential operations
- **Learning**: Getting started with AgentBay SDK
- **Debugging**: Easier to debug with sequential execution flow

**Example Use Case**: A script that processes files sequentially

```python
from agentbay import AgentBay, CreateSessionParams

agent_bay = AgentBay()
session = agent_bay.create(CreateSessionParams(image_id="code_latest")).session

# Process files one by one
for file_path in ["/tmp/file1.txt", "/tmp/file2.txt", "/tmp/file3.txt"]:
    content = session.file_system.read_file(file_path)
    processed = content.content.upper()
    session.file_system.write_file(file_path + ".processed", processed)

agent_bay.delete(session)
```

### When to Use Async API

Use the asynchronous API (`AsyncAgentBay`) when:

- **Web applications**: FastAPI, Django, or other async web frameworks
- **High concurrency**: Managing multiple sessions or operations simultaneously
- **Performance critical**: Need to maximize throughput with I/O-bound operations
- **Real-time systems**: Applications requiring non-blocking operations

**Example Use Case**: A web server handling multiple concurrent requests

```python
import asyncio
from agentbay import AsyncAgentBay, CreateSessionParams

async def process_request(task_id: str, code: str):
    agent_bay = AsyncAgentBay()
    session = (await agent_bay.create(CreateSessionParams(image_id="code_latest"))).session

    result = await session.code.run_code(code, "python")

    await agent_bay.delete(session)
    return result

async def main():
    # Process multiple requests concurrently
    tasks = [
        process_request("task1", "print('Hello from task 1')"),
        process_request("task2", "print('Hello from task 2')"),
        process_request("task3", "print('Hello from task 3')"),
    ]

    results = await asyncio.gather(*tasks)
    for result in results:
        print(result.result)

if __name__ == "__main__":
    asyncio.run(main())
```

## 📖 Complete Documentation

### 🆕 New Users
- [📚 Quick Start Tutorial](https://github.com/aliyun/wuying-agentbay-sdk/tree/main/docs/quickstart/README.md) - Get started in 5 minutes
- [🎯 Core Concepts](https://github.com/aliyun/wuying-agentbay-sdk/tree/main/docs/quickstart/basic-concepts.md) - Understand cloud environments and sessions
- [🔄 Sync vs Async Guide](docs/guides/async-programming/sync-vs-async.md) - Detailed guide on choosing between sync and async APIs

### 🚀 Experienced Users
**Choose Your Cloud Environment:**
- 🌐 [Browser Use](https://github.com/aliyun/wuying-agentbay-sdk/tree/main/docs/guides/browser-use/README.md) - Web scraping, browser testing, form automation
- 🖥️ [Computer Use](https://github.com/aliyun/wuying-agentbay-sdk/tree/main/docs/guides/computer-use/README.md) - Windows desktop automation, UI testing
- 📱 [Mobile Use](https://github.com/aliyun/wuying-agentbay-sdk/tree/main/docs/guides/mobile-use/README.md) - Android UI testing, mobile app automation
- 💻 [CodeSpace](https://github.com/aliyun/wuying-agentbay-sdk/tree/main/docs/guides/codespace/README.md) - Code execution, development environments

**Additional Resources:**
- [📖 Feature Guides](https://github.com/aliyun/wuying-agentbay-sdk/tree/main/docs/guides/README.md) - Complete feature introduction
- [🔧 Python API Reference](docs/api/README.md) - Detailed API documentation
- [💻 Python Examples](docs/examples/README.md) - Complete example code
- [📋 Logging Configuration](https://github.com/aliyun/wuying-agentbay-sdk/tree/main/docs/guides/common-features/configuration/logging.md) - Configure logging levels and output

## 🔧 Core Features Quick Reference

### Session Management

#### Synchronous
```python
from agentbay import AgentBay

agent_bay = AgentBay()

# Create session
result = agent_bay.create()
if result.success:
    session = result.session

# List sessions by labels with pagination
result = agent_bay.list(labels={"environment": "production"}, limit=10)
if result.success:
    session_ids = result.session_ids

# Delete session
delete_result = agent_bay.delete(session)
```

#### Asynchronous
```python
import asyncio
from agentbay import AsyncAgentBay

async def main():
    agent_bay = AsyncAgentBay()

    # Create session
    result = await agent_bay.create()
    if result.success:
        session = result.session

    # List sessions by labels with pagination
    result = await agent_bay.list(labels={"environment": "production"}, limit=10)
    if result.success:
        session_ids = result.session_ids

    # Delete session
    delete_result = await agent_bay.delete(session)

asyncio.run(main())
```

### File Operations

#### Synchronous
```python
# Read/write files
session.file_system.write_file("/path/file.txt", "content")
content = session.file_system.read_file("/path/file.txt")
print(content.content)

# List directory
files = session.file_system.list_directory("/path")
```

#### Asynchronous
```python
# Read/write files
await session.file_system.write_file("/path/file.txt", "content")
content = await session.file_system.read_file("/path/file.txt")
print(content.content)

# List directory
files = await session.file_system.list_directory("/path")
```

### Command Execution

#### Synchronous
```python
# Execute command
result = session.command.execute_command("python script.py")
print(result.output)
```

#### Asynchronous
```python
# Execute command
result = await session.command.execute_command("python script.py")
print(result.output)
```

### Code Execution

#### Synchronous
```python
from agentbay import AgentBay, CreateSessionParams

agent_bay = AgentBay()
session = agent_bay.create(CreateSessionParams(image_id="code_latest")).session

# Run Python code
result = session.code.run_code("print('Hello World')", "python")
if result.success:
    print(result.result)  # Hello World

agent_bay.delete(session)
```

#### Asynchronous
```python
import asyncio
from agentbay import AsyncAgentBay, CreateSessionParams

async def main():
    agent_bay = AsyncAgentBay()
    session = (await agent_bay.create(CreateSessionParams(image_id="code_latest"))).session

    # Run Python code
    result = await session.code.run_code("print('Hello World')", "python")
    if result.success:
        print(result.result)  # Hello World

    await agent_bay.delete(session)

asyncio.run(main())
```

### Data Persistence

#### Synchronous
```python
from agentbay import AgentBay, CreateSessionParams
from agentbay import ContextSync, SyncPolicy

agent_bay = AgentBay()

# Create context
context = agent_bay.context.get("my-project", create=True).context

# Create session with context
context_sync = ContextSync.new(context.id, "/tmp/data", SyncPolicy.default())
session = agent_bay.create(CreateSessionParams(context_syncs=[context_sync])).session

# Data in /tmp/data will be synchronized to the context
session.file_system.write_file("/tmp/data/config.json", '{"key": "value"}')

agent_bay.delete(session)
```

#### Asynchronous
```python
import asyncio
from agentbay import AsyncAgentBay, CreateSessionParams
from agentbay import ContextSync, SyncPolicy

async def main():
    agent_bay = AsyncAgentBay()

    # Create context
    context = (await agent_bay.context.get("my-project", create=True)).context

    # Create session with context
    context_sync = ContextSync.new(context.id, "/tmp/data", SyncPolicy.default())
    session = (await agent_bay.create(CreateSessionParams(context_syncs=[context_sync]))).session

    # Data in /tmp/data will be synchronized to the context
    await session.file_system.write_file("/tmp/data/config.json", '{"key": "value"}')

    await agent_bay.delete(session)

asyncio.run(main())
```

## 🆘 Get Help

- [GitHub Issues](https://github.com/aliyun/wuying-agentbay-sdk/issues)
- [Documentation](https://github.com/aliyun/wuying-agentbay-sdk/tree/main/docs/README.md)

## 📄 License

This project is licensed under the Apache License 2.0 - see the [LICENSE](../LICENSE) file for details.

# Changelog

All notable changes to the Wuying AgentBay SDK will be documented in this file.

## [0.15.0] - 2026-01-21

### Added

#### 🌐 Network (All SDKs)
- **Beta network management APIs**: Introduced beta network lifecycle APIs (create/describe) and `network_id` support in session params.

#### 🔗 MCP Session Routing (All SDKs)
- **LinkUrl routing**: Added LinkUrl-based routing for MCP sessions (tool calls and command execution), with integration tests and examples.
- **MCP agent environment variables**: Support passing environment variables when starting Page Use Agent MCP.

#### 📱 Mobile Beta Screenshot & UI Elements
- **Mobile beta screenshots**: Added beta screenshot APIs (including JSON response handling) and documentation/examples.
- **UI element formats**: Added support for retrieving all UI elements in **JSON/XML** formats.

#### 🧰 Code Assistant Cookbook
- **Code generation & analysis tools**: Added Qwen Code Generator and Mistral Codestral Analyzer packages plus integration guides/scripts for data analysis workflows.

#### 🤖 Agent Module
- **`execute_task` output schema**: Added support for output schema in task execution options across SDKs.

### Changed

#### ⚠️ Breaking Changes
- **Pause/Resume marked as beta**: Renamed `Pause/Resume` to `BetaPause/BetaResume` (and snake_case equivalents) across SDKs to indicate experimental status.
- **VPC routing cleanup**: Removed VPC chain/session params and legacy VPC-only logic; keep LinkUrl direct tool-call path as the unified route.

### Fixed

- **Task timeout correctness**: Fixed task execution timeout handling to wait for task termination.
- **Server recording flag**: Fixed `enableRecord=False` not taking effect (backend behavior exposed via SDK tests).
- **TypeScript docs/code cleanup**: Removed CDATA artifacts and improved import formatting in agent implementation.
- **Java SDK fixes**: Added missing `getMobile` API and updated dependency naming cleanup.

## [0.14.0] - 2026-01-10

### Added

#### ☕ Java SDK
- **Formal Release**: Introduced comprehensive support for the Java SDK, enabling Java developers to build agentic applications.
- **Four Major Environments**: Full support for Browser, Computer, Mobile, and CodeSpace environments.
- **Core Capabilities**: Support for session management, file operations (including `delete_file`), and multi-region configuration.
- **Code Execution**: Enabled `run_code` and `run_command` support within the Java SDK.
- **Observability**: Integrated session metrics and standardized logging.

#### 📱 Mobile Agent
- **Formal Launch**: Introduced the Mobile Agent (Natural Language Task Execution) across Python, TypeScript, Go, and Java SDKs.
- **Natural Language Control**: Support for executing mobile tasks using natural language via `execute_task`.
- **ADB Connection**: Added support for retrieving ADB connection URLs via `get_adb_url`.

#### 📊 Observability & Metrics
- **Session Metrics**: Implemented unified session metrics collection across all SDKs (Python, TypeScript, Go, Java).
- **SLS Logging**: Added support for SLS-formatted logs to improve log analysis capabilities.

#### 🛠️ Core Enhancements
- **CodeSpace Languages**: Added support for **R** and **Java** language execution in CodeSpace.
- **Binary Files**: Added comprehensive support for binary file reading (`read_file`) across all SDKs.
- **Session List Filtering**: Added `status` parameter to `agentbay.list()` for filtering sessions by status (RUNNING, PAUSED, etc.).
- **Ergonomic Aliases**: Introduced API aliases to improve usability and success rates for LLM interactions.

### Changed

#### ⚠️ Breaking Changes
- **Agent Task Execution**: Removed `max_step_retries` parameter. In `execute_task_and_wait`, replaced `max_try_times` with `timeout` (seconds).
- **Filesystem**: Renamed `error` field to `error_message` in `UploadResult` and `DownloadResult` objects.
- **Session API**: Renamed `GetSession` method to `GetStatus` across all SDKs. The old `GetSession` is now internal or removed.

#### Other Changes
- **Documentation**: Added warnings regarding service restrictions for overseas users.

### Fixed

- **File System**: Fixed an MQTT size limit error in `write_file` by optimizing content splitting.
- **Stability**: Resolved various issues related to session status checks, timeouts, and file transfers.
- **CI/CD**: Fixed version file paths and workflow configurations for smoother releases.

## [0.13.0] - 2025-12-19

### Core SDK capabilities (user-visible)

#### 🐍 Python API architecture (migration required)
- **Sync/async split**: Python SDK now provides separate sync and async APIs (`AgentBay` vs `AsyncAgentBay`, etc.).
- **Unified naming**: Removed `_async` suffix from method names; async APIs are `await`-able with the same method names as sync.
- **Unified imports**: Public imports were consolidated under `agentbay`.

#### 🧑‍💻 Code Execution (`run_code`)
- **Rich outputs (backward compatible)**: Added `EnhancedCodeExecutionResult` to support multi-format outputs (HTML/Markdown/images/SVG/LaTeX/charts) while keeping compatibility with `CodeExecutionResult`. (See commit `46cffd02`.)
- **Jupyter-like persistence**: Added docs/examples for long-lived code execution workflows in CodeSpace.

#### 🧾 Command execution
- **Structured outputs**: Standardized command execution outputs to expose `stdout` and `stderr` as explicit fields across SDKs. (See commit `c404ae48`.)
- **Correctness**: Fixed parsing of `exit_code` from command execution responses. (See commit `25d543cb`.)

#### 🤖 Agent module
- **BrowserUseAgent task API**: Introduced/extended task-oriented APIs for BrowserUseAgent. (See commit `c69b3596`.)
- **`execute_task` refinement**: Refined task execution API and updated docs/examples/tests accordingly. (See commit `aa98c5d8`.)

#### 📁 Context filesystem
- **`delete_file` (all languages)**: Added `delete_file` support with tests and examples.
- **Internal context loading**: Switched to `GetAndLoadInternalContext` to avoid incorrect context listing behavior.

#### 🔄 Context sync API
- **`sync_context` → `sync` (breaking)**: Renamed context sync API for consistency across SDKs and removed the legacy alias.

#### 🌍 Multi-region configuration
- **`region_id` support across SDKs**: Added region selection support for Python/TypeScript/Go.

#### 🖥️ Computer & window automation
- **Window API simplification (breaking)**: Removed `timeout` parameter from `get_active_window` across languages.
- **Typed screenshot results (TypeScript)**: `computer.screenshot()` returns a typed `ScreenshotResult`.
- **Cross-platform reliability**: Added/expanded window management integration tests (Python + Go).

#### 📱 Mobile automation
- **Mobile UI bounds**: Added `bounds_rect` support for mobile UI elements (Python), including tests and examples.

#### ☁️ OSS
- **Parameter naming**: Standardized Python OSS client `securityToken` → `security_token` and updated tests/docs.

#### 🐹 Go SDK
- **File transfer**: Added file transfer support in Go SDK with integration tests.
- **Session deletion semantics**: Adjusted delete session flow to align with async deletion API behavior.

### Developer experience (docs & reference)

- **Async programming docs**: Added/updated sync-vs-async comparison and v0.12.x → v0.13.x migration guide.
- **API reference**: Regenerated API docs for Python/TypeScript/Go and improved doc generation metadata filtering.

### Examples & cookbook (end-to-end usage)

- **Mobile login persistence cookbook**: Added `cookbook/mobile/app-login-persistence` examples covering cross-session login state for multiple apps. (See commit `0e47976b`.)
- **NL mobile control cookbook**: Added a LangChain-based NL mobile control example with a web demo and tests.

### Quality, CI, and release tooling

- **Smart integration test workflow**: Added/iterated `.aoneci/smart-integration-test.yaml` (multi-language, improved reporting, AI analysis prompts, and stability improvements).
- **Examples inspection workflow**: Added/iterated `.aoneci/example-check.yaml` (multi-language examples verification with AI analysis and DingTalk notifications).
- **KB preprocessing**: Added/iterated `preprocess_kb` pipeline to generate knowledge-base-friendly docs in batches.
- **llms artifacts**: Updated `llms.txt` / `llms-full.txt` generation workflow and content.

## [0.12.0] - 2025-11-28

### Added

#### 📱 Mobile Simulation
- **Device Simulation Support**: Added support for mobile device simulation features
  - Enhanced mobile testing capabilities
  - Support for simulating various mobile device characteristics

#### ⏸️ Session Pause & Resume
- **Session Control**: Added support for pausing and resuming sessions
  - `pause()` / `pause_async()`: Pause a running session to save resources
  - `resume()` / `resume_async()`: Resume a paused session
  - Available across Python, TypeScript, and Golang SDKs

### Fixed

#### 🐛 Bug Fixes
- **Browser Automation**: Fixed browser-use timeout issues
- **Context Management**: Fixed issue where `get_session` was creating a new context ID instead of returning the real one
- **Context Sync**: Fixed `sync` call to correctly use `context_id` and `path` together
- **Session Control**: Fixed return value handling when pause or resume backend operations fail
- **Local Testing**: Fixed issue preventing browser tests from running locally
- **Python SDK**: Simplified exception log output for cleaner logs
- **Infrastructure**: Updated logo fallback path for Aone compatibility

### Documentation

- **Use Cases**: Improved Use Cases section UX in README
- **Examples**: Updated Quick Start examples to use `CodeSpace` `run_code`
- **General**: Regenerated API documentation and improved code examples
- **Golang**: Added new examples for Golang SDK

## [0.11.0] - 2025-11-18

### Added

#### 🖱️ Browser Fingerprint Persistence
- **Fingerprint Management**: Support for browser fingerprint persistence and customization
  - Local fingerprint file synchronization
  - Custom fingerprint construction
  - Cross-session fingerprint persistence
  - Enhanced browser anti-detection capabilities

#### 📸 Browser Screenshot Enhancement
- **Long Screenshot Support**: Capture full-page screenshots beyond viewport
  - Support for scrolling screenshots
  - Automatic page stitching
  - Network idle waiting for complete rendering

#### 🔄 Cross-Platform Context Sync
- **MappingPolicy**: New policy for cross-platform context synchronization
  - Flexible path mapping between different platforms
  - Support for Windows/Linux/macOS path translation
  - Enhanced context portability

#### 📚 Cookbook Examples
- **E-Commerce Inspector**: Browser automation for e-commerce data extraction and analysis
- **AI Code Assistant**: Code generation and execution in isolated sandbox environment
- **Data Analysis**: Automated data processing and visualization with AI-driven insights

### Changed

#### 🔒 OSS Security Enhancement
- **Breaking Change**: `securityToken` is now required for OSS operations
  - Enhanced security for object storage operations
  - Updated documentation and examples

#### ⌨️ Key Normalization
- **Improved Case Compatibility**: Better handling of key names in `press_keys` tool
  - Automatic case normalization for common keys
  - Support for both uppercase and lowercase key names
  - Consistent behavior across all SDKs

#### 🧹 API Surface Cleanup
- **API Privatization**: Internal APIs marked as private across all SDKs
  - Python: Private methods prefixed with `_`
  - TypeScript: Internal APIs marked as private
  - Golang: Internal packages and unexported functions
  - Cleaner public API documentation
  - Removed deprecated APIs and properties

#### 📖 Documentation Overhaul
- **Comprehensive Documentation Enhancement**: Major documentation improvements
  - Migrated examples from separate docs to source code
  - Metadata-driven documentation generation
  - Inline examples for all public APIs
  - Fixed broken links across all documentation
  - Simplified and clarified API examples
  - Enhanced API reference with comprehensive usage examples

#### 🎯 Session Recovery
- **File Transfer Context**: Automatic context creation for recovered sessions
  - Better handling of session recovery scenarios
  - Improved file transfer reliability

### Fixed

#### 🐛 Bug Fixes
- **SDK Version Reporting**: Fixed version detection in SdkStats module
- **Context Sync**: Removed invalid `sync_id` parameter in ContextSyncResult
- **Session Info**: Handle NotFound errors gracefully with clear error messages
- **Mobile API**: Aligned mobile API naming across SDKs with MCP tool specification
- **UIElement Bounds**: Handle bounds string format correctly in Golang and TypeScript
- **Screenshot Timeout**: Fixed timeout issues caused by network idle waiting
- **Documentation**: Fixed RST code block rendering and markdown formatting issues

### Removed

#### 🗑️ Deprecated APIs
- **Cleanup**: Removed all deprecated APIs and properties
  - Cleaner codebase
  - Reduced maintenance burden
  - Clear upgrade path for users

## [0.10.0] - 2025-10-31

### Added

#### 🤖 AI Context Support
- **AI Coding Assistant Integration**: Added llms.txt and llms-full.txt files for better AI assistant context
  - Comprehensive codebase documentation for AI tools
  - Enhanced development experience with Claude Code and similar assistants
  - Structured project information for better AI understanding

#### 🔧 MCP Tool Enhancement
- **Unified MCP Tool API**: New public API for MCP tool invocation across all SDKs
  - Python: `session.call_mcp_tool(tool, args)` for direct MCP tool calls
  - TypeScript: `session.callMcpTool(tool, args)` for direct MCP tool calls
  - Golang: `session.CallMcpTool(tool, args)` for direct MCP tool calls
  - Simplified tool invocation without manual server discovery
  - Better error handling and response parsing

#### 📊 SDK Statistics & Tracking
- **SDK Stats Module**: Automatic SDK usage tracking and version reporting
  - Auto-detection of SDK version from package metadata
  - Release tracking for Python, TypeScript, and Golang
  - Statistics collection for better service improvement

#### 🗑️ Context Management Enhancement
- **Context Clear API**: New API for clearing context data
  - Python: `context.clear(context_id)` with status polling
  - TypeScript: `context.clear(contextId)` with status polling
  - Golang: `context.Clear(contextId)` with status polling
  - Asynchronous clearing with status monitoring
  - Non-blocking operation with completion detection

#### 🌐 Browser Automation Enhancement
- **Browser Type Selection**: Support for different browser types
  - Choose between Chrome and Chromium browsers
  - `browser_type` option in `BrowserOption` across all SDKs (values: "chrome", "chromium", or None for default)
  - Default browser selection per image type
  - Browser-specific optimization and compatibility

- **Browser Navigation & Arguments**: Enhanced browser initialization
  - `default_navigate_url` parameter for automatic page navigation
  - `cmd_args` parameter for custom browser command line arguments
  - Better control over browser startup behavior

- **Golang Browser Support**: Added full browser automation for Golang SDK
  - `session.Browser` interface matching Python and TypeScript
  - Complete browser API implementation
  - Browser context and page management

#### 📱 Mobile Enhancement
- **ADB Connection URL**: Direct ADB connection support for mobile automation
  - Python: `session.mobile.get_adb_url()` returns ADB connection URL
  - TypeScript: `session.mobile.getAdbUrl()` returns ADB connection URL
  - Golang: `session.Mobile.GetAdbUrl()` returns ADB connection URL
  - Enable external ADB client connections
  - Enhanced mobile automation capabilities

#### 📝 Enhanced Logging System
- **Comprehensive Logging Infrastructure**: Unified logging across all SDKs
  - File logging support with log rotation
  - Environment-based log level configuration (`AGENTBAY_LOG_LEVEL`)
  - API call and response logging with sanitization
  - Process and thread information in async operations
  - Python: loguru-based logging with enhanced formatting
  - TypeScript: winston-based logging with color support
  - Golang: structured logging with context support

#### 📋 Code Execution Enhancement
- **Code Execution Output Logging**: Better visibility for code execution
  - Detailed output logging for `run_code` operations
  - Comprehensive integration tests for code execution
  - Better error reporting and debugging

#### 📄 Data Persistence Enhancement
- **File Compression Support**: Archive mode for data persistence
  - Compress files before upload to reduce storage costs
  - Archive mode configuration in context sync
  - Automatic decompression on download
  - Support for .tar.gz format

### Changed

#### 🔄 Session Link Access Model
- **Breaking Change**: Session Link access changed from whitelist to paid subscription
  - Whitelist-based access deprecated
  - New subscription-based access model
  - Updated documentation with new access requirements

#### 🎨 Browser Context Management
- **Browser Replay Context Sync**: Fixed context synchronization behavior
  - Only sync browser replay context when `sync_context` is explicitly False
  - Better control over context persistence
  - Reduced unnecessary sync operations

#### 📚 Documentation Reorganization
- **Documentation Structure Improvement**: Better organized documentation
  - Updated API documentation links to new directory structure
  - Added custom images guide with comprehensive examples
  - Enhanced session management documentation
  - Added markdown link checker for quality assurance
  - Fixed 166 broken markdown links across documentation
  - Production environment recommendations for image types

### Fixed

#### 🐛 Browser Issues
- **Browser Image ID**: Fixed browser image references
  - Corrected `browser-latest` to `browser_latest` across all SDKs
  - Fixed default browser type values (none/undefined/nil)
  - Fixed browser type example syntax errors
  - Fixed bad reference links in browser API documents
  - Fixed browser page creation to use context 0

#### 🔧 TypeScript Issues
- **ESLint Compliance**: Fixed TypeScript code quality issues
  - Fixed `prefer-const` errors in API client
  - Improved error handling consistency
  - Better code organization

#### 📁 File System Issues
- **File Search Functionality**: Fixed filesystem example issues
  - Corrected file search implementation
  - Better error handling in filesystem operations
  - Fixed OSS sync file deletion issues

#### 📱 Mobile Issues
- **Mobile UI Element Methods**: Aligned mobile.py with ui.py implementation
  - Consistent method signatures across modules
  - Added JSON parsing in `get_clickable_ui_elements`
  - Fixed screenshot saving in automation examples

#### 🧪 Testing Issues
- **Test Case Quality**: Improved test reliability
  - Fixed bad test case design for browser type switching
  - Fixed mobile getAdbUrl unit tests across SDKs
  - Improved pytest configuration and compatibility
  - Fixed BoolResult parameter order in tests

### Documentation

- **Comprehensive Documentation Updates**: Major improvements across all areas
  - Added comprehensive custom images guide
  - Updated data persistence documentation with archive mode
  - Added Windows application management examples
  - Added logging documentation for all SDKs
  - Removed outdated logging and mobile examples docs
  - Added production environment recommendations
  - Updated Session Link access documentation
  - Fixed markdown link issues and emoji anchor compatibility

## [0.9.0] - 2025-10-15

### Added

#### 🎯 Platform-Specific Automation Modules
- **Computer Module**: New dedicated module for desktop/Windows automation across all SDKs
  - Desktop UI interaction APIs: `click_mouse()`, `move_mouse()`, `drag_mouse()`, `press_keys()`, `scroll()`
  - Screen information: `get_screen_size()`, `screenshot()`
  - Integration with MCP tools for advanced automation
  - Python: `session.computer.*`, TypeScript: `session.computer.*`, Golang: `session.Computer.*`
- **Mobile Module**: New dedicated module for Android device automation across all SDKs
  - Touch interaction: `tap()`, `swipe()`, `long_press()`
  - Input methods: `input_text()`, `send_key()` with KeyCode support
  - UI element detection: `get_clickable_ui_elements()`
  - Device configuration: `configure()` for setting device properties
  - Android-only support (mobile_latest image)
  - Python: `session.mobile.*`, TypeScript: `session.mobile.*`, Golang: `session.Mobile.*`

#### 📊 Session Management Enhancement
- **Get Session API**: Retrieve existing session information by session ID
  - Python: `agentbay.get(session_id)` returns `SessionResult`
  - TypeScript: `agentBay.get(sessionId)` returns `SessionResult`
  - Golang: `agentBay.Get(sessionID)` returns `*SessionResult`
  - Returns session object with VPC configuration, network info, and resource URL
  - Non-throwing error handling: check `result.success` and `result.error_message`
- **List Sessions API**: Retrieve paginated list of sessions with label filtering
  - Python: `agentbay.list(labels, page, limit)` returns `SessionListResult`
  - TypeScript: `agentBay.list(labels, page, limit)` returns `SessionListResult`
  - Golang: `agentBay.List(labels, page, limit)` returns `*SessionListResult`
  - Support for page-based pagination (page numbers start from 1)
  - Label filtering with key-value pairs
  - Returns session IDs, total count, and pagination metadata

#### 🗄️ Data Lifecycle Management
- **RecyclePolicy**: Control context data retention lifecycle
  - Lifecycle options: `1day`, `3days`, `5days`, `10days`, `15days`, `30days`, `90days`, `180days`, `360days`, `forever`
  - Path-specific policies: apply different lifecycles to different directories
  - Path validation: wildcard patterns not supported, use exact directory paths
  - Integration with ContextSync for automatic data cleanup
  - Python: `RecyclePolicy(lifecycle=Lifecycle.LIFECYCLE_30DAYS, paths=["/data"])`
  - TypeScript: `new RecyclePolicy(Lifecycle.LIFECYCLE_30DAYS, ["/data"])`
  - Golang: `&RecyclePolicy{Lifecycle: Lifecycle_30Days, Paths: []string{"/data"}}`

#### 🔒 VPC Session Authentication Enhancement
- **Token-based Authentication**: VPC sessions now support token authentication
  - Automatic token management for secure VPC session access
  - Token included in session creation response
  - Used for MCP tool calls and resource access in VPC environments

#### 🔧 API Schema Validation
- **MCP Field Validation**: Enhanced MCP tool parameter validation
  - Renamed `schema` to `field_schema` to align with MCP standard
  - Better error messages for invalid tool parameters
  - Improved type checking for tool inputs

### Changed (Breaking Changes)

#### ⚠️ API Response Structure Changes
- **SessionListResult.Sessions Removed**: Breaking change in session list response
  - **Removed**: `SessionListResult.Sessions` field (contained full Session objects)
  - **Use instead**: `SessionListResult.SessionIds` (list of session ID strings)
  - **Rationale**: Reduce response payload size and improve performance
  - **Migration**: Use `agentbay.get(session_id)` to retrieve full Session objects for specific sessions
  - **Before**: `result.Sessions[0].command.execute_command(...)`
  - **After**:
    ```python
    session_id = result.SessionIds[0]
    session_result = agentbay.get(session_id)
    session_result.session.command.execute_command(...)
    ```

#### 🔄 Error Handling Consistency
- **Unified Error Handling**: All APIs now use Result objects instead of raising exceptions
  - `context.get()` returns `ContextResult` (no longer raises `AgentBayError`)
  - `context.create()` returns `ContextResult` (no longer raises `AgentBayError`)
  - **Migration Required**: Replace `try-except AgentBayError` with `if not result.success` pattern
  - All error messages now follow `[ErrorCode] Message` format
  - **Before**:
    ```python
    try:
        result = agentbay.context.get("my-context")
        context = result.context
    except AgentBayError as e:
        print(f"Error: {e}")
    ```
  - **After**:
    ```python
    result = agentbay.context.get("my-context")
    if not result.success:
        print(f"Error: {result.error_message}")
    else:
        context = result.context
    ```

### Deprecated

- **UI Module**: All methods marked for removal in a future version
  - `session.ui.click()` → Use `session.computer.click_mouse()` or `session.mobile.tap()`
  - `session.ui.type()` → Use `session.computer.press_keys()` or `session.mobile.input_text()`
  - `session.ui.mouse_move()` → Use `session.computer.move_mouse()`
  - `session.ui.screenshot()` → Use `session.computer.screenshot()` or `session.mobile.screenshot()`
  - Migration guide: Use platform-specific `computer` or `mobile` modules
- **Window Module**: Some methods deprecated
  - Deprecated methods will be replaced by Computer module equivalents in a future version
- **Context Fields**:
  - `ContextResult.state` marked for removal in a future version
  - `ContextResult.os_type` marked for removal in a future version

### Enhanced

- **Error Messages**: Improved error reporting with structured `[Code] Message` format across all APIs
- **API-level Error Handling**: Enhanced error parsing for `context.get()`, `context.list()`, and `agentbay.create_session()`
- **ContextResult.error_message**: Added for consistent error reporting in context operations
- **ContextListResult.error_message**: Added for consistent error reporting in list operations

### Documentation

- **Documentation Restructure**: Major documentation organization improvements
  - **New Cookbook**: Real-world examples and recipes for common scenarios
  - **Restructured Guides**:
    - Common Features split into Basics, Advanced, and Configuration sections
    - Computer Use guide updated with new Computer module APIs
    - Mobile Use guide updated with new Mobile module APIs and Android-only clarification
    - CodeSpace guide enhanced with code execution examples
  - **API Reference Updates**: Aligned with actual SDK implementation across all three languages
  - **Migration Guides**: Added for breaking changes and deprecated APIs
  - Net documentation changes: +993 lines across 28 new files, 16 modified files, 14 deleted files

### Fixed

- **Documentation Accuracy**: Fixed incorrect iOS support claim in Mobile Use guide (Android only)
- **API Documentation**: Corrected method signatures and return types across all language SDKs
- **Example Code**: All code examples verified against actual SDK implementation

## [0.8.0] - 2025-09-19

### Added

- **Context Sync with Callback Support**: Enhanced context synchronization capabilities
  - **Asynchronous Context Sync**: Added callback-based asynchronous context sync functionality
  - **Synchronous Context Sync**: Support for blocking synchronous context sync operations
  - **Flexible Sync Options**: Two calling modes - with callback for async, without for sync
  - **Context Sync Examples**: Comprehensive examples demonstrating both sync modes
- **Enhanced Logging System**: Upgraded to loguru-based logging infrastructure
  - **File Logging**: Support for logging to files for better debugging and analysis
  - **Environment-based Log Levels**: Configurable log levels via environment variables
  - **Process & Thread Information**: Enhanced log output with process and thread details for async operations
  - **DEBUG Level Support**: More detailed logging information at DEBUG level (default: INFO)
- **Data Persistence Examples**: Comprehensive data persistence examples across all SDKs
  - **Cross-language Examples**: Updated examples for Python, TypeScript, and Golang
  - **Context Management**: Enhanced examples showing context binding and persistence
  - **Session Recovery**: Documentation and examples for session recovery scenarios
- **Browser-Use Documentation**: Complete browser automation documentation suite
  - **Core Features Guide**: Comprehensive documentation for browser context, proxies, stealth mode, extensions, and captcha handling
  - **Advanced Features Guide**: In-depth coverage of PageUse Agent and AI-powered browser interactions
  - **Code Examples**: Practical examples demonstrating browser automation workflows
  - **Integration Guide**: Documentation for seamless integration with community tools and frameworks

### Changed

- **Session Management**: Simplified session interface
  - **Removed resourceUrl**: Eliminated resourceUrl parameter from session creation for cleaner API
  - **Streamlined Session Creation**: Simplified session parameters and initialization
- **Build System**: Modernized Python package management
  - **Removed setup.py**: Transitioned from setup.py to setup.cfg for cleaner package configuration
  - **Poetry Integration**: Enhanced CI/CD with Poetry-based publishing workflows
- **Example Improvements**: Enhanced code quality and consistency across examples
  - **Better Error Handling**: Improved error handling patterns in SDK exa