chore: enhance VoltAgent 3.x with AI SDK Tool Integration

Author: omeraplak

.changeset/voltagent-3-next.md

@@ -151,7 +151,7 @@ const result = await agent.streamText({
 
 VoltAgent composes the fields it must own for framework behavior: `model`, `prompt`/`messages`, `tools`, `abortSignal`, `maxRetries`, `onStepEnd`, `onEnd`/`onFinish`, and `onError`. User callbacks are still accepted at the top level and are invoked after VoltAgent memory, guardrails, hooks, tracing, and recovery handling.
 
-Top-level AI SDK `runtimeContext`, `toolsContext`, `telemetry`, and `experimental_telemetry` are intentionally not exposed. Use `voltagent.context` for per-call application context, VoltAgent tool context/hooks for tool execution context, and VoltAgent observability/OpenTelemetry configuration for telemetry.
+Top-level AI SDK `toolsContext` is passed through for native AI SDK tools that declare `contextSchema`. Top-level AI SDK `runtimeContext`, `telemetry`, and `experimental_telemetry` are intentionally not exposed. Use `voltagent.context` for per-call application context and VoltAgent observability/OpenTelemetry configuration for telemetry.
 
 The same shape works for streaming:
 
@@ -178,10 +178,11 @@ for await (const part of result.stream) {
 
 ### Tool usage
 
-VoltAgent now accepts AI SDK-style tool sets directly. The recommended custom tool API is `tool()` from `@voltagent/core`, extended with VoltAgent-specific metadata under the `voltagent` namespace.
+VoltAgent now accepts AI SDK-style tool sets directly. Raw AI SDK tools are first-class, so the recommended custom tool API is `tool()` from `ai`. Add VoltAgent-specific metadata with `withVoltAgentMetadata` when you need hooks, tags, API metadata, or display metadata.
 
 ```ts
-import { Agent, tool } from "@voltagent/core";
+import { tool } from "ai";
+import { Agent } from "@voltagent/core";
 import { openai } from "@ai-sdk/openai";
 import { z } from "zod";
 
@@ -202,25 +203,77 @@ const agent = new Agent({
 });
 ```
 
-VoltAgent-specific tool metadata is available through the `voltagent` namespace, so existing framework features can be used with AI SDK-style tools:
+Native AI SDK tool options such as `contextSchema` work unchanged with call-level `toolsContext`:
 
 ```ts
-const refundCustomer = tool({
-  description: "Refund a customer order",
-  inputSchema: z.object({
-    orderId: z.string(),
-    reason: z.string(),
+const weather = tool({
+  description: "Get weather for a city",
+  inputSchema: z.object({ city: z.string() }),
+  contextSchema: z.object({
+    apiKey: z.string(),
+    defaultUnit: z.enum(["celsius", "fahrenheit"]),
   }),
-  execute: async ({ orderId, reason }) => {
-    return issueRefund(orderId, reason);
+  execute: async ({ city }, { context }) => {
+    return fetchWeather(city, {
+      apiKey: context.apiKey,
+      unit: context.defaultUnit,
+    });
   },
-  voltagent: {
-    name: "Refund Customer",
-    purpose: "Issue customer refunds",
+});
+
+await agent.generateText({
+  prompt: "What is the weather in San Francisco?",
+  tools: { weather },
+  toolsContext: {
+    weather: {
+      apiKey: process.env.WEATHER_API_KEY!,
+      defaultUnit: "fahrenheit",
+    },
   },
 });
 ```
 
+VoltAgent-specific tool metadata is optional and stored out-of-band so it is not sent to the model provider:
+
+```ts
+import { tool } from "ai";
+import { withVoltAgentMetadata } from "@voltagent/core";
+
+const refundCustomer = withVoltAgentMetadata(
+  tool({
+    description: "Refund a customer order",
+    inputSchema: z.object({
+      orderId: z.string(),
+      reason: z.string(),
+    }),
+    contextSchema: z.object({
+      actorId: z.string(),
+      permissions: z.array(z.string()),
+    }),
+    execute: async ({ orderId, reason }, { context }) => {
+      if (!context.permissions.includes("refund:write")) {
+        throw new Error("Not allowed to refund orders");
+      }
+
+      return issueRefund({
+        orderId,
+        reason,
+        actorId: context.actorId,
+      });
+    },
+  }),
+  {
+    name: "Refund Customer",
+    purpose: "Issue customer refunds",
+    tags: ["billing", "dangerous", "customer-support"],
+    metadata: {
+      owner: "payments-team",
+      riskLevel: "high",
+    },
+  }
+);
+```
+
 Register the tool under the canonical name the model should call:
 
 ```ts
@@ -233,11 +286,9 @@ const agent = new Agent({
 });
 ```
 
-The ToolSet key remains the canonical `tool.name` used for tool calls, approval, routing, and telemetry correlation. `voltagent.name` is display metadata and is emitted as `tool.display_name` for Console and observability consumers.
-
-VoltAgent `tool()` intentionally does not expose AI SDK `contextSchema`, `runtimeContext`, `toolsContext`, `telemetry`, or `experimental_telemetry`. Use `voltagent.context` on the agent call for per-request application context, `voltagent` tool hooks for VoltAgent lifecycle context, and VoltAgent observability/OpenTelemetry configuration for telemetry.
+The ToolSet key remains the canonical `tool.name` used for tool calls, approval, routing, and telemetry correlation. VoltAgent metadata `name` is display metadata and is emitted as `tool.display_name` for Console and observability consumers.
 
-`createTool` is now a legacy compatibility helper for existing class-style tools. New code should use `tool()`.
+`tool()` from `@voltagent/core` remains available as a convenience wrapper when inline `voltagent` metadata is preferred. `createTool` is now a legacy compatibility helper for existing class-style tools.
 
 ### Tool approval
 

packages/core/src/agent/agent.spec-d.ts

@@ -1,11 +1,17 @@
 import type { ModelMessage } from "@ai-sdk/provider-utils";
-import { type FinishReason, type LanguageModelUsage, Output, type UIMessage } from "ai";
+import {
+  type FinishReason,
+  type LanguageModelUsage,
+  Output,
+  type UIMessage,
+  tool as rawAiTool,
+} from "ai";
 import { MockLanguageModelV3 } from "ai/test";
 import { describe, expectTypeOf, it } from "vitest";
 import { z } from "zod";
 import type { ModelRouterModelId } from "../registries/model-provider-types.generated";
 import type { BaseRetriever } from "../retriever/retriever";
-import { Tool, type Toolkit, tool as aiSdkTool, createTool } from "../tool";
+import { Tool, type Toolkit, tool as aiSdkTool, createTool, withVoltAgentMetadata } from "../tool";
 import type { StreamEventType } from "../utils/streams";
 import type { Voice } from "../voice";
 import type { VoltOpsClient } from "../voltops/client";
@@ -238,46 +244,69 @@ describe("Agent Type System", () => {
       expectTypeOf(agent).toMatchTypeOf<Agent>();
     });
 
-    it("should reject VoltAgent-owned context and telemetry fields on AI SDK-style tools", () => {
-      aiSdkTool({
-        description: "Test",
-        inputSchema: z.object({ value: z.string() }),
-        // @ts-expect-error - use `voltagent.context` and VoltAgent tool hooks instead
-        contextSchema: z.object({ tenantId: z.string() }),
-        execute: async ({ value }) => ({ result: value }),
+    it("should accept AI SDK contextSchema on AI SDK-style tools", () => {
+      const weatherTool = aiSdkTool({
+        description: "Get weather",
+        inputSchema: z.object({ city: z.string() }),
+        contextSchema: z.object({
+          apiKey: z.string(),
+          defaultUnit: z.enum(["celsius", "fahrenheit"]),
+        }),
+        execute: async ({ city }, { context }) => {
+          expectTypeOf(context.apiKey).toEqualTypeOf<string>();
+          expectTypeOf(context.defaultUnit).toEqualTypeOf<"celsius" | "fahrenheit">();
+          return { city, unit: context.defaultUnit };
+        },
       });
 
-      aiSdkTool({
-        description: "Test",
-        inputSchema: z.object({ value: z.string() }),
-        // @ts-expect-error - runtime context is owned by VoltAgent agent calls
-        runtimeContext: { tenantId: "tenant-1" },
-        execute: async ({ value }) => ({ result: value }),
+      const agent = new Agent({
+        name: "Weather",
+        instructions: "Test",
+        model: mockModel,
+        tools: {
+          weather: weatherTool,
+        },
       });
 
-      aiSdkTool({
-        description: "Test",
-        inputSchema: z.object({ value: z.string() }),
-        // @ts-expect-error - tools context is owned by VoltAgent
-        toolsContext: {},
-        execute: async ({ value }) => ({ result: value }),
-      });
+      expectTypeOf(agent).toMatchTypeOf<Agent>();
+    });
 
-      aiSdkTool({
-        description: "Test",
-        inputSchema: z.object({ value: z.string() }),
-        // @ts-expect-error - use VoltAgent observability/OpenTelemetry instead
-        telemetry: { isEnabled: false },
-        execute: async ({ value }) => ({ result: value }),
-      });
+    it("should attach VoltAgent metadata to raw AI SDK tools", () => {
+      const refundCustomer = withVoltAgentMetadata(
+        rawAiTool({
+          description: "Refund a customer order",
+          inputSchema: z.object({
+            orderId: z.string(),
+            reason: z.string(),
+          }),
+          contextSchema: z.object({
+            actorId: z.string(),
+            permissions: z.array(z.string()),
+          }),
+          execute: async ({ orderId, reason }, { context }) => {
+            expectTypeOf(context.actorId).toEqualTypeOf<string>();
+            expectTypeOf(context.permissions).toEqualTypeOf<string[]>();
+            return { orderId, reason, actorId: context.actorId };
+          },
+        }),
+        {
+          tags: ["billing", "dangerous"],
+          metadata: {
+            owner: "payments-team",
+          },
+        },
+      );
 
-      aiSdkTool({
-        description: "Test",
-        inputSchema: z.object({ value: z.string() }),
-        // @ts-expect-error - use VoltAgent observability/OpenTelemetry instead
-        experimental_telemetry: { isEnabled: false },
-        execute: async ({ value }) => ({ result: value }),
+      const agent = new Agent({
+        name: "Support",
+        instructions: "Test",
+        model: mockModel,
+        tools: {
+          refundCustomer,
+        },
       });
+
+      expectTypeOf(agent).toMatchTypeOf<Agent>();
     });
   });
 
@@ -616,6 +645,9 @@ describe("Agent Type System", () => {
           responseBody: true,
         },
         experimental_download: async (downloads) => downloads.map(() => null),
+        toolsContext: {
+          lookup_order: {},
+        },
         onStart: async () => {},
         onStepStart: async () => {},
         onLanguageModelCallStart: async () => {},
@@ -633,7 +665,7 @@ describe("Agent Type System", () => {
       expectTypeOf(result).toMatchTypeOf<GenerateTextResultWithContext>();
     });
 
-    it("should reject VoltAgent-owned AI SDK context and telemetry fields", () => {
+    it("should accept toolsContext and reject VoltAgent-owned runtime/telemetry fields", () => {
       const runtimeContextOptions: GenerateTextOptions = {
         // @ts-expect-error - use `voltagent.context` instead
         runtimeContext: {
@@ -642,8 +674,9 @@ describe("Agent Type System", () => {
       };
 
       const toolsContextOptions: GenerateTextOptions = {
-        // @ts-expect-error - use VoltAgent tool context APIs instead
-        toolsContext: {},
+        toolsContext: {
+          lookup_order: {},
+        },
       };
 
       const telemetryOptions: GenerateTextOptions = {

packages/core/src/agent/agent.spec.ts

@@ -1608,7 +1608,7 @@ Use pandas and summarize findings.`.split("\n"),
       expect(startContext.conversationId).toBe("runtime-conv");
     });
 
-    it("should pass AI SDK v7 generateText options, strip VoltAgent-owned fields, and compose managed callbacks", async () => {
+    it("should pass AI SDK v7 generateText options, strip VoltAgent-owned telemetry/runtime fields, and compose managed callbacks", async () => {
       const hookOnStepEnd = vi.fn();
       const userOnStepEnd = vi.fn();
       const userOnEnd = vi.fn();
@@ -1691,7 +1691,11 @@ Use pandas and summarize findings.`.split("\n"),
       expect(callArgs.telemetry).toBeUndefined();
       expect(callArgs.experimental_telemetry).toBeUndefined();
       expect(callArgs.runtimeContext).toBeUndefined();
-      expect(callArgs.toolsContext).toBeUndefined();
+      expect(callArgs.toolsContext).toEqual({
+        lookup_order: {
+          requestId: "tool-request-1",
+        },
+      });
       expect(callArgs.include).toEqual({
         requestBody: true,
         requestMessages: true,