Installation
Install the comprehensive Owl Browser SDK from PyPI.
bash
pip install owl-browserQuick Start
The SDK supports both async (recommended) and sync usage. Here is how to get started with async mode:
python
import asyncio
from owl_browser import OwlBrowser, RemoteConfig
async def main():
config = RemoteConfig(
url="http://localhost:8080",
token="your-secret-token"
)
async with OwlBrowser(config) as browser:
# Create a browser context
ctx = await browser.create_context()
context_id = ctx["context_id"]
# Navigate to a page
await browser.navigate(context_id=context_id, url="https://example.com")
# Click an element
await browser.click(context_id=context_id, selector="button#submit")
# Take a screenshot
screenshot = await browser.screenshot(context_id=context_id)
# Extract text content
text = await browser.extract_text(context_id=context_id, selector="h1")
print(f"Page title: {text}")
# Close the context
await browser.close_context(context_id=context_id)
asyncio.run(main())Authentication
Bearer Token
Simple token-based authentication for most use cases.
python
config = RemoteConfig(
url="http://localhost:8080",
token="your-secret-token"
)JWT Authentication
Secure JWT authentication with automatic rotation.
python
from owl_browser import RemoteConfig, AuthMode, JWTConfig
config = RemoteConfig(
url="http://localhost:8080",
auth_mode=AuthMode.JWT,
jwt=JWTConfig(
private_key_path="/path/to/private.pem",
expires_in=3600,
issuer="my-app",
subject="user-123"
)
)Flow Execution
Execute complex automation flows defined in JSON files. This allows for portable, declarative automation logic.
Running a Flow
python
from owl_browser import OwlBrowser, RemoteConfig
from owl_browser.flow import FlowExecutor
async def run_flow():
async with OwlBrowser(RemoteConfig(...)) as browser:
ctx = await browser.create_context()
executor = FlowExecutor(browser, ctx["context_id"])
# Load and execute a dynamic flow
flow = FlowExecutor.load_flow("test-flows/navigation.json")
result = await executor.execute(flow)
if result.success:
print(f"Flow completed!")
else:
print(f"Flow failed: {result.error}")Flow JSON Format
json
{
"name": "Navigation Test",
"steps": [
{
"type": "browser_navigate",
"url": "https://example.com"
},
{
"type": "browser_extract_text",
"selector": "h1",
"expected": {
"contains": "Example"
}
}
]
}Configuration
Advanced configuration options for the `RemoteConfig` object.
python
from owl_browser import RemoteConfig, RetryConfig
config = RemoteConfig(
url="https://your-domain.com",
token="secret",
# Connection settings
timeout=30.0,
max_concurrent=10,
verify_ssl=True,
# Retry logic
retry=RetryConfig(
max_retries=3,
initial_delay_ms=100,
max_delay_ms=10000,
backoff_multiplier=2.0
),
# API Prefix (empty for direct server connection)
api_prefix="/api"
)Error Handling
The SDK provides specific exception classes for robust error handling.
python
from owl_browser import (
OwlBrowserError,
ConnectionError,
AuthenticationError,
ToolExecutionError,
TimeoutError
)
try:
await browser.navigate(...)
except AuthenticationError:
print("Check your token")
except ToolExecutionError as e:
print(f"Tool failed: {e.message}")
except TimeoutError:
print("Operation timed out")