Tools

@agentskit/tools provides ready-made ToolDefinition values for web search, filesystem access, and shell execution. Pass them to createRuntime or useChat.

When to use

• You want batteries-included tools with JSON Schema already tuned for models.
• You build a registry UI via listTools().

For custom tools in your own npm package, see @agentskit/templates.

Install

npm install @agentskit/tools

Depends on @agentskit/core types (via your runtime or useChat setup).

Public exports

Export	Returns	Notes
webSearch(config?)	ToolDefinition	Search providers: default DuckDuckGo, optional Serper, or custom search
filesystem(config)	ToolDefinition[]	read_file, write_file, list_directory scoped to basePath
shell(config)	ToolDefinition	Whitelist via allowed; timeout and output caps
listTools()	ToolMetadata[]	Discovery for dashboards and docs

webSearch

Search the web and return titles, URLs, and snippets.

Default provider: DuckDuckGo (no API key required).

import { createRuntime } from '@agentskit/runtime'
import { webSearch } from '@agentskit/tools'
import { anthropic } from '@agentskit/adapters'

const runtime = createRuntime({
  adapter: anthropic({ apiKey: process.env.ANTHROPIC_API_KEY!, model: 'claude-sonnet-4-6' }),
  tools: [webSearch()],
})

const result = await runtime.run('Who won the 2024 Nobel Prize in Physics?')

Serper (Google results)

webSearch({ provider: 'serper', apiKey: process.env.SERPER_API_KEY, maxResults: 8 })

Bring your own search (BYOS)

Provide a custom search function to use any backend:

webSearch({
  search: async (query) => {
    const hits = await mySearchClient.query(query)
    return hits.map(h => ({ title: h.title, url: h.href, snippet: h.body }))
  },
})

Schema

{
  "name": "web_search",
  "description": "Search the web for information. Returns titles, URLs, and snippets.",
  "schema": {
    "type": "object",
    "properties": {
      "query": { "type": "string", "description": "The search query" }
    },
    "required": ["query"]
  }
}

filesystem

Read, write, and list files within a sandboxed basePath. All paths passed by the model are resolved relative to basePath; any attempt to escape it throws an access-denied error.

import { filesystem } from '@agentskit/tools'

const fsTools = filesystem({ basePath: '/tmp/workspace' })
// Returns: [read_file, write_file, list_directory]

Pass the array directly to the runtime:

const runtime = createRuntime({
  adapter: anthropic({ apiKey: process.env.ANTHROPIC_API_KEY!, model: 'claude-sonnet-4-6' }),
  tools: fsTools,
})

read_file

{
  "name": "read_file",
  "description": "Read the contents of a file. Path is relative to the workspace.",
  "schema": {
    "type": "object",
    "properties": {
      "path": { "type": "string", "description": "File path relative to workspace" }
    },
    "required": ["path"]
  }
}

write_file

{
  "name": "write_file",
  "description": "Write content to a file. Creates the file if it does not exist.",
  "schema": {
    "type": "object",
    "properties": {
      "path":    { "type": "string", "description": "File path relative to workspace" },
      "content": { "type": "string", "description": "Content to write" }
    },
    "required": ["path", "content"]
  }
}

list_directory

{
  "name": "list_directory",
  "description": "List files and directories at a path.",
  "schema": {
    "type": "object",
    "properties": {
      "path": { "type": "string", "description": "Directory path relative to workspace (default: root)" }
    }
  }
}

shell

Execute shell commands from inside the agent. Use the allowed list to restrict which commands the model may run.

import { shell } from '@agentskit/tools'

// Allow only git and npm
const shellTool = shell({
  allowed: ['git', 'npm'],
  timeout: 15_000,
})

Config

Option	Type	Default	Description
timeout	number	30_000 ms	Kill the process after this many milliseconds
allowed	string[]	(any)	Whitelist of command names (first word of the input)
maxOutput	number	1_000_000	Maximum bytes captured from stdout + stderr

Schema

{
  "name": "shell",
  "description": "Execute a shell command. Returns stdout, stderr, and exit code.",
  "schema": {
    "type": "object",
    "properties": {
      "command": { "type": "string", "description": "The shell command to execute" }
    },
    "required": ["command"]
  }
}

The tool always returns a string ending with [exit code: N] or [killed: command timed out after Nms].

listTools

Discover all available tools and their metadata at runtime — useful for building dashboards or validating skill hints.

import { listTools } from '@agentskit/tools'

const tools = listTools()
// [
//   { name: 'web_search', description: '...', tags: ['web', 'search'], category: 'retrieval', schema: {...} },
//   { name: 'read_file', ... },
//   { name: 'write_file', ... },
//   { name: 'list_directory', ... },
//   { name: 'shell', ... },
// ]

Each entry is a ToolMetadata object:

interface ToolMetadata {
  name: string
  description: string
  tags: string[]
  category: string
  schema: JSONSchema7
}

Troubleshooting

Issue	Mitigation
Model never calls web_search	Strengthen description; ensure the user question benefits from live data.
Filesystem access denied	Paths are jail-rooted at basePath; log resolved paths when debugging.
Shell killed	Hit timeout or maxOutput; widen limits only in trusted environments.

See also

Start here · Packages · TypeDoc (@agentskit/tools) · Runtime · Skills · @agentskit/core