Schema Validation & Argument Coercion

Automatically serialize Zod schemas and pre-coerce argument types.

Models sometimes send stringified numbers or booleans like "42" or "true" when your schema expects primitive numbers or booleans. kenpachi automatically pre-coerces these primitive argument types before validating arguments with Zod.

Argument pre-coercion is enabled by default for every tool defined with defineTool.

---

What happens step by step

1. Serialize — Tool Zod schemas are dynamically converted to standard JSON Schema (type: "object", properties, required) using serializeZodSchema so the model receives clean parameter declarations.
2. Pre-Coerce — Incoming arguments are pre-coerced (e.g. "6" → 6, "true" → true) before schema parsing runs.
3. Validate — Coerced arguments are checked against your Zod schema using schema.safeParse().
4. Error handling — If arguments remain invalid after coercion, formatted validation errors are captured and returned cleanly without crashing your execution loop.

---

Example

import { z } from "zod";
import { Agent, defineTool, createOpenAIProvider } from "kenpachi";

const multiply = defineTool({
  name: "multiply",
  description: "Multiplies two numbers",
  schema: z.object({
    a: z.number(),
    b: z.number(),
  }),
  async execute({ a, b }) {
    return { product: a * b };
  },
});

const provider = createOpenAIProvider({
  apiKey: process.env.OPENAI_API_KEY!,
  model: "gpt-4o",
});
const agent = new Agent(provider, [multiply]);

// Model might send { a: "6", b: "7" } — kenpachi pre-coerces primitives and succeeds.
const result = await agent.run("What is 6 times 7?");
console.log(result.text);

---

Disable repair for a tool

Set repairable: false when invalid argument attempts should fail immediately without retry attempts (e.g. handoffs, security-sensitive tools):

defineTool({
  name: "delete_account",
  repairable: false,
  // ...
});

Configure max retry attempts per run with maxToolRepairAttempts on agent.run().