Golden Image
Backend workers
Add a Python (FastAPI) or Node worker only for external APIs, server-side secrets or heavy computation. The worker SDK handles the gateway contract.
Choosing
Add exactly one of "backend" (Python, backend/) or "backend-node" (Node, backend-node/) to parts in project.json, then run make setup again. One app never uses both runtimes.
The files you edit are agent/app.py (or agent/app.ts) and agents.json. Execution token verification, the handshake, serving /.well-known/agents.json and resource adapter routing are the worker SDK's (worker-sdk-python, worker-sdk-node).
A Python worker
from pydantic import BaseModel, ConfigDict, Field
from mothership_worker import GatewayError, Worker, WorkerContext, t
worker = Worker(agent_id=MANIFEST["agent"]["id"], manifest=MANIFEST)
app = worker.app
class AnalyzeInput(BaseModel):
text: str
class AnalyzeOutput(BaseModel):
model_config = ConfigDict(populate_by_name=True)
word_count: int = Field(alias="wordCount")
preview: str
@worker.operation(id="text.analyze", version="1.0", input_model=AnalyzeInput,
output_model=AnalyzeOutput, idempotency="supported", timeout_ms=10_000)
async def analyze(_context: WorkerContext, request: AnalyzeInput) -> AnalyzeOutput:
words = request.text.split()
return AnalyzeOutput(word_count=len(words), preview=" ".join(words[:12]))
# An adapter that wraps an external API as read-only shared data
@worker.resource_list("sample-items")
async def list_items(_context: WorkerContext, query: dict) -> dict:
return {"items": [{"id": "item-1", "value": {"title": "First example"}}]}
The Node worker (backend-node/agent/app.ts) has the same shape: new Worker({ agentId, manifest }), worker.operation(...), worker.resource("sample-items", { … }).
What it offers
| Kind | Called with | Note |
|---|---|---|
| Operations (capabilities) | ctx.api.capabilities.invoke |
Synchronous |
| Jobs | ctx.api.capabilities.start + ctx.jobs.wait/subscribe/cancel |
Progress and cancellation handled by the worker SDK. At most once, no automatic retry |
| Streams | :stream |
The worker's SSE passed through |
| Shared resources | ctx.data.list("<backend-id>/<resource>") |
Read-only; opened by allowed_consumers and admin grants |
Inside the worker, context offers AI, Runtime, connectors, artifact creation and job subscriptions too, using the execution token attached to the worker; subscriptions can't outlive its authorization window.
Pairing with the frontend
With both halves in parts, the build checks the pairing: the frontend's capabilities.requires and resource_requests against the backend's provides, resources and allowed_consumers. preview.sh emits one register-batch payload that registers the whole project at once.
Deploying and connecting
- Make a pre-shared signing key (32 characters or more) and set it as
EXECUTION_SIGNING_SECRETin the deployment.make setupwrites one into the local.env(without printing it). - Build the Docker image (
backend/Dockerfile,backend-node/Dockerfile) and run it where Mothership can reach it. Prefer https (plain http registers with atransport_unencryptedwarning). - In Mothership Catalog → External backend connection · advanced, enter the URL and the same key. Registration checks
/healthand proves the key with/v1/handshakebefore publishing, so a mistyped key fails at registration, not on the first call. - From then on the gateway signs each call with a short-lived HS256 execution token that the worker verifies.
During development, bash scripts/preview.sh --host <internal host Mothership reaches> starts the backend and writes its URL and signing secret to .preview/registration.json (owner-only).