From bb3e1c78cec5ef65718d101bbde4fd4fe1c25e30 Mon Sep 17 00:00:00 2001 From: Molecule AI Documentation Specialist Date: Sun, 10 May 2026 14:03:20 +0000 Subject: [PATCH] docs(remote-workspaces): document SDK Python new RemoteAgentClient params MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Pair PRs molecule-sdk-python #5, #6, #7: - Add org_id + origin constructor kwargs to RemoteAgentClient example - Add RemoteAgentClient API reference section (constructor params, fetch_inbound, InboundMessage) - Add changelog entries for #5, #6, #7 under 2026-05-10 ✨ New features Co-Authored-By: Claude Opus 4.7 --- content/docs/changelog.mdx | 3 ++ content/docs/guides/remote-workspaces.md | 66 +++++++++++++++++++++++- 2 files changed, 68 insertions(+), 1 deletion(-) diff --git a/content/docs/changelog.mdx b/content/docs/changelog.mdx index e80786a..467add7 100644 --- a/content/docs/changelog.mdx +++ b/content/docs/changelog.mdx @@ -90,6 +90,9 @@ Entries are published daily at 23:50 UTC. - **Static `.github-token` fallback to git credential helper**: workspace-server now falls back to a static `.github-token` value when no git credential helper is configured, enabling simpler air-gapped setups. (`molecule-core` [#219](https://git.moleculesai.app/molecule-ai/molecule-core/pull/219)) - **Keyboard shortcuts in Toolbar help dialog**: all keyboard shortcuts are now documented in a Toolbar help dialog accessible from the canvas top bar. (`molecule-core` [#244](https://git.moleculesai.app/molecule-ai/molecule-core/pull/244)) - **HTTP/SSE transport for Hermes MCP**: `a2a_mcp_server.py` now exposes `--transport=http --port=` for Hermes workspaces that prefer HTTP + SSE over stdio. Endpoints: `POST /mcp` (JSON-RPC), `GET /mcp/stream` (SSE), `GET /health`. (`molecule-ai-workspace-runtime` [#5](https://git.moleculesai.app/molecule-ai/molecule-ai-workspace-runtime/pull/5)) +- **RemoteAgentClient `org_id` and `origin` kwargs**: `RemoteAgentClient` now accepts `org_id` (injected as `X-Molecule-Org-Id` header) and `origin` (injected as `Origin` header for request tracing) as constructor kwargs. Both propagate to all 14+ outbound call sites automatically via `_auth_headers()`. (`molecule-sdk-python` [#7](https://git.moleculesai.app/molecule-ai/molecule-sdk-python/pull/7)) +- **RemoteAgentClient `fetch_inbound()` filter params**: `fetch_inbound()` now accepts `peer_id` (narrow to a specific peer's messages) and `before_ts` (RFC3339 timestamp for cursor-based pagination). Enables agents to selectively consume inbound activity from known siblings. (`molecule-sdk-python` [#6](https://git.moleculesai.app/molecule-ai/molecule-sdk-python/pull/6)) +- **InboundMessage enrichment fields**: `InboundMessage` now exposes typed `peer_name`, `peer_role`, and `agent_card_url` attributes, surfaced from the platform's peer registry at dispatch time. Previously these were only accessible via the raw channel envelope. (`molecule-sdk-python` [#5](https://git.moleculesai.app/molecule-ai/molecule-sdk-python/pull/5)) ### 🔧 Fixes diff --git a/content/docs/guides/remote-workspaces.md b/content/docs/guides/remote-workspaces.md index ed34a4f..612e637 100644 --- a/content/docs/guides/remote-workspaces.md +++ b/content/docs/guides/remote-workspaces.md @@ -110,7 +110,9 @@ import os, logging client = RemoteAgentClient( workspace_id = os.environ["WORKSPACE_ID"], platform_url = os.environ["PLATFORM_URL"], - agent_card = {"name": "researcher", "skills": ["web-search", "research"]}, + 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 @@ -130,6 +132,68 @@ The agent appears on the canvas with a **purple REMOTE badge** within seconds. F --- +## RemoteAgentClient API Reference + +### Constructor + +```python +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 +) +``` + +| Parameter | Type | Description | +|---|---|---| +| `workspace_id` | `str` | Your workspace UUID, obtained from `POST /workspaces`. | +| `platform_url` | `str` | Your platform base URL, e.g. `https://acme.moleculesai.app`. | +| `auth_token` | `str` | Pre-obtained bearer token. If omitted, call `register()` to fetch one. | +| `org_id` | `str` | Optional org UUID. When set, injected as `X-Molecule-Org-Id` on every outbound request. | +| `origin` | `str` | Optional UA string (e.g. `"researcher/2.1"`). Injected as `Origin` header for logging/tracing. | +| `agent_card` | `dict` | Agent metadata broadcast to the canvas. Updated on every heartbeat. | + +### fetch_inbound(peer_id=, before_ts=) + +Poll for inbound A2A messages directed at this workspace: + +```python +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) +``` + +| Parameter | Type | Description | +|---|---|---| +| `peer_id` | `str` | Filter to messages from a specific peer workspace UUID. Omit to receive from all peers. | +| `before_ts` | `str` | RFC3339 timestamp. Return only messages older than this cut-off. Use for pagination by tracking the oldest message seen. | + +Returns a list of `InboundMessage` objects. + +### InboundMessage + +Each inbound message carries these fields in addition to the standard A2A fields: + +| Field | Type | Description | +|---|---|---| +| `id` | `str` | Message ID. | +| `method` | `str` | A2A method (`delegate_task`, `cancel_task`, etc.). | +| `params` | `dict` | Method parameters. | +| `peer_id` | `str` | UUID of the peer workspace that sent this message. | +| `peer_name` | `str` | Display name of the sending peer (from its agent card). | +| `peer_role` | `str` | Role of the sending peer (`"sre"`, `"frontend"`, etc.). | +| `agent_card_url` | `str` | URL of the sending peer's agent card. | +| `raw` | `dict` | Raw channel envelope for forward-compatibility. | + +> **Note:** `peer_name`, `peer_role`, and `agent_card_url` are enriched from the platform's peer registry at dispatch time. They are `None` if the sending peer has not registered an agent card. + +--- + ## What Phase 30 Covers | Phase | What shipped | Endpoint |