feat(core): support Valibot schemas for tools

.changeset/valibot-tool-schemas.md

@@ -0,0 +1,7 @@
+---
+"@voltagent/core": minor
+---
+
+Let tools use Valibot (and other Standard Schema libraries) for their parameter and output schemas, not just Zod.
+
+Tool schemas now accept any Standard Schema, so `createTool`/`new Tool` take a Valibot schema and infer the `execute` args from it. Zod keeps working exactly as before. Since Valibot doesn't ship a JSON Schema extension yet, VoltAgent converts Valibot schemas with `@valibot/to-json-schema` (install it alongside `valibot` to use Valibot schemas); Zod-only users don't need it and nothing extra loads for them.

packages/core/package.json

@@ -36,6 +36,7 @@
     "@opentelemetry/sdk-trace-base": "^2.0.0",
     "@opentelemetry/sdk-trace-node": "^2.0.0",
     "@opentelemetry/semantic-conventions": "^1.28.0",
+    "@standard-schema/spec": "^1.0.0",
     "@voltagent/internal": "^1.0.3",
     "fast-glob": "^3.3.3",
     "gray-matter": "^4.0.3",
@@ -52,9 +53,11 @@
     "@ai-sdk/provider-utils": "^4.0.0",
     "@types/micromatch": "^4.0.10",
     "@types/uuid": "^10.0.0",
+    "@valibot/to-json-schema": "^1.0.0",
     "@vitest/coverage-v8": "^3.2.4",
     "ai": "^6.0.0",
     "msw": "^2.11.5",
+    "valibot": "^1.0.0",
     "zod": "^3.25.76"
   },
   "exports": {
@@ -78,11 +81,15 @@
   "module": "dist/index.mjs",
   "peerDependencies": {
     "@ai-sdk/provider-utils": "4.x",
+    "@valibot/to-json-schema": "^1.0.0",
     "@voltagent/logger": "2.0.2",
     "ai": "^6.0.0",
     "zod": "^3.25.0 || ^4.0.0"
   },
   "peerDependenciesMeta": {
+    "@valibot/to-json-schema": {
+      "optional": true
+    },
     "@voltagent/logger": {
       "optional": true
     }

packages/core/src/agent/agent.ts

@@ -78,6 +78,7 @@ import type {
   ToolSearchSelection,
   ToolSearchStrategy,
 } from "../tool/routing/types";
+import { normalizeToolSchemasForModel } from "../tool/standard-schema";
 import { randomUUID } from "../utils/id";
 import { convertModelMessagesToUIMessages } from "../utils/message-converter";
 import { NodeType, createNodeId } from "../utils/node-utils";
@@ -6364,6 +6365,10 @@ export class Agent {
     const preparedStaticTools =
       this.toolManager.prepareToolsForExecution(createToolExecuteFunction);
 
+    // Convert non-Zod schemas (e.g. Valibot) so the model still gets JSON Schema params.
+    await normalizeToolSchemasForModel(preparedDynamicTools);
+    await normalizeToolSchemasForModel(preparedStaticTools);
+
     const toolRouting = this.resolveToolRouting(options);
     oc.systemContext.set(TOOL_ROUTING_CONTEXT_KEY, toolRouting);
     if (toolRouting === false) {

packages/core/src/agent/providers/base/types.ts

@@ -5,6 +5,7 @@ import type {
   ToolContent,
   UserContent,
 } from "@ai-sdk/provider-utils";
+import type { StandardSchemaV1 } from "@standard-schema/spec";
 import type { AsyncIterableStream } from "@voltagent/internal/utils";
 import type { TextStreamPart } from "ai";
 import type { z } from "zod";
@@ -242,7 +243,26 @@ export type MessageRole = "user" | "assistant" | "system" | "tool";
 export type BaseMessage = ModelMessage;
 
 // Schema types
-export type ToolSchema = z.ZodType;
+/**
+ * Schema accepted for tool parameters and output.
+ *
+ * Any Standard Schema library works here (Valibot, ArkType, Effect Schema, ...),
+ * and Zod stays fully supported since Zod implements the Standard Schema interface.
+ * The AI SDK converts whatever it's given to JSON Schema for the model.
+ */
+export type ToolSchema = z.ZodType | StandardSchemaV1;
+
+/**
+ * Infer the parsed output type of a tool schema.
+ *
+ * Zod schemas keep going through `z.infer` for exact backward compatibility;
+ * other Standard Schema libraries resolve via their inferred output type.
+ */
+export type InferSchema<T> = T extends z.ZodType
+  ? z.infer<T>
+  : T extends StandardSchemaV1
+    ? StandardSchemaV1.InferOutput<T>
+    : unknown;
 
 /**
  * Tool execution context containing all tool-specific metadata.

packages/core/src/tool/index.ts

@@ -1,7 +1,11 @@
 import type { ProviderOptions, ToolNeedsApprovalFunction } from "@ai-sdk/provider-utils";
 import type { Tool as VercelTool } from "ai";
-import type { z } from "zod";
-import type { BaseTool, ToolExecuteOptions, ToolSchema } from "../agent/providers/base/types";
+import type {
+  BaseTool,
+  InferSchema,
+  ToolExecuteOptions,
+  ToolSchema,
+} from "../agent/providers/base/types";
 import { LoggerProxy } from "../logger";
 
 /**
@@ -161,7 +165,7 @@ export type ToolOptions<
    * Whether the tool requires approval before execution.
    * When set to a function, it can decide dynamically per call.
    */
-  needsApproval?: boolean | ToolNeedsApprovalFunction<z.infer<T>>;
+  needsApproval?: boolean | ToolNeedsApprovalFunction<InferSchema<T>>;
 
   /**
    * Provider-specific options for the tool.
@@ -204,7 +208,7 @@ export type ToolOptions<
    * ```
    */
   toModelOutput?: (args: {
-    output: O extends ToolSchema ? z.infer<O> : unknown;
+    output: O extends ToolSchema ? InferSchema<O> : unknown;
   }) => ToolResultOutput;
 
   /**
@@ -214,9 +218,9 @@ export type ToolOptions<
    * @returns A result or an AsyncIterable of results (last value is final).
    */
   execute?: (
-    args: z.infer<T>,
+    args: InferSchema<T>,
     options?: ToolExecuteOptions,
-  ) => ToolExecutionResult<O extends ToolSchema ? z.infer<O> : unknown>;
+  ) => ToolExecutionResult<O extends ToolSchema ? InferSchema<O> : unknown>;
 
   /**
    * Optional tool-specific hooks for lifecycle events.
@@ -228,7 +232,7 @@ export type ToolOptions<
  * Tool class for defining tools that agents can use
  */
 export class Tool<T extends ToolSchema = ToolSchema, O extends ToolSchema | undefined = undefined> {
-  /* implements BaseTool<z.infer<T>> */
+  /* implements BaseTool<InferSchema<T>> */
   /**
    * Unique identifier for the tool
    */
@@ -262,7 +266,7 @@ export class Tool<T extends ToolSchema = ToolSchema, O extends ToolSchema | unde
   /**
    * Whether the tool requires approval before execution.
    */
-  readonly needsApproval?: boolean | ToolNeedsApprovalFunction<z.infer<T>>;
+  readonly needsApproval?: boolean | ToolNeedsApprovalFunction<InferSchema<T>>;
 
   /**
    * Provider-specific options for the tool.
@@ -278,7 +282,7 @@ export class Tool<T extends ToolSchema = ToolSchema, O extends ToolSchema | unde
    * Enables returning images, media, or structured content to the LLM.
    */
   readonly toModelOutput?: (args: {
-    output: O extends ToolSchema ? z.infer<O> : unknown;
+    output: O extends ToolSchema ? InferSchema<O> : unknown;
   }) => ToolResultOutput;
 
   /**
@@ -299,9 +303,9 @@ export class Tool<T extends ToolSchema = ToolSchema, O extends ToolSchema | unde
    * @returns A result or an AsyncIterable of results (last value is final).
    */
   readonly execute?: (
-    args: z.infer<T>,
+    args: InferSchema<T>,
     options?: ToolExecuteOptions,
-  ) => ToolExecutionResult<O extends ToolSchema ? z.infer<O> : unknown>;
+  ) => ToolExecutionResult<O extends ToolSchema ? InferSchema<O> : unknown>;
 
   /**
    * Whether this tool should be executed on the client side.

packages/core/src/tool/standard-schema.spec.ts

@@ -0,0 +1,98 @@
+import { asSchema } from "ai";
+import * as v from "valibot";
+import { describe, expect, expectTypeOf, it } from "vitest";
+import { z } from "zod";
+import { createTool } from "./index";
+import { normalizeToolSchemasForModel, toModelToolSchema } from "./standard-schema";
+
+describe("Valibot tool schemas", () => {
+  it("accepts a Valibot schema and infers execute args from it", async () => {
+    const executed: Array<{ city: string; days?: number }> = [];
+
+    const tool = createTool({
+      name: "getWeather",
+      description: "Get the weather for a city",
+      parameters: v.object({
+        city: v.string(),
+        days: v.optional(v.number()),
+      }),
+      execute: async (args) => {
+        // Types come from the Valibot schema, not `any`.
+        expectTypeOf(args.city).toEqualTypeOf<string>();
+        expectTypeOf(args.days).toEqualTypeOf<number | undefined>();
+        executed.push(args);
+        return { forecast: "sunny" };
+      },
+    });
+
+    expect(tool.name).toBe("getWeather");
+    expect(tool.parameters).toBeDefined();
+
+    await tool.execute?.({ city: "Paris", days: 3 });
+    expect(executed).toEqual([{ city: "Paris", days: 3 }]);
+  });
+
+  it("converts a Valibot schema to the same JSON Schema as the Zod equivalent", async () => {
+    const valibotSchema = v.object({
+      city: v.string(),
+      days: v.optional(v.number()),
+    });
+    const zodSchema = z.object({
+      city: z.string(),
+      days: z.number().optional(),
+    });
+
+    const converted = await toModelToolSchema(valibotSchema);
+    const valibotJson = asSchema(converted).jsonSchema;
+    const zodJson = asSchema(zodSchema).jsonSchema;
+
+    expect(valibotJson.type).toBe("object");
+    expect(valibotJson.properties).toEqual({
+      city: { type: "string" },
+      days: { type: "number" },
+    });
+    expect(valibotJson.required).toEqual(["city"]);
+    // Same shape the model would see for the Zod version.
+    expect(valibotJson.properties).toEqual(zodJson.properties);
+    expect(valibotJson.required).toEqual(zodJson.required);
+  });
+
+  it("keeps Valibot validation on the converted schema", async () => {
+    const converted = await toModelToolSchema(
+      v.object({ city: v.string(), days: v.optional(v.number()) }),
+    );
+    const schema = asSchema(converted);
+
+    const ok = await schema.validate?.({ city: "Paris", days: 3 });
+    expect(ok).toEqual({ success: true, value: { city: "Paris", days: 3 } });
+
+    const bad = await schema.validate?.({ city: 123 });
+    expect(bad?.success).toBe(false);
+  });
+
+  it("leaves Zod schemas untouched", async () => {
+    const zodSchema = z.object({ query: z.string() });
+    const result = await toModelToolSchema(zodSchema);
+    expect(result).toBe(zodSchema);
+  });
+
+  it("normalizes only Valibot entries in a prepared tool map", async () => {
+    const zodSchema = z.object({ query: z.string() });
+    const valibotSchema = v.object({ query: v.string() });
+
+    const tools: Record<string, { inputSchema?: unknown }> = {
+      zodTool: { inputSchema: zodSchema },
+      valibotTool: { inputSchema: valibotSchema },
+      providerTool: {},
+    };
+
+    await normalizeToolSchemasForModel(tools);
+
+    expect(tools.zodTool.inputSchema).toBe(zodSchema);
+    expect(tools.valibotTool.inputSchema).not.toBe(valibotSchema);
+    expect(asSchema(tools.valibotTool.inputSchema).jsonSchema.properties).toEqual({
+      query: { type: "string" },
+    });
+    expect(tools.providerTool.inputSchema).toBeUndefined();
+  });
+});

packages/core/src/tool/standard-schema.ts

@@ -0,0 +1,92 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import { safeStringify } from "@voltagent/internal/utils";
+import { jsonSchema } from "ai";
+
+/**
+ * Tool schemas can come from any Standard Schema library, not just Zod. The AI SDK
+ * turns Zod schemas and any Standard Schema that ships a JSON Schema extension into
+ * JSON Schema on its own, so those pass straight through.
+ *
+ * Valibot is the exception: as of v1 its `~standard` entry only exposes `validate`,
+ * with no JSON Schema, so the model would never see the parameter shape. For those we
+ * convert to JSON Schema with `@valibot/to-json-schema` (an optional peer dependency)
+ * and keep Valibot's own validator for argument checking.
+ */
+
+type ToJsonSchema = (schema: unknown, config?: Record<string, unknown>) => Record<string, unknown>;
+
+let converterPromise: Promise<ToJsonSchema> | undefined;
+
+function isStandardSchema(schema: unknown): schema is StandardSchemaV1 {
+  return typeof schema === "object" && schema !== null && "~standard" in schema;
+}
+
+/**
+ * True when a schema needs VoltAgent to convert it before the AI SDK sees it.
+ * Zod and JSON-Schema-capable Standard Schemas are left untouched.
+ */
+function needsValibotConversion(schema: unknown): schema is StandardSchemaV1 {
+  if (!isStandardSchema(schema)) return false;
+  const standard = schema["~standard"] as StandardSchemaV1.Props & { jsonSchema?: unknown };
+  if (standard.vendor === "zod") return false;
+  if ("jsonSchema" in standard) return false;
+  return standard.vendor === "valibot";
+}
+
+async function loadValibotConverter(): Promise<ToJsonSchema> {
+  if (!converterPromise) {
+    converterPromise = import("@valibot/to-json-schema")
+      .then((mod) => mod.toJsonSchema as unknown as ToJsonSchema)
+      .catch(() => {
+        throw new Error(
+          "A Valibot schema was passed to a tool, but '@valibot/to-json-schema' is not installed. " +
+            "Install it to use Valibot schemas: `npm install @valibot/to-json-schema`.",
+        );
+      });
+  }
+  return converterPromise;
+}
+
+/**
+ * Normalize a tool schema into a form the AI SDK can hand to the model. Zod and other
+ * schemas pass through unchanged; Valibot schemas are converted to a JSON Schema that
+ * keeps Valibot's runtime validation.
+ */
+export async function toModelToolSchema(schema: unknown): Promise<unknown> {
+  if (!needsValibotConversion(schema)) {
+    return schema;
+  }
+
+  const toJsonSchema = await loadValibotConverter();
+  const standard = schema["~standard"];
+
+  return jsonSchema(toJsonSchema(schema, { errorMode: "ignore" }), {
+    validate: async (value) => {
+      const result = await standard.validate(value);
+      if (result.issues) {
+        return {
+          success: false,
+          error: new Error(`Tool argument validation failed: ${safeStringify(result.issues)}`),
+        };
+      }
+      return { success: true, value: result.value };
+    },
+  });
+}
+
+/**
+ * Rewrite the `inputSchema` of every entry in a prepared tool map so Valibot-defined
+ * tools produce a JSON Schema for the model. Mutates in place; provider tools and
+ * tools without a schema are left alone.
+ */
+export async function normalizeToolSchemasForModel(
+  tools: Record<string, { inputSchema?: unknown }>,
+): Promise<void> {
+  await Promise.all(
+    Object.values(tools).map(async (tool) => {
+      if (tool && "inputSchema" in tool && needsValibotConversion(tool.inputSchema)) {
+        tool.inputSchema = await toModelToolSchema(tool.inputSchema);
+      }
+    }),
+  );
+}