@agentskit/tools

@agentskit/tools

Profile: major-package

Give your agents real-world capabilities without writing a single integration.

Tags: ai · agents · llm · agentskit · ai-agents · function-calling · tool-use · mcp · web-search · filesystem

Verified proof

• Package metadata and tests live under packages/tools/.
• Package guide: https://www.agentskit.io/docs/reference/packages/tools
• Stability map: docs/STABILITY.md

How this fits the ecosystem

@agentskit/tools gives agents useful hands: web fetch, search, filesystem, shell, SQLite, integrations, and MCP-friendly tool definitions.

• AgentsKit: compose it with the other packages in this repo to build agents from small, swappable parts.
• Registry: look for ready agents and templates that already use this layer at registry.agentskit.io.
• Playbook: learn the production patterns behind this layer at playbook.agentskit.io.
• AKOS: run the same concepts with enterprise deployment, governance, and observability at akos.agentskit.io.

Docs: package guide · agent handoff

Why tools

• Save days of integration work — web search, filesystem read/write, shell execution, and directory listing are ready to drop in; no wiring required
• Safe by default — filesystem tools are sandboxed to a basePath, shell commands require an explicit allowlist, so agents can't escape their boundaries
• Composable with any runtime — tools are just objects with a schema; they work with @agentskit/runtime, useChat, or any custom ReAct loop
• Extend without friction — author custom tools with @agentskit/templates and register them the same way as built-ins

Install

npm install @agentskit/tools

Quick example

import { createRuntime } from '@agentskit/runtime'
import { openai } from '@agentskit/adapters'
import { webSearch, filesystem, shell } from '@agentskit/tools'

const runtime = createRuntime({
  adapter: openai({ apiKey: process.env.OPENAI_API_KEY, model: 'gpt-4o' }),
  tools: [
    webSearch(),
    ...filesystem({ basePath: './workspace' }),
    shell({ timeout: 10_000, allowed: ['ls', 'cat', 'grep'] }),
  ],
})

const result = await runtime.run('Find the README and summarize it')
console.log(result.content)

With useChat (browser)

Tools are plain ToolDefinition values — register them in useChat the same way as in createRuntime.

Authoring tools with defineZodTool

If you use Zod, @agentskit/tools ships defineZodTool — a factory that:

• Types execute args from a Zod schema (full TypeScript inference)
• Validates args at runtime via schema.parse before calling your function
• Converts the Zod schema to JSON Schema for the adapter via a user-supplied toJsonSchema callback

Zod and zod-to-json-schema are consumer-owned optional dependencies. They are not package peers because defineZodTool accepts a structural schema and a consumer-supplied JSON-Schema converter.

npm install zod zod-to-json-schema

import { z } from 'zod'
import { zodToJsonSchema } from 'zod-to-json-schema'
import { defineZodTool } from '@agentskit/tools'
import type { JSONSchema7 } from 'json-schema'

const lookupUser = defineZodTool({
  name: 'lookup_user',
  description: 'Look up a user by ID.',
  schema: z.object({
    userId: z.string().uuid(),
    includeProfile: z.boolean().optional(),
  }),
  toJsonSchema: (s) => zodToJsonSchema(s) as JSONSchema7,
  async execute(args) {
    // args.userId         → string  (UUID-validated by Zod at runtime)
    // args.includeProfile → boolean | undefined
    return await db.users.findById(args.userId, { profile: args.includeProfile })
  },
})

For tools without Zod, use defineTool from @agentskit/core with a JSON Schema as const.

Features

Built-ins (6)

• webSearch() — live web search with Serper, Tavily, DuckDuckGo, or a custom provider.
• fetchUrl() — safe HTTP GET with JSON / text handling, size cap, boilerplate stripping.
• filesystem({ basePath }) — sandboxed read, write, and list operations.
• shell({ allowed }) — shell execution with command allow-list + timeout.
• sqliteQueryTool({ path }) — read-only SQL against a local SQLite file. Optional peer dep on better-sqlite3. Note: never feed unvalidated user prompts straight into the sql field — wrap with input filtering or use parameterized helpers if exposing it to untrusted input.
• slackTool({ webhookUrl }) — post to a Slack Incoming Webhook. For Bearer-token features (search, channel listing), use the slack() integration.

Integrations (20+)

github, linear, slack, notion, discord, gmail, googleCalendar, stripe, postgres, s3, firecrawl, reader, documentParsers (PDF / DOCX / XLSX), openaiImages, elevenlabs, whisper, deepgram, maps, weather, coingecko, browserAgent (Puppeteer). Each integration exports granular sub-tools (e.g. githubCreateIssue, stripeCreatePaymentIntent) alongside the bundled set.

Authoring + composition

• defineZodTool — Zod-based factory with runtime validation + type inference.
• For composition, use composeTool and wrapToolWithSelfDebug from @agentskit/core.
• For execution policy, use createMandatorySandbox from @agentskit/sandbox.

MCP bridge

• createMcpClient + toolsFromMcpClient — consume any MCP server's tools.
• createMcpServer — publish AgentsKit tools to an MCP host that supports the documented 2024-11-05 tools bridge. Tools marked requiresConfirmation fail closed unless authorizeToolCall returns an explicit approval. Pass validateArgs (for example, createAjvValidator()) to enforce advertised schemas before execution; remote errors are sanitized unless exposeErrors: true is explicitly enabled for trusted development.
• Stdio + in-memory transports. HTTP/SSE adapters are host-owned.

Supported MCP protocol matrix

Protocol revision	Lifecycle	Supported transports	Supported methods	Explicitly outside this bridge
2024-11-05	initialize with exact-version negotiation; tools/list and tools/call; close settles pending calls	stdio, in-memory, or an injected transport	initialize, tools/list, tools/call	resources, prompts, sampling, tasks, HTTP/WebSocket, authentication, rate limiting, and persistence

The client and server fail closed when initialize.params.protocolVersion is not 2024-11-05. Hosts that need an omitted capability must provide it around the injected transport; the bridge does not imply support or isolation that it does not implement.

All tools honor the ToolDefinition contract (ADR 0002) — parallel tool calling works with any adapter, @agentskit/runtime, useChat, or a custom loop.

Subpaths

Subpath	Contents
@agentskit/tools/mcp	createMcpClient, createMcpServer, toolsFromMcpClient, stdio + in-memory transports. MCP bridge recipe.
@agentskit/tools/integrations	github, linear, slack, notion, discord, gmail, googleCalendar, stripe, postgres, s3, firecrawl, reader, documentParsers, openaiImages, elevenlabs, whisper, deepgram, maps, weather, coingecko, browserAgent. Integrations recipe + More integrations.
@agentskit/tools/mcp-devtools	Runtime inspection tools for an injected RuntimeInspector; expose through @agentskit/tools/mcp.
@agentskit/tools/validation	Optional Ajv-backed ArgsValidator for core and MCP argument enforcement.

Ecosystem

Package	Role
@agentskit/core	ToolDefinition contract
@agentskit/runtime	createRuntime({ tools })
@agentskit/react	useChat + tools in the UI
@agentskit/templates	Scaffold new tools

Contributors

License

MIT — see LICENSE.

Docs

Full documentation · GitHub

Maturity and compatibility

• Stability: beta — see docs/STABILITY.md
• Node.js 20+ and TypeScript strict mode
• Published as @agentskit/tools

Contributing

See CONTRIBUTING.md and the monorepo LICENSE.