wuying-agentbay-sdk 0.4.0

Python SDK for interacting with the Wuying AgentBay cloud runtime environment

Python SDK for Wuying AgentBay

This directory contains the Python implementation of the Wuying AgentBay SDK.

Prerequisites

• Python 3.10 or later
• Poetry (for development)

Installation

For Development

Clone the repository and install dependencies using Poetry:

git clone https://github.com/aliyun/wuying-agentbay-sdk.git
cd wuying-agentbay-sdk/python
poetry install

For Usage in Your Project

pip install wuying-agentbay-sdk

Running Examples

You can find examples in the docs/examples/python directory, including:

• Basic SDK usage
• Context management
• Label management
• Mobile system integration
• OSS management
• File system operations
• Session creation

To run the examples:

# Using Poetry
poetry run python docs/examples/python/basic_usage.py

# Or directly with Python if installed in your environment
python docs/examples/python/basic_usage.py

Python-Specific Usage

from agentbay import AgentBay
from agentbay.exceptions import AgentBayError
from agentbay.session_params import CreateSessionParams

def main():
    # Initialize with API key
    api_key = "your_api_key"  # Or use os.environ.get("AGENTBAY_API_KEY")

    try:
        agent_bay = AgentBay(api_key=api_key)

        # Create a session with labels
        params = CreateSessionParams()
        params.labels = {
            "purpose": "demo",
            "environment": "development"
        }
        session_result = agent_bay.create(params)
        session = session_result.session
        
        # Execute a command
        cmd_result = session.command.execute_command("ls -la")
        
        # Read a file
        file_result = session.file_system.read_file("/path/to/file.txt")
        
        # Run code
        code_result = session.command.run_code("print('Hello, World!')", "python")
        
        # Application management
        apps_result = session.application.get_installed_apps(
            include_system_apps=True,
            include_store_apps=False,
            include_desktop_apps=True
        )
        
        # Window management
        windows_result = session.window.list_root_windows()
        window_result = session.window.get_active_window()
        
        # UI interactions
        screenshot_result = session.ui.screenshot()
        session.ui.send_key(3)  # Send HOME key
        
        # OSS operations
        upload_result = session.oss.upload_file("/local/path/file.txt", "remote/path/")
        
        # Context management
        contexts_result = agent_bay.context.list()
        
        # Session labels
        labels_result = session.get_labels()
        
        # Clean up
        delete_result = agent_bay.delete(session)

    except AgentBayError as e:
        print(f"Error: {e}")

Key Features

Session Management

• Create sessions with optional parameters (image_id, context_id, labels)
• List sessions with pagination and filtering by labels
• Delete sessions and clean up resources
• Manage session labels
• Get session information and links

Command Execution

• Execute shell commands
• Run code in various languages
• Get command output and execution status

File System Operations

• Read and write files
• List directory contents
• Create and delete files and directories
• Get file information

UI Interaction

• Take screenshots
• Find UI elements by criteria
• Click on UI elements
• Send text input
• Perform swipe gestures
• Send key events (HOME, BACK, MENU, etc.)

Application Management

• Get installed applications
• List running applications
• Start and stop applications
• Get application information

Window Management

• List windows
• Get active window
• Focus, resize, and move windows
• Get window properties

Context Management

• Create, list, and delete contexts
• Bind sessions to contexts
• Synchronize context data using policies
• Get context information

OSS Integration

• Upload files to OSS
• Download files from OSS
• Initialize OSS environment

Mobile System Support

• Special UI interactions for mobile environments
• Support for mobile application management
• Touch and gesture simulation

Response Format

All API methods return responses that include:

• request_id: A unique identifier for the request
• success: A boolean indicating whether the operation was successful
• Operation-specific data (varies by method)
• error_message: Error details if the operation failed

Development

Building the SDK

poetry build

Running Tests

poetry run pytest

For more detailed documentation, refer to the SDK Documentation.

Changelog

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

[0.4.0] - 2025-07-18

Added

• Enhanced Configuration: Support for setting SDK configuration via three methods (environment variables, config files, code parameters) in Python, Golang, and TypeScript.
• API Response Improvements: All API responses now include a request_id field for better traceability and debugging.
• Session Label Pagination: listByLabels now supports pagination parameters.
• GetLink API: Added support for specifying protocol type and port when retrieving links.
• OSS Persistence: Added support for persistent storage with OSS.
• Ticket Parameter: Some APIs now support a ticket parameter.
• Context Sync & Management: Introduced context manager and context sync APIs and implementations.
• Automated Quality Scripts: Added one-click quality check scripts (lint/format/security scan) and multi-language automated testing.
• Comprehensive Unit & Integration Tests: Significantly expanded and improved tests for TypeScript, Go, and Python SDKs.
• Documentation Restructure: API reference is now split by language, with many new tutorials and examples.
• Type/Interface Enhancements: Many new interfaces and type definitions for better IDE support across Golang, TypeScript, and Python.

Changed

• API Compatibility: Standardized some API parameters and response formats.
• Error Handling: Improved error handling and logging across SDKs.
• Default Timeout: Default timeout changed to 60 seconds.
• Documentation: Major updates to README, Getting Started, API Reference, and Tutorials.
• Code Structure: Refactored directory structure; examples, tests, and scripts are now modularized.

Fixed

• Session Deletion/Management: Fixed issues with session deletion and state management.
• File System: Fixed issues with large file chunking and read/write consistency.
• Unit Tests: Fixed compatibility and edge cases in multi-language unit tests.
• CI/CD: Fixed cross-platform line endings and environment variable loading issues.
• API Responses: Fixed incomplete response structures in some APIs.

[0.3.0] - 2025-06-16

Added

• Session Labels: Added support for organizing and filtering sessions with labels
  • Set and get session labels
  • List sessions by label filters
• Code Execution: Added support for running code in multiple languages (Python, JavaScript, etc.)
• Window Management:
  • Added support for listing, activating, and manipulating windows
  • Window resizing, focusing, and positioning
  • Get window properties and child windows
• OSS Integration: Added Object Storage Service functionality
  • File upload/download to/from OSS buckets
  • Anonymous upload/download via URLs
  • OSS environment initialization
• Context Management:
  • Create, list, and delete contexts
  • Bind sessions to contexts for persistence
  • Get context information
• UI Enhancement:
  • Added support for screenshots
  • UI element detection and interaction
  • Mobile-specific operations (click, swipe, send keys)
• Enhanced Image ID Support: Added ability to specify custom image IDs when creating sessions
• Application Management: Added support for listing, launching, and stopping applications

Changed

• Updated API client to support the latest AgentBay backend features
• Improved error handling and reporting across all SDK components
• Enhanced documentation with examples for new features
• Enhanced TypeScript type definitions for better IDE support
• Standardized response formats across all operations

Fixed

• Various bug fixes and performance improvements
• Type compatibility issues in filesystem operations
• Session management edge cases
• Command execution timeouts
• File reading/writing inconsistencies

[0.1.0] - 2025-05-15

Added

• Core SDK Implementation: Initial implementation for Python, TypeScript, and Golang
• Session Management:
  • Create, list, and delete sessions
  • Get session information
• Command Execution:
  • Execute basic shell commands
• Basic File Operations:
  • Read and write files
  • Create and delete directories
  • List directory contents
• Authentication: API key-based authentication
• Configuration: Environment-based configuration
• Documentation: Initial API reference and examples