Golden Image

SDK로 쓰는 기능

프런트엔드만으로 데이터, 상태, 파일, AI, 지식 검색, Runtime, 커넥터, 작업을 써요. 백엔드를 만들기 전에 여기서 먼저 찾아요.

필요한 것 SDK 메모
레코드 저장·조회 ctx.data manifest의 record_schema. 목록 필터는 eq만, 정렬은 클라이언트에서
키·값 상태 ctx.storage.state state_namespaces + value_schema. 키 prefix 필터
파일 ctx.files 사용자가 준 파일, 다른 기능(AI 첨부, 지식, 변환)에 건넬 blob
앱이 소유하는 blob ctx.storage.objects 논리 키, 버전. manifest 선언 필요
AI ctx.api.ai.generate / stream / embeddings 등급 fast·smart·deep
지식 검색(RAG) ctx.knowledge 청킹과 임베딩은 게이트웨이가 해요
다른 앱의 기능·데이터 ctx.api.capabilities.invoke, ctx.data.list("<provider>/<res>") manifest에 capabilities.requires, resource_requests
외부 도구(MCP) ctx.api.connectors.listTools / invoke 관리자가 등록한 커넥터 + connector_requests
오래 걸리는 실행 ctx.api.runtime.start / subscribe / resume / cancel runtime_profiles
작업 기다리기 ctx.jobs.wait / subscribe / cancel 변환·수집·백엔드 job

AI

ts
const { text } = await ctx.api.ai.generate({
  profile: "smart",                                  // 빼면 smart
  messages: [{ role: "user", content: "이 계약의 위험 조항을 정리해 줘" }],
  attachments: [{ fileId }],                         // 파일 내용을 직접 붙이지 말고 첨부로
  responseSchema: { type: "object", properties: { risks: { type: "array", items: { type: "string" } } } },
});

for await (const e of ctx.api.ai.stream({ profile: "fast", messages })) {
  if (e.type === "response.delta") append(e.delta);
}

지식 검색

ts
const file = await ctx.files.upload(selectedFile);
const queued = await ctx.knowledge.ingest(
  { collectionId: "review-documents", fileId: file.fileId, title: file.name, scope: "user_private" },
  { idempotencyKey: `ingest:${file.fileId}` },
);
await ctx.jobs.wait(queued.jobId);
const document = await ctx.knowledge.get(queued.documentId);
if (document.status !== "ready") throw new Error(document.error?.message ?? document.status);
const results = await ctx.knowledge.search({
  collections: ["review-documents"], documentIds: [document.documentId],
  query: "승인이 필요한 일은?", topK: 6,
});
  • files.list, knowledge.list, files.artifactsPage는 { items, nextCursor }를 돌려줘요. 커서는 그대로 다음 요청에 넘겨요.
  • 작업이 끝났다고 성공은 아니에요. 작업이나 문서의 상태를 확인해요.
  • Idempotency-Key는 같은 요청에만 다시 써요. 다른 요청에 같은 키를 쓰면 409 idempotency_conflict예요.

Runtime

ts
const run = await ctx.api.runtime.start({ profile: "review", input: { question: "올린 보고서를 요약해 줘" } });
for await (const event of ctx.api.runtime.subscribe(run.runId, { transport: "sse", signal })) {
  // event.sequence를 저장해 두면 afterSequence로 이어서 받아요
}
const latest = await ctx.api.runtime.get(run.runId);

질문 interrupt는 decision: "submit"과 inputSchema에 맞는 input으로, 승인·동의는 "approve"/"deny"로 이어 가요. 구독을 끊는 것과 실행을 멈추는 것(runtime.cancel)은 달라요.

커넥터와 결과물

ts
const { tools } = await ctx.api.connectors.listTools("search");
const result = await ctx.api.connectors.invoke("search", "find", { query: "report" });
const converted = await ctx.files.convert(file.fileId, "application/pdf");
const job = await ctx.jobs.wait(converted.jobId);
const generated = await ctx.files.artifacts({ jobId: job.jobId });

더 자세한 동작과 한계는 Mothership의 AI, 지식 검색, Runtime과 자동화, 외부 도구와 파일에 있어요.

Esc