Built-in tools

What it is

A small library of ready-to-use tools shipped with the SDK so you don’t have to write boilerplate for common needs. There are three independent pieces:

MCP server configs — typed factories (FilesystemToolServer, CodeRunnerToolServer) that produce the spawn config for a well-known MCP server. You register them with agent.register_mcp().
Built-in capability library — BuiltinToolLoader loads pre-written capabilities for third-party APIs (GitHub, Jira, Slack, …) that you wire into your agent with agent.define_capability().
HTTP helper — HttpHelper is a tiny fetch wrapper with bearer-token auth, used by the built-in library and exported for your own tools.

When to use them

FilesystemToolServer — your agent needs to read or write files under a specific directory.
CodeRunnerToolServer — your agent needs to execute scripts or shell commands in a sandbox.
BuiltinToolLoader — you want working GitHub / Jira / Slack / etc. capabilities without writing them by hand.
HttpHelper — you’re writing your own third-party integration and want consistent auth and error handling.

If none of these fit your use case, write a capability directly with agent.define_capability().

Functional usage — combined example

import {
  Agent,
  FilesystemToolServer,
  CodeRunnerToolServer,
  BuiltinToolLoader,
} from '@svantic/sdk';

const agent = new Agent({ name: 'ops-agent', description: 'Ops helper' });

// 1. MCP-backed tools — spawned as child processes, surfaced as capabilities.
const fs_tool = new FilesystemToolServer({ root: '/data' });
await agent.register_mcp('filesystem', fs_tool.config());

const runner = new CodeRunnerToolServer({
  root: '/sandbox',
  allowed_commands: ['python', 'node'],
  timeout_ms: 10_000,
});
await agent.register_mcp('code-runner', runner.config());

// 2. Built-in capabilities — hand-written tools, loaded by domain.
const loader = new BuiltinToolLoader();
const { tools, errors } = await loader.load_domains(['github', 'slack']);
if (errors.length) console.warn('could not load:', errors);
for (const tool of tools) agent.define_capability(tool);

await agent.start();

MCP server configs

`FilesystemToolServer`

import { FilesystemToolServer } from '@svantic/sdk';

const fs_tool = new FilesystemToolServer({ root: '/data' });
await agent.register_mcp('filesystem', fs_tool.config());

Scoped filesystem access via @modelcontextprotocol/server-filesystem. The server process runs locally with the given root as its sandbox.

`FilesystemToolServerOptions`

Field	Type	Default	Purpose
`root`	`string`	—	Required. Directory the MCP server is allowed to read/write.
`package_name?`	`string`	`@modelcontextprotocol/server-filesystem`	Override to pin a version or fork.
`name?`	`string`	`filesystem`	Registration label.

Methods

config(): McpServerConfig — spawn config to pass to agent.register_mcp().
as_registration(): Record<string, McpServerConfig> — { [name]: config } for bulk registration.

`CodeRunnerToolServer`

import { CodeRunnerToolServer } from '@svantic/sdk';

const runner = new CodeRunnerToolServer({
  root: '/sandbox',
  allowed_commands: ['python', 'node'],
  timeout_ms: 10_000,
});
await agent.register_mcp('code-runner', runner.config());

Sandboxed shell/code execution. Tighten the blast radius with allowed_commands and timeout_ms.

`CodeRunnerToolServerOptions`

Field	Type	Default	Purpose
`root`	`string`	—	Required. Working directory for executed commands.
`allowed_commands?`	`string[]`	unrestricted	Allowlist of command names.
`timeout_ms?`	`number`	unrestricted	Per-command wallclock timeout.
`package_name?`	`string`	(ships default)	Override package.
`name?`	`string`	`code_runner`	Registration label.

Built-in capability library

`BuiltinToolLoader` / `BUILTIN_DOMAINS`

import { BuiltinToolLoader, BUILTIN_DOMAINS } from '@svantic/sdk';

const loader = new BuiltinToolLoader();
const { tools, loaded, errors } = await loader.load_domain('github');

Each domain groups a set of pre-built capabilities for a third-party API. Credentials are read from environment variables at call time (documented on each tool).

Domain	Provides
`github`	List / get / create PRs, diffs, reviews, merges.
`bitbucket`	List / get / create PRs, diffs, comments, merges.
`jira`	Get / create issues, add comments, transition status.
`zendesk`	List / get / create / update tickets, add comments.
`slack`	Send messages (text or threaded replies).
`shell`	General-purpose command execution.
`datadog`	Query metrics, list alerts.
`hubspot`	Contacts and deals — list, get, create, update.

BUILTIN_DOMAINS is the exhaustive list as a runtime constant.

Methods

load_domain(domain) — load every tool in one domain.
load_domains(domains) — load multiple domains, aggregating tools / loaded / errors.
load_all() — load every domain.
list_domain(domain) — return the list of tool names available in a domain without loading.
domains — getter returning BUILTIN_DOMAINS.

`BuiltinLoadResult`

Field	Type	Description
`tools`	`LocalToolDefinition[]`	Loaded tool objects. Each has `name`, `description`, `parameters`, `handler`.
`loaded`	`string[]`	Names that loaded successfully.
`errors`	`string[]`	Per-tool error strings for anything that failed.

Each LocalToolDefinition can be registered with agent.define_capability():

for (const tool of tools) {
  agent.define_capability(tool);
}

HTTP helper

`HttpHelper`

Small fetch wrapper used by the built-in tools for bearer-token-authenticated REST calls. Exported for custom tools that follow the same pattern.

import { HttpHelper } from '@svantic/sdk';

const client = new HttpHelper({
  base_url: 'https://api.example.com',
  token_env_var: 'EXAMPLE_API_TOKEN',
});

const res = await client.get<{ items: unknown[] }>('/v1/items');
if (res.ok) console.log(res.data.items);

Methods: get, post, put, patch, request. Plus check_auth() — returns { configured: true | false, env_var? } so tools can bail early with a helpful message when the env var isn’t set.

Overview

Guides

Reference

Builtin tools

Built-in tools

What it is

When to use them

Functional usage — combined example

MCP server configs

`FilesystemToolServer`

`FilesystemToolServerOptions`

Methods

`CodeRunnerToolServer`

`CodeRunnerToolServerOptions`

Built-in capability library

`BuiltinToolLoader` / `BUILTIN_DOMAINS`

Methods

`BuiltinLoadResult`

HTTP helper

`HttpHelper`

See also

​Built-in tools

​What it is

​When to use them

​Functional usage — combined example

​MCP server configs

​FilesystemToolServer

​FilesystemToolServerOptions

​Methods

​CodeRunnerToolServer

​CodeRunnerToolServerOptions

​Built-in capability library

​BuiltinToolLoader / BUILTIN_DOMAINS

​Methods

​BuiltinLoadResult

​HTTP helper

​HttpHelper

​See also

Built-in tools

What it is

When to use them

Functional usage — combined example

MCP server configs

`FilesystemToolServer`

`FilesystemToolServerOptions`

Methods

`CodeRunnerToolServer`

`CodeRunnerToolServerOptions`

Built-in capability library

`BuiltinToolLoader` / `BUILTIN_DOMAINS`

Methods

`BuiltinLoadResult`

HTTP helper

`HttpHelper`

See also