API Reference

Agent

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

Constructor

new Agent(options: AgentOptions)

Option	Type	Default	Required
`name`	`string`	—	Yes
`instructions`	`string`	—	Yes
`model`	`ModelId \| string`	`"gpt-4o-mini"`	No
`transport`	`Transport`	—	One of `transport` or `baseUrl`
`baseUrl`	`string`	—	One of `transport` or `baseUrl`
`apiKey`	`string`	—	No
`tools`	`AgentTool[]`	`[]`	No
`rag`	`RAG`	—	No
`memory`	`MemoryConfig`	—	No
`maxSteps`	`number`	`10`	No
`toolTimeoutMs`	`number`	`30000`	No
`maxToolCalls`	`number`	`maxSteps * 5`	No
`parallelToolExecution`	`boolean`	`false`	No
`skills`	`SkillsConfig`	—	No
`extensions`	`Array<ExtensionInitFn \| string>`	—	No
`mcp`	`MCPServerConfig[]`	—	No

Methods

Method	Returns	Description
`run(input, options?)`	`Promise<AgentRunResult>`	Run the agent with a user message
`on(type, handler)`	`() => void`	Subscribe to events. Returns unsubscribe fn
`off(type, handler)`	`void`	Unsubscribe from events
`toolCount`	`number`	Number of registered tools (getter)

RAG

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

Constructor

new RAG(config: RAGConfig, transport: Transport)

Option	Type	Default
`bucket`	`string`	required
`topK`	`number`	`7`

Static Properties

Property	Type	Value
`MAX_QUERY_LENGTH`	`number`	`8000`

Methods

Method	Returns	Description
`search(query: string)`	`Promise<SearchResultItem[]>`	Semantic search over bucket
`chat(query: string)`	`Promise<ChatResult>`	Search + LLM answer
`asTool(name?: string)`	`AgentTool`	Convert to agent tool

WebSearch

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

Constructor

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

Option	Type	Default
`maxResults`	`number`	`5`
`provider`	`WebSearchProvider`	`"schift"`
`providerApiKey`	`string`	—

Methods

Method	Returns	Description
`search(query: string)`	`Promise<WebSearchResultItem[]>`	Search the web
`asTool(name?: string)`	`AgentTool`	Convert to agent tool

DeepResearch

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

Constructor

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

Option	Type	Default
`maxIterations`	`number`	`3`
`resultsPerSearch`	`number`	`5`
`queriesPerIteration`	`number`	`2`
`queryModel`	`ModelId \| string`	`"gpt-4o-mini"`
`synthesisModel`	`ModelId \| string`	`"gpt-4o-mini"`
`webSearch`	`WebSearchConfig`	—

Methods

Method	Returns	Description
`run(question: string)`	`Promise<ResearchReport>`	Run deep research
`asTool(name?: string)`	`AgentTool`	Convert to agent tool

ConversationMemory

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

Constructor

new ConversationMemory(config?: MemoryConfig)

Option	Type	Default
`maxMessages`	`number`	`50`
`transformContext`	`(messages: ChatMessage[]) => ChatMessage[]`	—

Methods

Method	Returns	Description
`add(message: ChatMessage)`	`void`	Add message to history
`getMessages()`	`ChatMessage[]`	Get all messages
`clear()`	`void`	Clear non-system messages
`length`	`number`	Message count (getter)

ToolRegistry

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

Methods

Method	Returns	Description
`register(tool: AgentTool)`	`void`	Register a tool
`get(name: string)`	`AgentTool \| undefined`	Get tool by name
`has(name: string)`	`boolean`	Check if tool exists
`list()`	`AgentTool[]`	List all tools
`execute(name, args)`	`Promise<ToolResult>`	Execute a tool by name
`filtered(allowedNames: Set<string>)`	`ToolRegistry`	New registry with only allowed tools
`without(blockedNames: Set<string>)`	`ToolRegistry`	New registry excluding blocked tools
`toOpenAI()`	`Array`	Generate OpenAI-compatible tool definitions
`toAnthropic()`	`Array`	Generate Anthropic-compatible tool definitions

AgentEventEmitter

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

Methods

Method	Returns	Description
`on(type, handler)`	`() => void`	Subscribe to event. Returns unsubscribe fn
`on("*", handler)`	`() => void`	Subscribe to all events
`off(type, handler)`	`void`	Unsubscribe from event
`emit(event)`	`void`	Emit an event
`removeAll()`	`void`	Remove all handlers

SkillLoader

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

Constructor

new SkillLoader(skillsDir: string)

Methods

Method	Returns	Description
`loadAll(options?)`	`Promise<SkillSummary[]>`	Load all skill files
`get(name: string)`	`Promise<Skill \| undefined>`	Get a skill by name
`getAll()`	`Promise<Skill[]>`	Get all loaded skills
`reload(name: string)`	`Promise<Skill \| undefined>`	Reload a specific skill

Convenience

const loader = await loadSkills("./skills");
// Equivalent to: new SkillLoader("./skills") + loadAll()

SkillResolver

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

Constructor

new SkillResolver(loader: SkillLoader)

Methods

Method	Returns	Description
`resolve(query)`	`Promise<Skill[]>`	Get all skills
`resolvePrimary(query)`	`Promise<ResolvedSkill \| undefined>`	Best-matching skill for query
`buildPromptSection(skills)`	`{ promptText, allowedTools }`	Build prompt injection section

PolicyEngine

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

Constructor

new PolicyEngine(contract: SkillContract)

Methods

Method	Returns	Description
`beforeTool(input)`	`PolicyDecision`	Check if tool call is allowed
`afterTool(input)`	`PolicyDecision`	Validate tool result

Helper

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

ExtensionHost

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

Methods

Method	Returns	Description
`load(extension)`	`Promise<void>`	Load an extension (function or module path)

Managed Agents (retired compatibility surface)

Managed Agents, Agent Hub, and APM were retired on 2026-09-25. The SDK compatibility types remain deprecated until the next major release; do not start new integrations from this section. Use bucket search, Warehouse Data, or Structify instead.

Server-side managed agents — create, configure, and run agents via the Schift Cloud API.

AgentsClient

const client = schift.agents;

Method	Returns	Description
`create(req: CreateAgentRequest)`	`Promise<AgentResponse>`	Create a managed agent
`list()`	`Promise<AgentResponse[]>`	List all agents
`get(id: string)`	`Promise<AgentResponse>`	Get agent by ID
`update(id, req)`	`Promise<AgentResponse>`	Update an agent
`delete(id: string)`	`Promise<void>`	Delete an agent
`runs(agentId: string)`	`RunsClient`	Get runs client for an agent

RunsClient

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

Method	Returns	Description
`create(req: CreateRunRequest)`	`Promise<RunResponse>`	Start a run
`list()`	`Promise<RunResponse[]>`	List all runs
`get(runId: string)`	`Promise<RunResponse>`	Get run by ID
`streamEvents(runId, afterSeq?)`	`AsyncGenerator<RunEvent>`	Stream run events

WorkspaceClient (Client)

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

Constructor

new WorkspaceClient(config: SchiftConfig)

Option	Type	Default
`apiKey`	`string`	required (must start with `sch_`)
`baseUrl`	`string`	hosted API origin
`timeout`	`number`	`60000`

Properties

Property	Type	Description
`transport`	`HttpTransport`	HTTP transport for Agent/RAG
`agents`	`AgentsClient`	Managed Agents sub-client
`models`	`ModelsClient`	Model catalog
`db`	`DBClient`	Bucket/document management
`tools`	`SchiftTools`	Tool definition helpers

Core Methods

Method	Returns	Description
`embed(request)`	`Promise<EmbedResponse>`	Generate embeddings
`embedBatch(request)`	`Promise<EmbedBatchResponse>`	Batch embeddings
`search(request)`	`Promise<SearchResult[]>`	Vector search
`chat(request)`	`Promise<ChatResponse>`	RAG chat
`chatStream(request)`	`AsyncGenerator<ChatStreamEvent>`	RAG chat with SSE streaming
`webSearch(query, maxResults?)`	`Promise<WebSearchResultItem[]>`	Web search
`aggregate(request)`	`Promise<AggregateResponse>`	Metadata aggregation
`rerank(request)`	`Promise<RerankResult>`	Rerank documents
`similarity(request)`	`Promise<{ score: number }>`	Text similarity score
`cluster(request)`	`Promise<ClusterResult>`	Text clustering
`classify(request)`	`Promise<ClassifyResult>`	Zero-shot classification

Bucket Methods

Method	Returns	Description
`listBuckets()`	`Promise<Bucket[]>`	List all buckets
`createBucket(request)`	`Promise<Bucket>`	Create a bucket
`deleteBucket(nameOrId)`	`Promise<void>`	Delete a bucket
`bucketSearch(nameOrId, request)`	`Promise<SearchResult>`	Search a bucket
`bucketGraph(nameOrId, query?, topK?)`	`Promise<GraphResult>`	Graph query on a bucket
`db.upload(bucket, options)`	`Promise<BucketUploadResult>`	Upload files to a bucket

Edge Methods

Method	Returns	Description
`addEdges(nameOrId, edges)`	`Promise<{ count: number }>`	Add graph edges
`listEdges(nameOrId, nodeId, options?)`	`Promise<EdgeListResult>`	List edges for a node
`deleteEdge(nameOrId, source, target, relation?)`	`Promise<void>`	Delete an edge

Collection Methods

Method	Returns	Description
`listCollections()`	`Promise<Collection[]>`	List collections
`getCollection(id)`	`Promise<Collection>`	Get collection by ID
`createCollection(request)`	`Promise<Collection>`	Create a collection
`deleteCollection(id)`	`Promise<void>`	Delete a collection
`collectionStats(id)`	`Promise<Stats>`	Get collection statistics
`collectionAdd(collection, request)`	`Promise<Result>`	Add documents to collection
`collectionSearch(collection, request)`	`Promise<SearchResult>`	Search a collection
`upsertVectors(collection, vectors)`	`Promise<Result>`	Upsert raw vectors
`deleteVectors(collection, ids)`	`Promise<Result>`	Delete vectors by ID
`upsertDocuments(collection, documents, model)`	`Promise<Result>`	Upsert documents with embedding

LLM Routing

Method	Returns	Description
`chatCompletion(request)`	`Promise<ChatCompletionResult>`	OpenAI-compatible chat completions
`listModels()`	`Promise<Model[]>`	List available LLM models
`getRouting()`	`Promise<RoutingConfig>`	Get current routing config
`setRouting(request)`	`Promise<RoutingConfig>`	Set routing config

Usage & Jobs

Method	Returns	Description
`usage()`	`Promise<Usage>`	Get current usage
`usageSummary()`	`Promise<UsageSummary>`	Get usage summary
`getJob(jobId)`	`Promise<Job>`	Get job status
`listJobs(options?)`	`Promise<Job[]>`	List jobs
`cancelJob(jobId)`	`Promise<Job>`	Cancel a job
`reprocessJob(jobId)`	`Promise<Job>`	Reprocess a failed job

SchiftTools

Tool calling helpers that generate provider-specific tool definitions. Automatically created on schift.tools.

// OpenAI format
const tools = schift.tools.openai();
// Anthropic format
const tools = schift.tools.anthropic();
// Vercel AI SDK format
const tools = schift.tools.vercelAI();
// Handle any tool call (auto-detects format)
const result = await schift.tools.handle(toolCall);

Method	Returns	Description
`openai()`	`object[]`	OpenAI-compatible tool definitions
`anthropic()`	`object[]`	Anthropic-compatible tool definitions
`vercelAI()`	`Record<string, object>`	Vercel AI SDK tool definitions
`handle(toolCall)`	`Promise<string>`	Execute a tool call from any provider

Types

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;    // Per-run call limit
}

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;  // Default: 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 Types

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;
}

Event Types

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

Each event includes type, runId, and timestamp. Additional fields vary by event type:

Event	Additional Fields
`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;

Model Catalogs

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"

Error Classes

import {
  SchiftError,       // Base error (status, code)
  AuthError,         // 401 - Invalid API key
  QuotaError,        // 402 - Quota exceeded
  EntitlementError,  // 403 - Upgrade required
  AgentError,        // Agent failure (stepId)
  ToolError,         // Tool execution failure (toolName)
  MaxStepsError,     // Max ReAct iterations reached
} from "@schift-io/sdk";