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

backend/agent/app.py
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

  1. Make a pre-shared signing key (32 characters or more) and set it as EXECUTION_SIGNING_SECRET in the deployment. make setup writes one into the local .env (without printing it).
  2. Build the Docker image (backend/Dockerfile, backend-node/Dockerfile) and run it where Mothership can reach it. Prefer https (plain http registers with a transport_unencrypted warning).
  3. In Mothership Catalog → External backend connection · advanced, enter the URL and the same key. Registration checks /health and proves the key with /v1/handshake before publishing, so a mistyped key fails at registration, not on the first call.
  4. 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).

Esc