@agentskit/tools/validation — for agents

Opt-in runtime validation of tool-call arguments against their JSON Schema. Wraps Ajv; plugs into the core ArgsValidator contract (ADR-0008).

#Install

npm install @agentskit/tools

#Why

The real untrusted boundary in an agent is model output. A model returns tool-call args as arbitrary JSON; core parses them (safeParseArgs) but does not check them against the tool's schema — execute receives args the type system only claims are valid. This package enforces the tool's existing JSONSchema7 at runtime. JSON Schema stays the single source of truth (ADR-0008); no Zod, no duplicate contract.

#Primary exports

createAjvValidator(options?) — returns an ArgsValidator (the core contract) backed by Ajv. Pass it as validateArgs on the chat controller or runtime config. Invalid args raise AK_TOOL_INVALID_INPUT before execute runs.

#Options (`AjvValidatorOptions`)

Field	Default	Notes
`rejectAdditionalProperties`	`false`	Recursively closes ordinary object boundaries that omit `additionalProperties`. Explicit policies are preserved. Composition/applicator boundaries stay as authored; close them explicitly when required.
`coerceTypes`	`false`	Coerce unambiguous primitives (e.g. `"42"` → `42`). Successful validation may mutate the args object.
`ajv`	—	Supply a pre-configured Ajv instance. It owns coercion, formats, keywords, strictness, and other Ajv behavior.

#Usage

import { createChatController } from '@agentskit/core'
import { createAjvValidator } from '@agentskit/tools/validation'

const chat = createChatController({
  adapter,
  tools: [weatherTool],
  validateArgs: createAjvValidator(),
})

Same shape on the runtime:

import { createRuntime } from '@agentskit/runtime'
import { createAjvValidator } from '@agentskit/tools/validation'

const runtime = createRuntime({ adapter, tools, validateArgs: createAjvValidator() })

#Notes

Opt-in. Omit validateArgs and behaviour is unchanged (passthrough). Core stays zero-dependency; Ajv lives only here.
Single source of truth. Validates the optional schema already on each ToolDefinition. Tools with no schema are skipped.
Compiled validators are cached by schema identity — repeated calls do not recompile.
Schemas are trusted application configuration. Invalid schemas throw when first compiled; invalid model arguments return structured field errors without echoing values.
The implementation package is private. Install @agentskit/tools and import only @agentskit/tools/validation.
See ADR-0008 (docs/architecture/adrs/0008-runtime-validation.md).

Explore nearby

✎ Edit this page on GitHub·Found a problem? Open an issue →·How to contribute →