molecule-ai/molecule-sdk-python

Fork 0

Files

T

History

sdk-dev d6c2b701b6

[Do] Merge queue: CI checks green, merge queue ready

Details

sop-checklist / all-items-acked SOP checklist acknowledged

Details

Test / test (3.12) (pull_request) Successful in 1m30s

Details

Test / test (3.11) (pull_request) Successful in 1m45s

Details

Test / test (3.13) (pull_request) Successful in 1m33s

Details

fix(examples): correct stale import path in remote-agent/run.py

The old path `sdk/python/` no longer exists in the standalone
molecule-sdk-python repo. Update the local-dev import path to add
the repo root to sys.path, which correctly resolves molecule_agent
when running the script from a repo checkout.

Also update the Usage section to use the correct relative path
(`examples/remote-agent/run.py` instead of `python3 run.py`)
and update the "What it doesn't do" docstring to reflect that
Phase 30.8b (inbound A2A) is now shipped.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

2026-05-16 20:36:12 +00:00

README.md

feat: initial Python SDK (extracted from molecule-monorepo/sdk/python)

2026-04-16 03:15:38 -07:00

run.py

fix(examples): correct stale import path in remote-agent/run.py

2026-05-16 20:36:12 +00:00

README.md

Remote agent demo

A ~100-line Python script that registers with a Molecule AI platform from outside its Docker network, pulls its secrets, and heartbeats — exercising the Phase 30.1 / 30.2 / 30.4 endpoints end-to-end.

Prerequisites

A running Molecule AI platform (./infra/scripts/setup.sh + go run ./cmd/server from platform/)
pip install requests in your Python environment

Quick start

# 1. Create the workspace row on the platform. `external` runtime keeps
#    the provisioner from trying to start a Docker container:
curl -s -X POST http://localhost:8080/workspaces \
    -H 'Content-Type: application/json' \
    -d '{"name":"remote-demo","tier":2,"runtime":"external"}'
# → {"id":"<UUID>", ...}

# 2. (Optional) seed a secret so `pull_secrets` has something to return:
curl -s -X POST http://localhost:8080/workspaces/<UUID>/secrets \
    -H 'Content-Type: application/json' \
    -d '{"key":"REMOTE_DEMO_KEY","value":"hello-from-remote"}'

# 3. Run the demo from any machine that can reach the platform:
WORKSPACE_ID=<UUID> PLATFORM_URL=http://localhost:8080 \
    python3 sdk/python/examples/remote-agent/run.py

You should see log lines for each of the three phases, and then heartbeat lines every 5s. The workspace should appear online on the canvas. Pause or delete it from the canvas / via API, and the script exits cleanly.

What this demonstrates

Phase	Endpoint	Shown in the demo
30.1	`POST /registry/register`	Token issuance + on-disk caching
30.1	`POST /registry/heartbeat`	Bearer-authenticated liveness report
30.2	`GET /workspaces/:id/secrets/values`	Token-gated decrypted-secrets pull
30.4	`GET /workspaces/:id/state`	Token-gated pause/delete detection

What it doesn't do yet

No inbound A2A server. Other agents can't initiate calls back to this remote agent. Future 30.8b adds an optional HTTP server helper.
No sibling discovery. Future 30.6 adds peer URL caching so this agent can call siblings directly instead of going through the proxy.

Troubleshooting

401 missing workspace auth token on the secrets/state calls — your cached token is stale (workspace was recreated). Delete ~/.molecule/<workspace_id>/.auth_token and re-run.
connection refused — double-check PLATFORM_URL and that the platform is actually listening.
Workspace never appears as online on the canvas — confirm it was created with runtime: external (otherwise the provisioner will try to start a local container and fail).