Plato Python SDK (v2)

2.62.4 · active · verified Thu Apr 16

The Plato Python SDK (v2) provides a powerful interface for browser automation and task execution, enabling developers to efficiently create and manage browser environments and execute tasks. It is currently at version 2.62.4 and is under active development, with frequent updates indicated by recent changelogs.

Common errors

```
Error: PLATO_API_KEY environment variable not set.
```
cause The Plato SDK requires an API key for authentication, which is typically read from the `PLATO_API_KEY` environment variable.

fix Set the `PLATO_API_KEY` environment variable in your shell (e.g., `export PLATO_API_KEY="your_api_key_here"` on Linux/macOS or `SET PLATO_API_KEY=your_api_key_here` on Windows) or pass it directly when initializing `AsyncPlato` (e.g., `AsyncPlato(api_key="...")`).
```
Session not starting / connection issues
```
cause Problems creating or connecting to a session can stem from network connectivity issues or incorrect/insufficient permissions associated with the provided API key.

fix Verify your internet connection. Double-check that your `PLATO_API_KEY` is correct and has the necessary permissions for the requested operations by checking your Plato dashboard.
```
AttributeError: module 'plato' has no attribute 'Plato' or ImportError: cannot import name 'Plato' from 'plato'
```
cause This typically occurs when trying to use the older SDK v1 import patterns with `plato-sdk-v2`, which has moved core components to the `plato.v2` submodule.

fix Update your import statements to use `from plato.v2 import AsyncPlato, Env` (or other v2-specific symbols) and adjust your code to the new v2 API structure.

Warnings

breaking The SDK v2 introduces significant API changes, moving from direct `Plato` and `PlatoTask` objects to `AsyncPlato` for client interaction and `sessions` for environment management. Code written for SDK v1.x will not be compatible with v2 without modifications.
Fix: Update imports from `from plato import ...` to `from plato.v2 import ...`. Refactor client and environment management to use `AsyncPlato` and `session` objects as per the v2 documentation.
gotcha API keys should be managed securely, preferably via the `PLATO_API_KEY` environment variable. Directly embedding API keys in code is discouraged for security reasons.
Fix: Set the `PLATO_API_KEY` environment variable. The `AsyncPlato` client will automatically pick it up. If explicit passing is required (e.g., for multiple keys), ensure secure handling.
gotcha Browser environments and sessions must be explicitly closed using `await session.close()` and `await plato.close()` within a `try...finally` block to prevent resource leaks and ensure proper cleanup.
Fix: Always wrap your session and client usage in `try...finally` blocks to guarantee that `await session.close()` and `await plato.close()` are called, even if errors occur.

Install

pip install plato-sdk-v2 Install with pip
uv add plato-sdk-v2 Install with uv

Imports

AsyncPlato, Env
wrong:
```
from plato import Plato, PlatoTask
```
correct:
```
from plato.v2 import AsyncPlato, Env
```
The v2 SDK introduces a new API under `plato.v2`, replacing the `Plato` client and `PlatoTask` from previous versions.

Quickstart

This quickstart demonstrates how to initialize the `AsyncPlato` client, create and manage a session with a simulated environment, execute commands, retrieve state, and ensure proper cleanup. It relies on the `PLATO_API_KEY` environment variable for authentication.

import asyncio
import os
from plato.v2 import AsyncPlato, Env

async def main():
    # Ensure PLATO_API_KEY environment variable is set
    # export PLATO_API_KEY="your_api_key_here"
    if not os.environ.get("PLATO_API_KEY"):
        print("Error: PLATO_API_KEY environment variable not set.")
        print("Please generate your API key from the Plato dashboard and set it.")
        return

    # Initialize the client
    plato = AsyncPlato()

    # Create a session with an example environment (e.g., 'espocrm' simulator)
    session = await plato.sessions.create(
        envs=[Env.simulator("espocrm")]
    )

    try:
        # Reset the environment to its initial state
        await session.reset()

        # Get the public URL to access the application (if applicable)
        urls = await session.get_public_url()
        print(f"Access your environment at: {urls}")

        # Execute a command within the environment
        result = await session.execute("whoami")
        print(f"Running as: {result}")

        # Get the current state of the environment
        state = await session.get_state()
        print(f"State: {state}")

    except Exception as e:
        print(f"An error occurred: {e}")
    finally:
        # Always clean up and close the session
        await session.close()
        await plato.close()

if __name__ == "__main__":
    asyncio.run(main())

view raw JSON →