Built-in Tools

The SDK includes several tools you can add alongside Supyagent Cloud tools. All tools are Vercel AI SDK Tool objects returned by factory functions.

`createBashTool(options?)`

A shell execution tool that lets the agent run bash commands on the server. Includes safety features: command classification, environment sanitization, and configurable approval policies.

import { createBashTool } from '@supyagent/sdk';

const bash = createBashTool({
  cwd: '/path/to/project',
  timeout: 60_000,
  approval: 'auto',
});

Options

Option	Type	Default	Description
`cwd`	`string`	`process.cwd()`	Working directory for commands
`timeout`	`number`	`30000`	Timeout in ms (max 600000)
`maxOutput`	`number`	`30000`	Max output characters
`approval`	`"auto" \| "always" \| "never" \| function`	`"auto"`	Command approval policy
`env`	`"safe" \| "inherit" \| "none" \| Record<string,string>`	`"safe"`	Environment variable policy
`envInclude`	`string[]`	—	Extra env vars to include (with `env: "safe"`)
`envExclude`	`string[]`	—	Extra env vars to exclude (with `env: "safe"`)
`allowCommands`	`string[]`	—	Additional commands to auto-approve
`denyPatterns`	`RegExp[]`	—	Additional patterns to block

Approval Policies

Policy	Behavior
`"auto"`	Read-only commands (ls, cat, grep, git status, etc.) auto-execute; others require user approval
`"always"`	Every command requires user approval
`"never"`	No approval required (use only in trusted/sandboxed environments)
`function`	Custom function — return `true` to require approval

Environment Policies

Policy	Behavior
`"safe"`	Strips env vars matching secret patterns (KEY, TOKEN, SECRET, PASSWORD, etc.)
`"inherit"`	Passes full `process.env` (not recommended for production)
`"none"`	Minimal env: PATH, HOME, TERM only
`Record<string,string>`	Explicit env vars to use

Result Shape

interface BashToolResult {
  stdout: string;
  stderr: string;
  exitCode: number;
  durationMs: number;
  timedOut?: boolean;
}

`createViewImageTool(options?)`

Lets the agent display images in the chat by providing a URL. On the client side, pair with a prepareStep callback to inject the image into the conversation for the model to see.

import { createViewImageTool } from '@supyagent/sdk';

const viewImage = createViewImageTool();

Options

Option	Type	Default	Description
`description`	`string`	`"Display an image in the chat..."`	Custom tool description

Server + Client Integration

On the server, the tool returns { url, displayed: true }. To make the image visible to the model in subsequent steps, use prepareStep:

app/api/chat/route.ts

const result = streamText({
  model: yourModel,
  messages,
  tools: { viewImage: createViewImageTool() },
  prepareStep: async ({ steps }) => {
    const imageUrls: string[] = [];
    for (const step of steps) {
      for (const call of step.toolCalls) {
        if (call.toolName === 'viewImage' && call.input?.url) {
          imageUrls.push(call.input.url as string);
        }
      }
    }
    if (imageUrls.length === 0) return undefined;
    return {
      messages: [
        ...messages,
        {
          role: 'user' as const,
          content: imageUrls.map(url => ({
            type: 'file' as const,
            data: new URL(url),
            mediaType: 'image/jpeg',
          })),
        },
      ],
    };
  },
});

Skill Tools

These are typically created automatically via client.skills(), but you can also create them manually if needed.

`createLoadSkillTool(skills)`

Creates a tool that returns detailed API documentation for a named skill.

import { createLoadSkillTool, parseSkillsMarkdown } from '@supyagent/sdk';

const doc = parseSkillsMarkdown(markdownString);
const loadSkill = createLoadSkillTool(doc.skills);

`createApiCallTool(baseUrl, apiKey)`

Creates a tool that makes authenticated HTTP requests to the Supyagent API.

import { createApiCallTool } from '@supyagent/sdk';

const apiCall = createApiCallTool('https://app.supyagent.com', apiKey);

The tool accepts method, path, body, and params. The authorization header is added automatically.

Skill Parsing Utilities

Function	Description
`parseSkillsMarkdown(md)`	Parse a YAML-frontmatter skills document into structured sections
`buildSkillsSystemPrompt(doc)`	Build a concise system prompt listing available skills
`findSkill(skills, name)`	Find a skill by name (case-insensitive, partial matching)

Combining Tools

A typical setup combines Supyagent Cloud tools with built-in tools:

const { systemPrompt, tools: skillTools } = await client.skills({ cache: 300 });

const tools = {
  ...skillTools,
  bash: createBashTool({ approval: 'auto' }),
  viewImage: createViewImageTool(),
};

What's Next

Client — The supyagent() client that provides cloud tools
Full API Route Example — See all tools used together in a real endpoint

Built-in Tools

On this page