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
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 내용을 만들어요.
배포와 연결
- 미리 나눈 서명 키(32자 이상)를 만들어 배포 환경의
EXECUTION_SIGNING_SECRET에 둬요.make setup이 로컬.env에 만들어 줘요(찍지는 않아요). - Docker 이미지로 만들어(
backend/Dockerfile,backend-node/Dockerfile) Mothership이 닿는 곳에 띄워요. https를 권해요(http면transport_unencrypted경고). - Mothership 카탈로그 관리 → 외부 백엔드 연결 · 고급에 URL과 같은 키를 넣어요. 등록이
/health를 확인하고/v1/handshake로 키를 맞춰 본 뒤에야 게시해요. 키가 틀리면 첫 호출이 아니라 등록에서 실패해요. - 그다음 게이트웨이는 호출마다 짧은 HS256 실행 토큰으로 서명하고, worker는 그것을 검증해요.
개발 중에는 bash scripts/preview.sh --host <Mothership이 닿는 내부 호스트>가 백엔드를 띄우고 .preview/registration.json(소유자만 읽기)에 URL과 서명 키를 써요.