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과 자동화, 외부 도구와 파일에 있어요.