Skip to content

Latest commit

 

History

History
259 lines (191 loc) · 6.16 KB

README.md

File metadata and controls

259 lines (191 loc) · 6.16 KB

Simplex Python SDK & CLI

Official Python SDK and CLI for the Simplex browser automation platform.

Python Version License: MIT

Installation

pip install simplex

This installs both the Python SDK (from simplex import SimplexClient) and the CLI (simplex command).

Authentication

# Option 1: Environment variable
export SIMPLEX_API_KEY="your-api-key"

# Option 2: Login command (saves to ~/.simplex/credentials)
simplex login

Claude Code Plugin

Give Claude Code full knowledge of the Simplex CLI and SDK:

/plugin install simplexlabs/simplex-python

Once installed, Claude Code automatically knows how to use simplex editor, simplex connect, simplex run, and the full Python SDK.

CLI

simplex editor — Create a workflow and start an interactive session

simplex editor --name "My Workflow" --url "https://example.com"
simplex editor -n "My Workflow" -u "https://example.com" --var key=value
simplex editor -n "Test" -u "https://example.com" --json

Creates a workflow, starts a browser session, and streams live agent events. Prints session info (session_id, workflow_id, vnc_url) then streams SSE events until Ctrl+C.

simplex connect — Stream events from a running session

simplex connect <session_id>
simplex connect "https://host:port/stream" --json

simplex run — Run an existing workflow

simplex run <workflow_id>
simplex run <workflow_id> --var email=test@test.com --watch

simplex send — Send a message to a running session

simplex send <session_id> "Click the login button"

simplex pause / simplex resume

simplex pause <session_id>
simplex resume <session_id>

simplex workflows list

simplex workflows list --name "search term"

simplex sessions

simplex sessions status <session_id>
simplex sessions logs <session_id>
simplex sessions download <session_id> --filename report.pdf --output ./report.pdf
simplex sessions replay <session_id> --output replay.mp4

simplex login / whoami / logout

simplex login       # Prompts for API key
simplex whoami      # Shows current auth status
simplex logout      # Removes saved credentials

Python SDK

Quick Start

from simplex import SimplexClient

client = SimplexClient(api_key="your-api-key")

# Start an interactive editor session
result = client.start_editor_session(
    name="My Session",
    url="https://example.com",
    test_data={"username": "test"},
)
print(f"Session: {result['session_id']}")
print(f"VNC: {result['vnc_url']}")

# Stream live events
for event in client.stream_session(result["logs_url"]):
    print(event)

# Send a message to the agent
client.send_message(result["message_url"], "Click the login button")

# Close the session
client.close_session(result["session_id"])

Client

client = SimplexClient(
    api_key="your-api-key",
    base_url="https://api.simplex.sh",  # Optional
    timeout=30,                          # Request timeout in seconds
    max_retries=3,                       # Retry attempts
    retry_delay=1.0,                     # Delay between retries
)

Workflow Management

# Create
result = client.create_workflow(name="My Workflow", url="https://example.com")
workflow_id = result["workflow"]["id"]

# Get
workflow = client.get_workflow(workflow_id)

# Update
client.update_workflow(workflow_id, name="New Name", url="https://new-url.com")

# Search
results = client.search_workflows(workflow_name="search term")

Editor Sessions

# Start an editor session (creates workflow + browser session)
# NOTE: Takes 10-15 seconds. Use timeout=120.
result = client.start_editor_session(
    name="My Session",
    url="https://example.com",
    test_data={"username": "test"},
)
# Returns: succeeded, workflow_id, session_id, vnc_url, logs_url, message_url, filesystem_url

# Stream live SSE events
for event in client.stream_session(result["logs_url"]):
    event_type = event.get("event") or event.get("type", "")
    print(f"[{event_type}] {event}")

# Send a message to the agent
client.send_message(result["message_url"], "Click the login button")

Run Workflows

import time

result = client.run_workflow("workflow-id", variables={"key": "value"})

# Poll for completion
while True:
    status = client.get_session_status(result["session_id"])
    if not status["in_progress"]:
        break
    time.sleep(2)

if status["success"]:
    print(status["scraper_outputs"])
    print(status["structured_output"])

Session Management

client.pause(session_id)
client.resume(session_id)
client.close_session(session_id)
client.get_session_status(session_id)
client.retrieve_session_logs(session_id)
client.download_session_files(session_id)
client.retrieve_session_replay(session_id)

SSE Event Format

Events from stream_session() are dicts. The event type is in the event key:

Event Description
RunContent Agent text output
ToolCallStarted Tool invocation started
ToolCallCompleted Tool result
FlowPaused Session paused
FlowResumed Session resumed
RunCompleted Agent finished
RunError Error occurred

Error Handling

from simplex import (
    SimplexError,
    AuthenticationError,
    RateLimitError,
    NetworkError,
    ValidationError,
    WorkflowError,
)

try:
    result = client.run_workflow("workflow-id")
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except WorkflowError as e:
    print(f"Workflow error: {e.message}, session: {e.session_id}")
except SimplexError as e:
    print(f"Error: {e.message}")

Requirements

  • Python 3.9+
  • requests>=2.25.0

License

MIT License - see LICENSE for details.

Links