​
Accessing Plato Environment

There are two ways to access and use a Plato environment: using Plato’s managed browser (recommended) or setting up your own custom browser.

​
Method 1: Using Plato’s Managed Browser

This is the recommended way to access the environment as it provides seamless integration with Plato’s infrastructure and state management.
from plato import Plato

# Initialize client
plato = Plato(api_key="your-api-key")

# Initialize the environment
env = await plato.make_environment("espocrm")

# Wait for environment to be ready
await env.wait_for_ready()

# Start interaction
await env.reset()
cdp_url = await env.get_cdp_url()

# Connect using CDP
from playwright.async_api import async_playwright

async with async_playwright() as p:
    browser = await p.chromium.connect_over_cdp(cdp_url)
    page = await browser.new_page()
    # Your automation code here

# Get final state mutations
state_changes = await env.get_state()

# Evaluate task completion
result = await env.evaluate()

# Clean up
await env.close()

​
Core Environment Methods

​
Wait for Ready

Waits for the environment to be fully initialized and ready for use: 
# Wait indefinitely
await env.wait_for_ready()

# Wait with timeout (60 seconds)
await env.wait_for_ready(timeout=60.0)

​
Get CDP URL

Retrieves the Chrome DevTools Protocol URL for browser connection: 
# Must call reset() first to initialize session
await env.reset()
cdp_url = await env.get_cdp_url()
print(f"CDP URL: {cdp_url}")

​
State Management

Get current environment state and track changes: 
# Get current state
state = await env.get_state()
print(f"Current state: {state}")

# Get list of state mutations
mutations = await env.get_state_mutations()
print(f"State changes: {mutations}")

​
Evaluate Task Completion

Evaluate whether the current task has been completed successfully: 
# Evaluate task completion
result = await env.evaluate()
print(f"Task completed: {result.success}")
if not result.success:
    print(f"Failure reason: {result.reason}")

# Optional: specify agent version for evaluation
result = await env.evaluate(agent_version="v1.0")

​
Get Live View URL

Get URL for real-time environment monitoring: 
# Get live view URL for monitoring
live_url = await env.get_live_view_url()
print(f"Monitor at: {live_url}")

​
Close Environment

Clean up resources when finished: 
# Always close environment to free resources
await env.close()

​
Method 2: Custom Browser Setup

If you need full control over the browser configuration, you can set up your own browser instance. The setup depends on whether you’re working with recorded apps or non-recorded apps.

​
For Recorded Apps (Using Proxy)

For recorded apps like DoorDash, Uber, etc., you need to use Plato’s proxy configuration to ensure proper state tracking and interaction recording. You can find the complete example in our GitHub repository at custom_browser_environment.py. 
from plato import Plato
from playwright.async_api import async_playwright

# Initialize client
client = Plato(api_key="your-api-key")

# Create environment for recorded app
env = await client.make_environment(
    env_id="doordash",  # or other recorded app
    interface_type=None,  # Required for custom browser
)

# Initialize environment
await env.wait_for_ready()
await env.reset()

# Get proxy configuration
proxy_config = await env.get_proxy_config()
# Returns:
# {
#     "server": "https://proxy.plato.so",
#     "username": "<env_id>",
#     "password": "<session_id>"
# }

# Launch browser with proxy
async with async_playwright() as p:
    browser = await p.chromium.launch(
        headless=False,  # Set to True for headless mode
        proxy=proxy_config,
        args=[
            "--ignore-certificate-errors",
            "--ignore-ssl-errors",
            "--disable-http2",
        ],
    )
    
    page = await browser.new_page()
    # Your automation code here

​
For Non-Recorded Apps (Using Public URL)

For non-recorded apps (regular software applications), you can use the public URL directly without proxy configuration: 
from plato import Plato
from playwright.async_api import async_playwright

# Initialize client
client = Plato(api_key="your-api-key")

# Create environment for non-recorded app
env = await client.make_environment(
    env_id="espocrm",  
    interface_type=None,  # Required for custom browser
)

# Initialize environment
await env.wait_for_ready()
await env.reset()

# Get public URL instead of proxy
public_url = await env.get_public_url()
print(f"Public URL: {public_url}")

# Launch browser 
async with async_playwright() as p:
    browser = await p.chromium.launch()
    
    page = await browser.new_page()
    
    # Navigate to the public URL
    await page.goto(public_url)
    
    # Your automation code here

await env.close()

​
Method 3: Using Sync Plato Client

If you prefer synchronous code or cannot use async/await in your environment, you can use the sync Plato client instead:

​
Basic Sync Environment Usage

from plato.sync_sdk import SyncPlato
from playwright.sync_api import sync_playwright

# Initialize sync client
plato = SyncPlato(api_key="your-api-key")

# Initialize the environment
env = plato.make_environment("espocrm")

# Wait for environment to be ready
env.wait_for_ready()

# Start interaction
env.reset()
cdp_url = env.get_cdp_url()

# Connect using CDP
with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp(cdp_url)
    page = browser.new_page()
    # Your automation code here

# Get final state mutations
state_changes = env.get_state()

# Evaluate task completion
result = env.evaluate()

# Clean up
env.close()

​
Sync Environment for Recorded Apps (Using Proxy)

from plato.sync_sdk import SyncPlato
from playwright.sync_api import sync_playwright

# Initialize sync client
client = SyncPlato(api_key="your-api-key")

# Create environment for recorded app
env = client.make_environment(
    env_id="doordash",  # or other recorded app
    interface_type=None,  # Required for custom browser
)

# Initialize environment
env.wait_for_ready()
env.reset()

# Get proxy configuration
proxy_config = env.get_proxy_config()

# Launch browser with proxy
with sync_playwright() as p:
    browser = p.chromium.launch(
        headless=False,  # Set to True for headless mode
        proxy=proxy_config,
        args=[
            "--ignore-certificate-errors",
            "--ignore-ssl-errors",
            "--disable-http2",
        ],
    )
    
    page = browser.new_page()
    # Your automation code here
    
# Clean up
env.close()

​
Sync Environment for Non-Recorded Apps (Using Public URL)

from plato.sync_sdk import SyncPlato
from playwright.sync_api import sync_playwright

# Initialize sync client
client = SyncPlato(api_key="your-api-key")

# Create environment for non-recorded app
env = client.make_environment(
    env_id="espocrm",  
    interface_type=None,  # Required for custom browser
)

# Initialize environment
env.wait_for_ready()
env.reset()

# Get public URL instead of proxy
public_url = env.get_public_url()
print(f"Public URL: {public_url}")

# Launch browser 
with sync_playwright() as p:
    browser = p.chromium.launch()
    page = browser.new_page()
    
    # Navigate to the public URL
    page.goto(public_url)
    
    # Your automation code here

# Clean up
env.close()

​
Common Issues & Solutions

​
1. Environment Not Ready

# Always wait for environment to be ready
await env.wait_for_ready()  # Async version
# OR
env.wait_for_ready()  # Sync version

​
2. Session Not Initialized

# Reset environment to initialize session
await env.reset()  # Async version - required before getting cdp_url
# OR  
env.reset()  # Sync version - required before getting cdp_url

​
Required Environment Variables

# Required
PLATO_API_KEY=your_api_key
Remember to always close the environment when you’re done to free up resources.
You can find the official example script for custom browser setup in our GitHub repository at custom_browser_environment.py.