Skip to content

Latest commit

 

History

History
263 lines (163 loc) · 6.53 KB

async-extension.md

File metadata and controls

263 lines (163 loc) · 6.53 KB

AsyncExtension API Reference

💡 Sync Version: This documentation covers the asynchronous API. For synchronous operations, see ExtensionsService.

⚡ Performance Advantage: Async API enables concurrent operations with 4-6x performance improvements for parallel tasks.

🧩 Related Tutorial

AsyncExtensionsService

class AsyncExtensionsService()

Provides methods to manage user browser extensions asynchronously. This service integrates with the existing context functionality for file operations.

Usage (Simplified - Auto-detection):

# Service automatically detects if context exists and creates if needed
extensions_service = AsyncExtensionsService(agent_bay, "browser_extensions")

# Use the service immediately
extension = await extensions_service.create("/path/to/plugin.zip")

Integration with ExtensionOption (Simplified):

# Create extensions and configure for browser sessions
extensions_service = AsyncExtensionsService(agent_bay, "my_extensions")
ext1 = await extensions_service.create("/path/to/ext1.zip")
ext2 = await extensions_service.create("/path/to/ext2.zip")

# Create extension option for browser integration (no context_id needed!)
ext_option = await extensions_service.create_extension_option([ext1.id, ext2.id])

# Use with BrowserContext for session creation
browser_context = BrowserContext(
    context_id="browser_session",
    auto_upload=True,
    extension_option=ext_option  # All extension config encapsulated
)

Context Management:

  • If context_id provided and exists: Uses the existing context
  • If context_id provided but doesn't exist: Creates context with provided name
  • If context_id empty or not provided: Generates default name and creates context
  • No need to manually manage context creation

init

def __init__(self, agent_bay: "AsyncAgentBay", context_id: str = "")

Initializes the AsyncExtensionsService.

Arguments:

  • agent_bay AsyncAgentBay - The AgentBay client instance.
  • context_id str, optional - The context ID or name. If empty or not provided, a default context name will be generated automatically. If the context doesn't exist, it will be automatically created when needed.

list

async def list() -> List[Extension]

Lists all available browser extensions within this context from the cloud. Uses the context service to list files under the extensions directory.

Returns:

List[Extension]: List of all extensions in the context.

Raises:

AgentBayError: If listing fails.

Example:

extensions_service = AsyncExtensionsService(agent_bay, "my-extensions")
extensions = await extensions_service.list()
print(f"Found {len(extensions)} extensions")

create

async def create(local_path: str) -> Extension

Uploads a new browser extension from a local path into the current context.

Arguments:

  • local_path str - Path to the local extension ZIP file.

Returns:

Extension: Extension object with generated ID and metadata.

Raises:

FileNotFoundError: If the local file doesn't exist.
ValueError: If the file format is not supported (only ZIP files allowed).
AgentBayError: If upload fails.

Example:

extensions_service = AsyncExtensionsService(agent_bay, "my-extensions")
extension = await extensions_service.create("/path/to/extension.zip")
print(f"Created extension: {extension.id}")

update

async def update(extension_id: str, new_local_path: str) -> Extension

Updates an existing browser extension in the current context with a new file.

Arguments:

  • extension_id str - ID of the extension to update.
  • new_local_path str - Path to the new extension ZIP file.

Returns:

Extension: Updated extension object.

Raises:

FileNotFoundError: If the new local file doesn't exist.
ValueError: If the extension ID doesn't exist in the context.
AgentBayError: If update fails.

Example:

extensions_service = AsyncExtensionsService(agent_bay, "my-extensions")
updated = await extensions_service.update("ext_abc123.zip", "/path/to/new_version.zip")
print(f"Updated extension: {updated.id}")

cleanup

async def cleanup() -> bool

Cleans up the auto-created context if it was created by this service.

Returns:

bool: True if cleanup was successful or not needed, False if cleanup failed.

Notes:

This method only works if the context was auto-created by this service. For existing contexts, no cleanup is performed.

Example:

extensions_service = AsyncExtensionsService(agent_bay)
success = await extensions_service.cleanup()
print(f"Cleanup success: {success}")

delete

async def delete(extension_id: str) -> bool

Deletes a browser extension from the current context.

Arguments:

  • extension_id str - ID of the extension to delete.

Returns:

bool: True if deletion was successful, False otherwise.

Example:

extensions_service = AsyncExtensionsService(agent_bay, "my-extensions")
success = await extensions_service.delete("ext_abc123.zip")
print(f"Delete success: {success}")

create_extension_option

async def create_extension_option(extension_ids: List[str]) -> ExtensionOption

Create an ExtensionOption for the current context with specified extension IDs.

This is a convenience method that creates an ExtensionOption using the current service's context_id and the provided extension IDs. This option can then be used with BrowserContext for browser session creation.

Arguments:

  • extension_ids List[str] - List of extension IDs to include in the option. These should be extensions that exist in the current context.

Returns:

ExtensionOption: Configuration object for browser extension integration.

Raises:

ValueError: If extension_ids is empty or invalid.

Example:

extensions_service = AsyncExtensionsService(agent_bay, "my-extensions")
ext_option = await extensions_service.create_extension_option(["ext1.zip", "ext2.zip"])
print(f"Extension option: {ext_option}")

See Also

Related APIs:

Documentation generated automatically from source code using pydoc-markdown.