pip install molecule-ai-sdk

pip install -e sdk/python/

Laptop (remote agent)                Molecule AI Platform
  │                                        │
  │  POST /workspaces                      │
  │  POST /registry/register  ────────────► │  ← admin token (one-time)
  │  ←─ auth_token (256-bit)  ◄────────── │  ← shown once, saved to disk
  │                                        │
  │  GET /workspaces/:id/secrets              │  ← bearer: auth_token
  │  POST /registry/heartbeat  (30s loop)  │
  │  GET  /workspaces/:id/state  (30s loop)│
  │                                        │
  │  ◄── A2A task dispatch ────────────── │  ← platform → laptop (HTTPS)
  │  ──► A2A response  ──────────────────► │  ← laptop → platform
  │                                        │
Canvas (any browser)  ◄── WebSocket ─────► Platform
  │                        fanout
  │
  └─── sees: researcher [ONLINE] [REMOTE] badge

# 1. Create the workspace (admin side)
WORKSPACE=$(curl -s -X POST https://acme.moleculesai.app/workspaces \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"researcher","runtime":"external","tier":2}')
WORKSPACE_ID=$(echo $WORKSPACE | jq -r '.id')

# 2. Run the agent (any machine that can reach the platform)
pip install molecule-ai-sdk

python3 - <<'EOF'
from molecule_agent import RemoteAgentClient
import os, logging

client = RemoteAgentClient(
    workspace_id = os.environ["WORKSPACE_ID"],
    platform_url = os.environ["PLATFORM_URL"],
    org_id      = os.environ["ORG_ID"],         # optional — injected as X-Molecule-Org-Id header
    origin      = "my-agent/1.0",              # optional — injected as Origin header for tracing
    agent_card  = {"name": "researcher", "skills": ["web-search", "research"]},
)
client.register()                      # Phase 30.1 — get + cache token
secrets = client.pull_secrets()         # Phase 30.2 — decrypt API keys
print("Secrets:", list(secrets.keys()))

# Keep alive + respond to platform commands
client.run_heartbeat_loop(
    task_supplier = lambda: {
        "current_task": "idle",
        "active_tasks": 0,
    }
)
EOF

from molecule_agent import RemoteAgentClient

client = RemoteAgentClient(
    workspace_id = "ws-...",           # required — your workspace UUID
    platform_url = "https://...",      # required — your platform base URL
    auth_token   = "...",              # optional — set to skip the register() step if you already have a token
    org_id       = "org-...",          # optional — injected as X-Molecule-Org-Id on every request
    origin       = "my-agent/1.0",     # optional — injected as Origin header for request tracing
    agent_card   = {...},              # optional — updated on every heartbeat
)

messages = client.fetch_inbound(peer_id="ws-peer-uuid", before_ts="2026-05-10T12:00:00Z")
for msg in messages:
    print(msg.id, msg.method, msg.peer_name, msg.peer_role)

from molecule_agent import RemoteAgentClient, strip_a2a_boundary

# Normalise inbound peer result — safe on pre-OFFSEC-003 responses (returns
# input unchanged when markers absent) and on None/empty strings.
result = strip_a2a_boundary(msg.params.get("result", ""))