Extension API Reference

April 2, 2026 · View on GitHub

💡 Async Version: This documentation covers the synchronous API. For async/await support, see AsyncExtensionsService which provides the same functionality with async methods.

Browser Extensions Guide - Learn how to use browser extensions

ExtensionsService

class ExtensionsService()

Provides methods to manage user browser extensions synchronously. 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 = ExtensionsService(agent_bay, "browser_extensions")

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

Integration with ExtensionOption (Simplified):

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

# Create extension option for browser integration (no context_id needed!)
ext_option = 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: "AgentBay", context_id: str = "")

Initializes the ExtensionsService.

Arguments:

agent_bay AgentBay - 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

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 = ExtensionsService(agent_bay, "my-extensions")
extensions = extensions_service.list()
print(f"Found {len(extensions)} extensions")

create

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 = ExtensionsService(agent_bay, "my-extensions")
extension = extensions_service.create("/path/to/extension.zip")
print(f"Created extension: {extension.id}")

update

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 = ExtensionsService(agent_bay, "my-extensions")
updated = extensions_service.update("ext_abc123.zip", "/path/to/new_version.zip")
print(f"Updated extension: {updated.id}")

cleanup

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 = ExtensionsService(agent_bay)
success = extensions_service.cleanup()
print(f"Cleanup success: {success}")

delete

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 = ExtensionsService(agent_bay, "my-extensions")
success = extensions_service.delete("ext_abc123.zip")
print(f"Delete success: {success}")

create_extension_option

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 = ExtensionsService(agent_bay, "my-extensions")
ext_option = extensions_service.create_extension_option(["ext1.zip", "ext2.zip"])
print(f"Extension option: {ext_option}")