Golden Image

백엔드 worker

외부 API, 서버 쪽 비밀키, 무거운 계산이 필요할 때만 Python(FastAPI)이나 Node worker를 더해요. 게이트웨이 계약은 worker SDK가 맡아요.

고르기

project.json의 parts에 "backend"(Python, backend/) 또는 "backend-node"(Node, backend-node/)를 하나만 더해요. 고친 뒤 make setup을 다시 해요. 앱 하나가 두 런타임을 같이 쓰지는 않아요.

고치는 파일은 agent/app.py(또는 agent/app.ts)와 agents.json뿐이에요. 실행 토큰 검증, handshake, /.well-known/agents.json 내주기, 자원 adapter 연결은 worker SDK(worker-sdk-python, worker-sdk-node)가 해요.

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]))

# 외부 API를 감싸 읽기 전용 공용 데이터로 내놓는 adapter
@worker.resource_list("sample-items")
async def list_items(_context: WorkerContext, query: dict) -> dict:
    return {"items": [{"id": "item-1", "value": {"title": "첫 번째 예시"}}]}

Node worker(backend-node/agent/app.ts)도 같은 모양이에요: new Worker({ agentId, manifest }), worker.operation(...), worker.resource("sample-items", { … }).

내놓는 것

종류 부르는 법 메모
동작(capability, operation) ctx.api.capabilities.invoke 동기 호출
작업(job) ctx.api.capabilities.start + ctx.jobs.wait/subscribe/cancel 진행 보고와 취소는 worker SDK가 처리. 한 번까지 실행, 자동 재시도 없음
스트림 :stream worker의 SSE를 그대로 흘려요
공용 자원 ctx.data.list("<backend-id>/<resource>") 읽기 전용. allowed_consumers와 관리자 허용으로 열어요

worker 안에서도 context로 AI, Runtime, 커넥터, 결과물 만들기, 작업 구독을 쓸 수 있어요. worker에 붙은 실행 토큰을 쓰고, 구독은 그 권한 시간을 넘지 못해요.

프런트엔드와 짝

parts에 둘 다 있으면 빌드가 짝을 검사해요: 프런트엔드의 capabilities.requires·resource_requests ↔ 백엔드의 provides·resources·allowed_consumers. preview.sh는 프로젝트 전체를 한 번에 등록할 register-batch 내용을 만들어요.

배포와 연결

  1. 미리 나눈 서명 키(32자 이상)를 만들어 배포 환경의 EXECUTION_SIGNING_SECRET에 둬요. make setup이 로컬 .env에 만들어 줘요(찍지는 않아요).
  2. Docker 이미지로 만들어(backend/Dockerfile, backend-node/Dockerfile) Mothership이 닿는 곳에 띄워요. https를 권해요(http면 transport_unencrypted 경고).
  3. Mothership 카탈로그 관리 → 외부 백엔드 연결 · 고급에 URL과 같은 키를 넣어요. 등록이 /health를 확인하고 /v1/handshake로 키를 맞춰 본 뒤에야 게시해요. 키가 틀리면 첫 호출이 아니라 등록에서 실패해요.
  4. 그다음 게이트웨이는 호출마다 짧은 HS256 실행 토큰으로 서명하고, worker는 그것을 검증해요.

개발 중에는 bash scripts/preview.sh --host <Mothership이 닿는 내부 호스트>가 백엔드를 띄우고 .preview/registration.json(소유자만 읽기)에 URL과 서명 키를 써요.

Esc