sdk-dev
6a1b2bf1a1
The repo was restructured from sdk/python/ to top-level molecule_agent/ and molecule_plugin/. Four doc references still pointed to sdk/python/: - molecule_agent/__init__.py: sdk/python/examples/remote-agent/ → examples/remote-agent/ - molecule_agent/README.md: sdk/python/examples/remote-agent/ → examples/remote-agent/ - molecule_plugin/__init__.py: sdk/python/README.md → repo root README.md - examples/remote-agent/README.md: sdk/python/examples/remote-agent/run.py → examples/remote-agent/run.py Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
64 lines
2.5 KiB
Markdown
64 lines
2.5 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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 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).
|