API 레퍼런스

Agent

import { Agent } from "@schift-io/sdk";

생성자

new Agent(options: AgentOptions)

옵션	타입	기본값	필수 여부
`name`	`string`	—	필수
`instructions`	`string`	—	필수
`model`	`ModelId \| string`	`"gpt-4o-mini"`	선택
`transport`	`Transport`	—	`transport` 또는 `baseUrl` 중 하나
`baseUrl`	`string`	—	`transport` 또는 `baseUrl` 중 하나
`apiKey`	`string`	—	선택
`tools`	`AgentTool[]`	`[]`	선택
`rag`	`RAG`	—	선택
`memory`	`MemoryConfig`	—	선택
`maxSteps`	`number`	`10`	선택
`toolTimeoutMs`	`number`	`30000`	선택
`maxToolCalls`	`number`	`maxSteps * 5`	선택
`parallelToolExecution`	`boolean`	`false`	선택
`skills`	`SkillsConfig`	—	선택
`extensions`	`Array<ExtensionInitFn \| string>`	—	선택
`mcp`	`MCPServerConfig[]`	—	선택

메서드

메서드	반환값	설명
`run(input, options?)`	`Promise<AgentRunResult>`	사용자 메시지로 에이전트를 실행
`on(type, handler)`	`() => void`	이벤트 구독. 구독 해제 함수 반환
`off(type, handler)`	`void`	이벤트 구독 해제
`toolCount`	`number`	등록된 도구 수 (getter)

RAG

import { RAG } from "@schift-io/sdk";

생성자

new RAG(config: RAGConfig, transport: Transport)

옵션	타입	기본값
`bucket`	`string`	필수
`topK`	`number`	`7`

정적 속성

속성	타입	값
`MAX_QUERY_LENGTH`	`number`	`8000`

메서드

메서드	반환값	설명
`search(query: string)`	`Promise<SearchResultItem[]>`	버킷에서 시맨틱 검색
`chat(query: string)`	`Promise<ChatResult>`	검색 + LLM 답변
`asTool(name?: string)`	`AgentTool`	에이전트 도구로 변환

WebSearch

import { WebSearch } from "@schift-io/sdk";

생성자

new WebSearch(config?: WebSearchConfig, transport?: Transport)

옵션	타입	기본값
`maxResults`	`number`	`5`
`provider`	`WebSearchProvider`	`"schift"`
`providerApiKey`	`string`	—

메서드

메서드	반환값	설명
`search(query: string)`	`Promise<WebSearchResultItem[]>`	웹 검색
`asTool(name?: string)`	`AgentTool`	에이전트 도구로 변환

DeepResearch

import { DeepResearch } from "@schift-io/sdk";

생성자

new DeepResearch(config?: DeepResearchConfig, llm: LLMFn, transport?: Transport)

옵션	타입	기본값
`maxIterations`	`number`	`3`
`resultsPerSearch`	`number`	`5`
`queriesPerIteration`	`number`	`2`
`queryModel`	`ModelId \| string`	`"gpt-4o-mini"`
`synthesisModel`	`ModelId \| string`	`"gpt-4o-mini"`
`webSearch`	`WebSearchConfig`	—

메서드

메서드	반환값	설명
`run(question: string)`	`Promise<ResearchReport>`	심층 리서치 실행
`asTool(name?: string)`	`AgentTool`	에이전트 도구로 변환

ConversationMemory

import { ConversationMemory } from "@schift-io/sdk";

생성자

new ConversationMemory(config?: MemoryConfig)

옵션	타입	기본값
`maxMessages`	`number`	`50`
`transformContext`	`(messages: ChatMessage[]) => ChatMessage[]`	—

메서드

메서드	반환값	설명
`add(message: ChatMessage)`	`void`	메시지를 히스토리에 추가
`getMessages()`	`ChatMessage[]`	전체 메시지 목록 반환
`clear()`	`void`	시스템 메시지 제외 초기화
`length`	`number`	메시지 수 (getter)

ToolRegistry

import { ToolRegistry } from "@schift-io/sdk";

메서드

메서드	반환값	설명
`register(tool: AgentTool)`	`void`	도구 등록
`get(name: string)`	`AgentTool \| undefined`	이름으로 도구 조회
`has(name: string)`	`boolean`	도구 존재 확인
`list()`	`AgentTool[]`	전체 도구 목록
`execute(name, args)`	`Promise<ToolResult>`	이름으로 도구 실행
`filtered(allowedNames: Set<string>)`	`ToolRegistry`	허용 도구만 포함한 새 레지스트리
`without(blockedNames: Set<string>)`	`ToolRegistry`	차단 도구 제외한 새 레지스트리
`toOpenAI()`	`Array`	OpenAI 호환 도구 정의 생성
`toAnthropic()`	`Array`	Anthropic 호환 도구 정의 생성

AgentEventEmitter

import { AgentEventEmitter } from "@schift-io/sdk";

메서드

메서드	반환값	설명
`on(type, handler)`	`() => void`	이벤트 구독. 구독 해제 함수 반환
`on("*", handler)`	`() => void`	전체 이벤트 구독
`off(type, handler)`	`void`	이벤트 구독 해제
`emit(event)`	`void`	이벤트 발행
`removeAll()`	`void`	전체 핸들러 제거

SkillLoader

import { SkillLoader, loadSkills } from "@schift-io/sdk";

생성자

new SkillLoader(skillsDir: string)

메서드

메서드	반환값	설명
`loadAll(options?)`	`Promise<SkillSummary[]>`	전체 스킬 파일 로드
`get(name: string)`	`Promise<Skill \| undefined>`	이름으로 스킬 조회
`getAll()`	`Promise<Skill[]>`	로드된 전체 스킬 조회
`reload(name: string)`	`Promise<Skill \| undefined>`	특정 스킬 리로드

편의 함수

const loader = await loadSkills("./skills");
// new SkillLoader("./skills") + loadAll() 과 동일

SkillResolver

import { SkillResolver } from "@schift-io/sdk";

생성자

new SkillResolver(loader: SkillLoader)

메서드

메서드	반환값	설명
`resolve(query)`	`Promise<Skill[]>`	전체 스킬 조회
`resolvePrimary(query)`	`Promise<ResolvedSkill \| undefined>`	쿼리에 가장 적합한 스킬
`buildPromptSection(skills)`	`{ promptText, allowedTools }`	프롬프트 주입 섹션 생성

PolicyEngine

import { PolicyEngine, policyViolation } from "@schift-io/sdk";

생성자

new PolicyEngine(contract: SkillContract)

메서드

메서드	반환값	설명
`beforeTool(input)`	`PolicyDecision`	도구 호출 허용 여부 확인
`afterTool(input)`	`PolicyDecision`	도구 결과 검증

헬퍼

policyViolation(reason: string): ToolResult
// { success: false, data: null, error: "POLICY_VIOLATION:reason" } 반환

ExtensionHost

import { ExtensionHost } from "@schift-io/sdk";

메서드

메서드	반환값	설명
`load(extension)`	`Promise<void>`	Extension 로드 (함수 또는 모듈 경로)

Managed Agents

서버 측 매니지드 에이전트 — Schift Cloud API를 통한 CRUD 및 실행.

AgentsClient

const client = schift.agents;

메서드	반환값	설명
`create(req: CreateAgentRequest)`	`Promise<AgentResponse>`	매니지드 에이전트 생성
`list()`	`Promise<AgentResponse[]>`	전체 에이전트 목록
`get(id: string)`	`Promise<AgentResponse>`	ID로 에이전트 조회
`update(id, req)`	`Promise<AgentResponse>`	에이전트 업데이트
`delete(id: string)`	`Promise<void>`	에이전트 삭제
`runs(agentId: string)`	`RunsClient`	에이전트의 RunsClient 조회

RunsClient

const runs = schift.agents.runs("agt_abc123");

메서드	반환값	설명
`create(req: CreateRunRequest)`	`Promise<RunResponse>`	실행 시작
`list()`	`Promise<RunResponse[]>`	전체 실행 목록
`get(runId: string)`	`Promise<RunResponse>`	ID로 실행 조회
`streamEvents(runId, afterSeq?)`	`AsyncGenerator<RunEvent>`	실행 이벤트 스트리밍

WorkspaceClient (클라이언트)

import { WorkspaceClient } from "@schift-io/sdk";

생성자

new WorkspaceClient(config: SchiftConfig)

옵션	타입	기본값
`apiKey`	`string`	필수 (`sch_`로 시작)
`baseUrl`	`string`	hosted API origin
`timeout`	`number`	`60000`

속성

속성	타입	설명
`transport`	`HttpTransport`	Agent/RAG용 HTTP 트랜스포트
`workflows`	`WorkflowClient`	워크플로우 서브 클라이언트
`agents`	`AgentsClient`	Managed Agents 서브 클라이언트
`models`	`ModelsClient`	모델 카탈로그
`db`	`DBClient`	버킷/문서 관리
`tools`	`SchiftTools`	도구 정의 헬퍼

핵심 메서드

메서드	반환값	설명
`embed(request)`	`Promise<EmbedResponse>`	임베딩 생성
`embedBatch(request)`	`Promise<EmbedBatchResponse>`	배치 임베딩
`search(request)`	`Promise<SearchResult[]>`	벡터 검색
`chat(request)`	`Promise<ChatResponse>`	RAG 채팅
`chatStream(request)`	`AsyncGenerator<ChatStreamEvent>`	SSE 스트리밍 RAG 채팅
`webSearch(query, maxResults?)`	`Promise<WebSearchResultItem[]>`	웹 검색
`aggregate(request)`	`Promise<AggregateResponse>`	메타데이터 집계
`rerank(request)`	`Promise<RerankResult>`	문서 리랭킹
`similarity(request)`	`Promise<{ score: number }>`	텍스트 유사도
`cluster(request)`	`Promise<ClusterResult>`	텍스트 클러스터링
`classify(request)`	`Promise<ClassifyResult>`	제로샷 분류

버킷 메서드

메서드	반환값	설명
`listBuckets()`	`Promise<Bucket[]>`	전체 버킷 목록
`createBucket(request)`	`Promise<Bucket>`	버킷 생성
`deleteBucket(nameOrId)`	`Promise<void>`	버킷 삭제
`bucketSearch(nameOrId, request)`	`Promise<SearchResult>`	버킷 검색
`bucketGraph(nameOrId, query?, topK?)`	`Promise<GraphResult>`	버킷 그래프 쿼리
`db.upload(bucket, options)`	`Promise<BucketUploadResult>`	버킷에 파일 업로드

엣지 메서드

메서드	반환값	설명
`addEdges(nameOrId, edges)`	`Promise<{ count: number }>`	그래프 엣지 추가
`listEdges(nameOrId, nodeId, options?)`	`Promise<EdgeListResult>`	노드의 엣지 목록
`deleteEdge(nameOrId, source, target, relation?)`	`Promise<void>`	엣지 삭제

컬렉션 메서드

메서드	반환값	설명
`listCollections()`	`Promise<Collection[]>`	컬렉션 목록
`getCollection(id)`	`Promise<Collection>`	ID로 컬렉션 조회
`createCollection(request)`	`Promise<Collection>`	컬렉션 생성
`deleteCollection(id)`	`Promise<void>`	컬렉션 삭제
`collectionStats(id)`	`Promise<Stats>`	컬렉션 통계
`collectionAdd(collection, request)`	`Promise<Result>`	컬렉션에 문서 추가
`collectionSearch(collection, request)`	`Promise<SearchResult>`	컬렉션 검색
`upsertVectors(collection, vectors)`	`Promise<Result>`	벡터 upsert
`deleteVectors(collection, ids)`	`Promise<Result>`	ID로 벡터 삭제
`upsertDocuments(collection, documents, model)`	`Promise<Result>`	임베딩 포함 문서 upsert

LLM 라우팅

메서드	반환값	설명
`chatCompletion(request)`	`Promise<ChatCompletionResult>`	OpenAI 호환 chat completions
`listModels()`	`Promise<Model[]>`	사용 가능한 LLM 모델 목록
`getRouting()`	`Promise<RoutingConfig>`	현재 라우팅 설정 조회
`setRouting(request)`	`Promise<RoutingConfig>`	라우팅 설정 변경

사용량 및 작업

메서드	반환값	설명
`usage()`	`Promise<Usage>`	현재 사용량 조회
`usageSummary()`	`Promise<UsageSummary>`	사용량 요약
`getJob(jobId)`	`Promise<Job>`	작업 상태 조회
`listJobs(options?)`	`Promise<Job[]>`	작업 목록
`cancelJob(jobId)`	`Promise<Job>`	작업 취소
`reprocessJob(jobId)`	`Promise<Job>`	실패 작업 재처리

SchiftTools

프로바이더별 도구 정의를 생성하는 헬퍼. schift.tools에 자동 생성됩니다.

// OpenAI 형식
const tools = schift.tools.openai();
// Anthropic 형식
const tools = schift.tools.anthropic();
// Vercel AI SDK 형식
const tools = schift.tools.vercelAI();
// 도구 호출 처리 (형식 자동 감지)
const result = await schift.tools.handle(toolCall);

메서드	반환값	설명
`openai()`	`object[]`	OpenAI 호환 도구 정의
`anthropic()`	`object[]`	Anthropic 호환 도구 정의
`vercelAI()`	`Record<string, object>`	Vercel AI SDK 도구 정의
`handle(toolCall)`	`Promise<string>`	프로바이더 형식 자동 감지 후 도구 호출 실행

타입

AgentTool

interface AgentTool {
  name: string;                // Must match /^[a-zA-Z_][a-zA-Z0-9_]*$/
  description: string;
  parameters?: JSONSchema;
  handler: (args: Record<string, unknown>) => Promise<ToolResult>;
  maxCallsPerRun?: number;    // 실행당 호출 제한
}

ToolResult

interface ToolResult {
  success: boolean;
  data: unknown;
  error?: string;
}

AgentRunResult

interface AgentRunResult {
  steps: AgentStep[];
  output: string;
  totalDurationMs: number;
}

AgentStep

interface AgentStep {
  id: string;
  type: "think" | "tool_call" | "tool_result" | "final_answer" | "error";
  content?: string;
  toolName?: string;
  toolArgs?: Record<string, unknown>;
  toolResult?: ToolResult;
  durationMs: number;
}

RunOptions

interface RunOptions {
  requestId?: string;
  signal?: AbortSignal;
}

ChatMessage

interface ChatMessage {
  role: "system" | "user" | "assistant" | "tool";
  content: string;
  toolCallId?: string;
  toolName?: string;
}

SkillsConfig

interface SkillsConfig {
  loader: SkillLoader;
  autoResolve?: boolean;  // 기본값: true
}

SkillContract

interface SkillContract {
  skillName: string;
  model?: string;
  allowedTools?: string[];
  blockedTools?: string[];
  procedures?: string[];
  constraints?: string[];
}

SkillFrontmatter

interface SkillFrontmatter {
  name: string;
  description: string;
  model?: string;
  "allowed-tools"?: string[];
  "blocked-tools"?: string[];
  procedures?: string[];
  constraints?: string[];
  rag?: string;
}

PolicyDecision

interface PolicyDecision {
  allowed: boolean;
  stage: "before_tool" | "after_tool" | "procedure" | "constraint";
  reason?: string;
}

ExtensionAPI

interface ExtensionAPI {
  registerTool(tool: AgentTool): void;
  on<K extends AgentEventType>(type: K, handler: (event: AgentEventMap[K]) => void): () => void;
  off<K extends AgentEventType>(type: K, handler: (event: AgentEventMap[K]) => void): void;
  readonly agentName: string;
}

MCPServerConfig

interface MCPServerConfig {
  transport: "stdio" | "sse";
  command?: string;
  args?: string[];
  url?: string;
  toolPrefix?: string;
}

Managed Agent 타입

interface CreateAgentRequest {
  name: string;
  model?: string;
  instructions?: string;
  tools?: AgentToolDef[];
  ragConfig?: RagConfig;
  metadata?: Record<string, unknown>;
}

interface AgentResponse {
  id: string;
  orgId: string;
  name: string;
  model: string;
  instructions: string;
  tools: AgentToolDef[];
  ragConfig: RagConfig;
  metadata: Record<string, unknown>;
  createdAt: string;
  updatedAt: string;
}

interface RunResponse {
  id: string;
  agentId: string;
  orgId: string;
  status: "pending" | "running" | "success" | "error" | "timeout";
  inputText: string;
  outputText?: string;
  error?: string;
  tokensUsed: number;
  durationMs?: number;
  createdAt: string;
  finishedAt?: string;
}

interface RunEvent {
  seq: number;
  eventType: string;
  [key: string]: unknown;
}

이벤트 타입

type AgentEventType =
  | "agent_start"
  | "turn_start"
  | "tool_call"
  | "tool_result"
  | "message_delta"
  | "agent_end"
  | "error"
  | "policy_violation";

각 이벤트에는 type, runId, timestamp가 포함됩니다. 이벤트별 추가 필드:

이벤트	추가 필드
`agent_start`	`input`
`turn_start`	`turnIndex`
`tool_call`	`toolName`, `toolArgs`, `callId`
`tool_result`	`toolName`, `callId`, `result`, `durationMs`
`message_delta`	`content`
`agent_end`	`output`, `totalDurationMs`
`error`	`error`
`policy_violation`	`skillName`, `stage`, `reason`, `toolName?`

WebSearchProvider

const WebSearchProvider = {
  SCHIFT: "schift",
  TAVILY: "tavily",
  SERPER: "serper",
  BRAVE: "brave",
} as const;

모델 카탈로그

import { OpenAIModel, GeminiModel, ClaudeModel } from "@schift-io/sdk";

// OpenAI
OpenAIModel.GPT_5_5_PRO      // "gpt-5.5-pro"
OpenAIModel.GPT_5_5          // "gpt-5.5"
OpenAIModel.GPT_5_4          // "gpt-5.4"
OpenAIModel.GPT_5_4_MINI     // "gpt-5.4-mini"
OpenAIModel.GPT_5_4_NANO     // "gpt-5.4-nano"
OpenAIModel.GPT_4_1          // "gpt-4.1"
OpenAIModel.GPT_4_1_MINI     // "gpt-4.1-mini"
OpenAIModel.GPT_4_1_NANO     // "gpt-4.1-nano"
OpenAIModel.GPT_4O           // "gpt-4o"
OpenAIModel.GPT_4O_MINI      // "gpt-4o-mini"
OpenAIModel.O3               // "o3"
OpenAIModel.O3_MINI          // "o3-mini"
OpenAIModel.O3_PRO           // "o3-pro"
OpenAIModel.O4_MINI          // "o4-mini"

// Google
GeminiModel.GEMINI_3_1_PRO       // "gemini-3.1-pro"
GeminiModel.GEMINI_3_1_FLASH     // "gemini-3.1-flash"
GeminiModel.GEMINI_3_1_FLASH_LITE // "gemini-3.1-flash-lite"
GeminiModel.GEMINI_2_5_PRO       // "gemini-2.5-pro"
GeminiModel.GEMINI_2_5_FLASH     // "gemini-2.5-flash"
GeminiModel.GEMINI_2_5_FLASH_LITE // "gemini-2.5-flash-lite"

// Anthropic
ClaudeModel.OPUS_4_8         // "claude-opus-4-8"
ClaudeModel.OPUS_4_6         // "claude-opus-4-6"
ClaudeModel.SONNET_4_6       // "claude-sonnet-4-6"
ClaudeModel.HAIKU_4_5        // "claude-haiku-4-5-20251001"

에러 클래스

import {
  SchiftError,       // 기본 에러 (status, code)
  AuthError,         // 401 - 잘못된 API 키
  QuotaError,        // 402 - 할당량 초과
  EntitlementError,  // 403 - 플랜 업그레이드 필요
  AgentError,        // 에이전트 실패 (stepId)
  ToolError,         // 도구 실행 실패 (toolName)
  MaxStepsError,     // 최대 ReAct 반복 횟수 초과
} from "@schift-io/sdk";