@skalerlabs/agent-sdk

TypeScript SDK for building AI agents. Sandboxed filesystem, discoverable tool registry, multi-provider model routing, sub-agents, skills, and MCP support.

Install

npm install @skalerlabs/agent-sdk

Requires Node 20+.

Quick start

import { createAgent } from '@skalerlabs/agent-sdk'

const agent = await createAgent({
  agentId: 'my-agent',
  modelId: 'anthropic/claude-sonnet-4-5',
  agentDir: './agent',     // brain dir — AGENTS.md, sub-agents, skills
  sessionDir: './work',    // workspace dir — files the agent reads/writes
})

const result = await agent.generateText({
  prompt: 'Summarize what is in /session.',
})

console.log(result.text)
console.log(result.usage)

For streaming:

const { stream, text, usage } = await agent.streamText({
  prompt: 'Summarize what is in /session.',
})

const reader = stream.getReader()
while (true) {
  const { value, done } = await reader.read()
  if (done) break
  // value is a UIMessageChunk — assistant text deltas, tool calls, etc.
}

console.log(await text)
console.log(await usage)

Provider keys

The SDK does not load .env files for you. Set whichever provider keys you need in your process environment:

• ANTHROPIC_API_KEY
• OPENAI_API_KEY
• GOOGLE_GENERATIVE_AI_API_KEY
• XAI_API_KEY
• AWS credentials for Bedrock
• OLLAMA_BASE_URL (optional — defaults to http://localhost:11434/v1 for local Ollama; no API key required)

If no matching provider key is set, the SDK falls back to the Vercel AI Gateway.

What you get

• Sandboxed FS. File tools (Read, Write, Glob, Grep) are scoped to two mounted dirs: /agent (your agent's brain) and /session (the per-run workspace). Absolute host paths are rejected.
• Tool registry + discovery. Every built-in tool (Bash, file tools, web tools, task tools, sub-agents, skills, MCP bridges) is registered but inactive by default. The model activates tools on demand via ToolSearch. Keeps the prompt clean.
• Sub-agents. Explore, Plan, and General are built in. Drop a frontmatter file at <agentDir>/agents/<Name>.md to add or override one.
• Skills. Markdown skills at <agentDir>/skills/<name>/SKILL.md are listed in the system prompt and runnable via the Skill tool.
• MCP. Pass mcpServers to createAgent to bridge MCP tools into the registry. Stdio + Streamable HTTP transports.
• Plan mode. EnterPlanMode flips the session to read-only-tools-plus-ExitPlanMode. ExitPlanMode is a stop condition — the run pauses for user approval.
• Tasks. TaskCreate / TaskUpdate / TaskList mutate session task state with status icons consumers can render.
• Multi-provider model routing. Anthropic, OpenAI, Google, xAI, Bedrock, local Ollama (via ollama/<name> pass-through), with Gateway fallback.
• Token + cost accounting. Usage summaries roll up across the whole run.

Source & docs

Full docs and source: https://github.com/skalerlabs/agent-sdk

The CLI (@skalerlabs/agent-cli) is a separate package built on top of this SDK — it's the reference consumer.

License

MIT © Skaler Labs