plato-sdk-v2 2.107.0

Python SDK for the Plato API

Plato Python SDK

Python SDK for the Plato platform.

Installation

pip install plato-sdk-v2

# For agent functionality (requires Python 3.12+)
pip install 'plato-sdk-v2[agents]'

Or with uv:

uv add plato-sdk-v2
uv add 'plato-sdk-v2[agents]'  # for agent support

Configuration

Create a .env file in your project root:

PLATO_API_KEY=your-api-key
PLATO_BASE_URL=https://plato.so  # optional, defaults to https://plato.so

Or set environment variables directly:

export PLATO_API_KEY=your-api-key

Agents

Agents run inside Plato VMs. The first-party agent is computer-use (browser automation, install: pip install plato-agent-computer-use); custom agents subclass plato.agents.BaseAgent.

Python Usage

from plato.agents import BaseAgent, AgentTask, run_agent, get_agent_schema, AGENT_SCHEMAS

# List available agent config schemas
print(list(AGENT_SCHEMAS.keys()))

CLI Usage

# List available agents
plato agent list

# Get agent config schema
plato agent schema computer-use

# Publish a custom agent to Plato PyPI
plato agent publish ./my-agent

Agent Schemas

Get configuration schemas for any agent:

from plato.agents import get_agent_schema, AGENT_SCHEMAS

# Get schema for specific agent
schema = get_agent_schema("claude-code")
print(schema)

# List all available schemas
print(list(AGENT_SCHEMAS.keys()))

Custom Agents

Create a custom agent by subclassing plato.agents.BaseAgent (see plato/agents/base.py for the interface).

Publish to Plato PyPI:

plato agent publish ./my-agent-package

---

Sessions & Environments

Flow 1: Create Session from Environments

Use this when you want to spin up environments for development, testing, or custom automation.

import asyncio
from plato.v2 import AsyncPlato, Env

async def main():
    plato = AsyncPlato()

    # Create session with one or more environments
    # (heartbeat starts automatically to keep session alive)
    session = await plato.sessions.create(
        envs=[
            Env.simulator("gitea", dataset="blank", alias="gitea"),
            Env.simulator("kanboard", alias="kanboard"),
        ],
        timeout=600,
    )

    # Reset environments to initial state
    await session.reset()

    # Get public URLs for browser access
    public_urls = await session.get_public_url()
    for alias, url in public_urls.items():
        print(f"{alias}: {url}")

    # Get state mutations from all environments
    state = await session.get_state()
    print(state)

    # Cleanup
    await session.close()
    await plato.close()

asyncio.run(main())

Flow 2: Create Session from Task

Use this when running evaluations against predefined tasks. This flow includes task evaluation at the end.

import asyncio
from plato.v2 import AsyncPlato

async def main():
    plato = AsyncPlato()

    # Create session from task ID
    session = await plato.sessions.create(task=123, timeout=600)

    # Reset environments to initial state
    await session.reset()

    # Get public URLs for browser access
    public_urls = await session.get_public_url()
    for alias, url in public_urls.items():
        print(f"{alias}: {url}")

    # Evaluate task completion
    evaluation = await session.evaluate()
    print(f"Task completed: {evaluation}")

    # Cleanup
    await session.close()
    await plato.close()

asyncio.run(main())

Environment Configuration

Two ways to specify environments:

from plato.v2 import Env

# 1. From simulator (most common)
Env.simulator("gitea")                          # default tag
Env.simulator("gitea", tag="staging")           # specific tag
Env.simulator("gitea", dataset="blank")         # specific dataset
Env.simulator("gitea", alias="my-git")          # custom alias

# 2. From artifact ID
Env.artifact("artifact-abc123")
Env.artifact("artifact-abc123", alias="my-env")

Per-Environment Operations

Access individual environments within a session:

# Get all environments
for env in session.envs:
    print(f"{env.alias}: {env.job_id}")

# Get specific environment by alias
gitea = session.get_env("gitea")

if gitea:
    # Execute shell command
    result = await gitea.execute("whoami", timeout=30)
    print(result)

    # Get state for this environment only
    state = await gitea.get_state()

    # Reset this environment only
    await gitea.reset()

Sync Client

A synchronous client is also available:

from plato.v2 import Plato, Env

plato = Plato()

session = plato.sessions.create(
    envs=[Env.simulator("gitea", alias="gitea")],
    timeout=600,
)

session.reset()

public_urls = session.get_public_url()
state = session.get_state()

session.close()
plato.close()

Architecture

plato/
├── agents/          # Agent SDK (BaseAgent, AgentTask, run_agent) + schemas
├── sims/            # Simulator clients (Spree, Firefly, etc.)
├── world/           # World/environment abstractions
├── v1/              # Legacy SDK + CLI
└── v2/              # New API client

Documentation

• Generating Simulator SDKs - How to create API clients for simulators
• Building Simulators - Internal docs for snapshotting simulators