Skip to content
AgentsKit

@agentskit/tools β€” Interfaces

API interfaces for @agentskit/tools.

#Interface: DefineZodToolConfig<TSchema>

Defined in: zod.ts:22

Configuration for defineZodTool, including its runtime and JSON Schema adapters.

#Type Parameters

#TSchema

TSchema extends ZodLike

#Properties

#category?

optional category?: string

Defined in: zod.ts:40


#description?

optional description?: string

Defined in: zod.ts:24


#dispose?

optional dispose?: () => MaybePromise<void>

Defined in: zod.ts:38

#Returns

MaybePromise<void>


#execute?

optional execute?: (args, context) => unknown

Defined in: zod.ts:33

#Parameters

args

InferZodOutput<TSchema>

context

ToolExecutionContext

#Returns

unknown


#init?

optional init?: () => MaybePromise<void>

Defined in: zod.ts:37

#Returns

MaybePromise<void>


#name

name: string

Defined in: zod.ts:23


#requiresConfirmation?

optional requiresConfirmation?: boolean

Defined in: zod.ts:32


#schema

schema: TSchema

Defined in: zod.ts:25


#tags?

optional tags?: string[]

Defined in: zod.ts:39


#toJsonSchema?

optional toJsonSchema?: (schema) => JSONSchema7

Defined in: zod.ts:31

Convert the Zod schema to JSON Schema. Users must supply this themselves (e.g. via zod-to-json-schema), keeping the zod dependency entirely optional.

#Parameters

schema

TSchema

#Returns

JSONSchema7


#Interface: EgressPolicy

Defined in: safe-fetch.ts:11

Default-deny egress policy (ADR-0010). All outbound HTTP from tools should pass through safeFetch / checkEgress so a model-supplied or redirected URL cannot reach internal infrastructure (SSRF).

#Properties

#allowedHosts?

optional allowedHosts?: string[]

Defined in: safe-fetch.ts:22

Literal hostname allowlist. If set, every request (and redirect hop) must match exactly β€” overrides allowPrivateHosts. Wildcards unsupported by design.


#allowPrivateHosts?

optional allowPrivateHosts?: boolean

Defined in: safe-fetch.ts:17

Allow requests to any non-public address. Off by default so an agent cannot reach private, reserved, loopback, link-local, or metadata targets. Enable only for vetted internal targets.


#maxRedirects?

optional maxRedirects?: number

Defined in: safe-fetch.ts:24

Max redirects to follow; each hop is re-gated. Default 3.


#Interface: FetchUrlConfig

Defined in: fetch-url.ts:5

Response, redirect, and egress settings for fetchUrl.

#Properties

#allowedHosts?

optional allowedHosts?: string[]

Defined in: fetch-url.ts:29

Hostname allowlist. If set, every request (and every redirect hop) must match a literal hostname in this list β€” overrides allowPrivateHosts. Wildcards are not supported by design.


#allowPrivateHosts?

optional allowPrivateHosts?: boolean

Defined in: fetch-url.ts:18

Allow requests to private/loopback/link-local addresses. Off by default so an agent can't reach AWS IMDS (169.254.169.254), the loopback interface, or internal RFC1918 services. Set true only when the tool runs against a vetted internal target.


#maxBytes?

optional maxBytes?: number

Defined in: fetch-url.ts:7

Maximum bytes to read from the response body. Default: 200 KB.


#maxRedirects?

optional maxRedirects?: number

Defined in: fetch-url.ts:23

Max redirects to follow. Each hop's resolved host is re-checked against allowPrivateHosts to block redirect-based SSRF. Default 3.


#timeoutMs?

optional timeoutMs?: number

Defined in: fetch-url.ts:9

Request timeout in ms. Default: 15000.


#userAgent?

optional userAgent?: string

Defined in: fetch-url.ts:11

Header value for User-Agent. Default: AgentsKit/1.0.


#Interface: FilesystemConfig

Defined in: filesystem.ts:6

Workspace root and symlink policy for filesystem.

#Properties

#basePath

basePath: string

Defined in: filesystem.ts:7


optional denySymlinks?: boolean

Defined in: filesystem.ts:14

When true, refuse to operate on symlinks at all (read, write, list). Default true β€” symlinks inside basePath can target outside the jail and would otherwise leak access. Set false only if you trust the contents of basePath.


#Interface: ShellConfig

Defined in: shell.ts:5

Executable allowlist, timeout, output cap, working directory, and environment for shell.

#Properties

#allowAny?

optional allowAny?: boolean

Defined in: shell.ts:20

Opt out of the allowlist requirement. When true, any executable is permitted β€” use only for trusted, sandbox-wrapped contexts. Off by default so a misconfigured agent cannot run arbitrary binaries.


#allowed?

optional allowed?: string[]

Defined in: shell.ts:14

Allowlist of permitted executables. Required by default β€” leave unset only when explicitly opting into the open mode via allowAny:true. Each entry is matched against the command's first token (the executable name).


#cwd?

optional cwd?: string

Defined in: shell.ts:24

Working directory passed to the child process.


#env?

optional env?: ProcessEnv

Defined in: shell.ts:31

Environment for the child. Defaults to safeEnv() from @agentskit/cross-platform: only the system variables a process needs to start (PATH, SystemRoot, TEMP…), so secrets in the parent environment do not leak into the executed command unless forwarded.


#maxOutput?

optional maxOutput?: number

Defined in: shell.ts:22

Cap on stdout and on stderr per invocation. Default 1 MB.


#timeout?

optional timeout?: number

Defined in: shell.ts:7

Per-command timeout in ms. Default 30s.


#Interface: SlackToolConfig

Defined in: slack.ts:9

Incoming webhook and request cancellation settings for slackTool.

#Properties

#fetch?

optional fetch?: {(input, init?): Promise<Response>; (input, init?): Promise<Response>; }

Defined in: slack.ts:12

Override fetch (mainly for tests). Defaults to the global fetch.

#Call Signature

(input, init?): Promise<Response>

MDN Reference

Parameters
input

URL | RequestInfo

init?

RequestInit

Returns

Promise<Response>

#Call Signature

(input, init?): Promise<Response>

MDN Reference

Parameters
input

string | URL | Request

init?

RequestInit

Returns

Promise<Response>


#signal?

optional signal?: AbortSignal

Defined in: slack.ts:14


#timeoutMs?

optional timeoutMs?: number

Defined in: slack.ts:13


#webhookUrl

webhookUrl: string

Defined in: slack.ts:10


#Interface: SqliteQueryConfig

Defined in: sqlite-query.ts:5

Read-only database path and row limit for sqliteQueryTool.

#Properties

#maxRows?

optional maxRows?: number

Defined in: sqlite-query.ts:10

Max rows returned. Defaults to 100.


#path

path: string

Defined in: sqlite-query.ts:6


#readOnly?

optional readOnly?: true

Defined in: sqlite-query.ts:8

Reserved for v2; only true is accepted today.


#Interface: WebSearchConfig

Defined in: web-search.ts:22

Provider, credentials, result count, timeout, response cap, and custom search settings for webSearch.

#Properties

#apiKey?

optional apiKey?: string

Defined in: web-search.ts:29


#maxResponseBytes?

optional maxResponseBytes?: number

Defined in: web-search.ts:34

Maximum provider response body size. Defaults to 2 MiB.


#maxResults?

optional maxResults?: number

Defined in: web-search.ts:30


#mcpClient?

optional mcpClient?: McpClient

Defined in: web-search.ts:42

MCP client used by provider: 'parallel'. Host-owned: bring your own transport and authentication. Defaults to a keyless HTTP client for Parallel Search MCP (https://search.parallel.ai/mcp).


#provider?

optional provider?: WebSearchProvider

Defined in: web-search.ts:28

Which backend to use. 'auto' (default) picks the best available: Serper if SERPER_API_KEY is set, Tavily if TAVILY_API_KEY is set, otherwise falls back to an unauthenticated DuckDuckGo HTML scrape.


optional search?: (query) => Promise<WebSearchResult[]>

Defined in: web-search.ts:44

Custom search function β€” overrides every other path.

#Parameters

query

string

#Returns

Promise<WebSearchResult[]>


#signal?

optional signal?: AbortSignal

Defined in: web-search.ts:36

Caller cancellation signal.


#timeoutMs?

optional timeoutMs?: number

Defined in: web-search.ts:32

Overall deadline for provider and custom-search work. Defaults to 15s.


#Interface: WebSearchResult

Defined in: web-search.ts:9

Title, URL, and text snippet returned by a web-search provider.

#Properties

#snippet

snippet: string

Defined in: web-search.ts:12


#title

title: string

Defined in: web-search.ts:10


#url

url: string

Defined in: web-search.ts:11

Explore nearby