RFC: Make VoltAgent vNext an ai-sdk-first outer framework

[Diluka]

RFC: Make VoltAgent vNext an ai-sdk-first outer framework

Summary

VoltAgent should become an outer framework around ai-sdk instead of a hidden abstraction layer. The primary API should
reuse ai-sdk names, options, semantics, and types. VoltAgent-specific features must live under a voltagent namespace
and provide orchestration, workflows, memory, observability, plugins, and engineering integrations.

Motivation

Current VoltAgent has already moved toward native ai-sdk models, but the core API still wraps ai-sdk calls through
agent.generateText(input, options) and agent.streamText(input, options). This creates semantic drift, duplicated
types, and blocked access to newer ai-sdk capabilities.

Source evidence:

• Agent.generateText(input, options) is positional, not ai-sdk object-style.
• BaseGenerationOptions is hand-written and extends Partial<CallSettings>.
• maxSteps, stop, context, UsageInfo, Tool, and LLMProvider create parallel concepts.
• @voltagent/core currently peers ai:^6.0.0, while current ai-sdk source is v7.
• @voltagent/core depends directly on many provider packages.

Goals

• Align public generation APIs with ai-sdk v7.
• Reuse ai-sdk types directly.
• Preserve VoltAgent value: workflows, memory, guardrails, observability, server adapters, MCP/A2A.
• Provide a low-cost escape hatch to raw ai-sdk calls.
• Provide compat and codemod migration.

Non-Goals

• Reimplement ai-sdk retry, stream parsing, tool execution, or provider registry.
• Add new features to legacy APIs.
• Hide provider-specific ai-sdk capabilities.

Proposed API

const agent = new Agent({
  id: "assistant",
  instructions: "Helpful assistant",
  model: openai("gpt-4o-mini"),
});

const result = await agent.generateText({
  prompt: "Explain TypeScript",
  temperature: 0.2,
  stopWhen: isStepCount(3),
  voltagent: {
    memory: { userId: "u1", conversationId: "c1" },
    observability: { traceName: "explain-typescript" },
  },
});

Tools use ai-sdk directly:

const tools = {
  get_weather: tool({
    description: "Get weather",
    inputSchema: z.object({ location: z.string() }),
    execute: async ({ location }) => ({ location, temp: 72 }),
  }),
};

Structured output uses ai-sdk Output:

const result = await agent.generateText({
  prompt: "Create recipe",
  output: Output.object({ schema: recipeSchema }),
});

Escape hatch:

await agent.run({ prompt: "Hello" }, async ({ ai, voltagent }) => {
  const result = await generateText({
    ...ai,
    timeout: { totalMs: 30_000 },
  });
  voltagent.attachResult(result);
  return result;
});

Architecture

@voltagent/core

Owns lifecycle, plugins, configuration, registries. Must not own provider wrappers or ai-sdk reimplementations.

@voltagent/ai-sdk-bridge

Thin layer for ai-sdk v7 type aliases, option composition, version checks, model resolution helpers, callback
composition, and escape hatch context.

@voltagent/workflows

Owns workflow DSL, checkpoints, suspension, restart, workflow memory state.

@voltagent/observability

Owns OpenTelemetry, VoltOps, exporters, and ai-sdk telemetry bridge.

@voltagent/compat

Owns legacy signatures and migration shims only.

Deprecations

N+1:

• Add new object-style API.
• Warn on positional generateText/streamText.
• Warn on maxSteps, stop, top-level context/userId/conversationId.
• Warn on createTool as primary API.
• Warn on generateObject/streamObject.

N+2:

• Remove legacy overloads from core.
• Move legacy wrappers to @voltagent/compat.
• Remove LLMProvider and provider response types from core exports.
• Remove provider hard dependencies from core.

Codemod

Rules:

• agent.generateText(input, opts) -> agent.generateText({ prompt/messages: input, ...opts })

• maxSteps: n -> stopWhen: isStepCount(n)

• stop: "x" -> stopSequences: ["x"]

• generateObject(input, schema, opts) -> generateText({ prompt/messages: input, output:
  Output.object({ schema }), ...opts })

• Best-effort createTool({ parameters }) -> tool({ inputSchema })

Validation

• Golden behavior tests against raw ai-sdk for text, stream, tools, structured output, callbacks, abort, retry, and
  telemetry.

• E2E matrix for Node, Edge, OpenAI, Anthropic, Google, Groq, Gateway, OpenAI-compatible.

• Bundle and install-size benchmarks.

• Performance benchmarks for no-extension path, memory path, observability path.

Risks

• ai-sdk v7 migration can break typings.
• ToolSet migration can break toolkit users.
• Retry defaults changing can affect cost and reliability.
• Stream result identity changes can break UI integrations.
• Provider registry removal can surprise string-model users.

Rollback

• Keep @voltagent/compat.
• Feature-flag new API in N+1.
• Keep old default retry/step behavior in compat.
• Pin ai-sdk v7 minor during beta/rc.

---

It is recommended to adjust the solution based on the actual situation, and it is not necessary to force compatibility with the previous major version.

[omeraplak]

Thanks for opening this RFC. I’m very much aligned with the direction of making VoltAgent vNext more AI SDK-first.

After looking through the current framework surface, I think the key principle should be:

VoltAgent should use AI SDK primitives as the public/default mental model, while preserving VoltAgent’s orchestration layer on top.

In other words, model, messages / prompt, tools, output, stopWhen, providerOptions, etc. should feel native to AI SDK users. But VoltAgent should continue to own the parts that make it more than a thin AI SDK wrapper: memory, subagents, workflows, observability, guardrails, middleware, tool routing, server integrations, evals, and VoltOps.

A plan that feels safe to me:

1. Define the vNext Agent call shape

   • Support object-style calls such as agent.generateText({ prompt, model, tools, output, ... }).
   • Keep AI SDK-compatible fields at the top level.
   • Move VoltAgent-specific runtime concerns into a clear namespace, for example:
     • voltagent.memory
     • voltagent.userId
     • voltagent.conversationId
     • voltagent.guardrails
     • voltagent.middleware
     • voltagent.toolRouting
     • voltagent.feedback
     • voltagent.parentSpan

2. Keep compatibility during the transition

   • Preserve the current agent.generateText(input, options) and agent.streamText(input, options) signatures as compatibility wrappers.
   • Keep generateObject / streamObject as deprecated wrappers around generateText / streamText with output.
   • Add codemods and migration docs before removing anything.

3. Create a feature parity test matrix before refactoring
   These should be protected explicitly:

   • tools, toolkits, provider tools, client-side tools, approval, toModelOutput
   • tool routing and embedding-based tool search
   • Memory V2, semantic memory, working memory, conversation steps
   • subagents, delegate_task, parallel handoff, bail, stream metadata
   • input/output guardrails, streaming redaction, middleware retries
   • model fallback, retry hooks, dynamic model resolution
   • OpenTelemetry spans, VoltOps sync, feedback, live eval payloads
   • workflows, andAgent, suspend/resume/replay
   • server-core, Hono, MCP, A2A, AG-UI, resumable streams

4. Decouple provider dependencies carefully
   Removing provider packages from core makes sense, but we should preserve the current provider/model router experience somehow, either as an optional package or lazy provider registry. Otherwise users lose a very convenient onboarding path.

5. Refactor internally only after parity is locked
   Once compatibility tests are in place, we can simplify the internal Agent execution path around AI SDK primitives without accidentally regressing framework features.

My main concern is not the AI SDK-first direction itself. I think that’s the right direction. The risk is accidentally flattening VoltAgent into a pass-through wrapper and losing the orchestration features that make it useful as a framework.

So I’d frame vNext as:

AI SDK-native at the boundary, VoltAgent-native in orchestration.

[lzj960515]

I agree with the overall direction, but I think the most important part is defining the boundary clearly.

The AI SDK gives VoltAgent a very strong foundation, but it is still mostly a set of low-level, composable primitives for model calls, tools, structured output, streaming, provider options, usage, etc. It is not a complete out-of-the-box application framework for agent products.

So I would frame the boundary like this:

• AI SDK should own the model invocation layer: model, messages / prompt, tools, output, stopWhen, streaming events, usage objects, provider options, abort/retry behavior, and provider-specific capabilities.
• VoltAgent should own the agent application layer: conversation management, memory, user/session/conversation state, subagents, delegation, workflows, guardrails, observability, server adapters, persistence, evals, and VoltOps integration.

In other words, VoltAgent should not re-invent AI SDK concepts when the AI SDK already exposes them well. If VoltAgent only renames or wraps something without adding framework-level value, it should probably expose the AI SDK shape directly instead.

But VoltAgent also should not become just a thin pass-through wrapper around generateText / streamText. The value of VoltAgent is everything around the model call: how agents are composed, how conversations continue, how memory is stored and retrieved, how subagents are coordinated, how workflows are resumed, how traces and evals are captured, and how this runs in production.

A useful rule of thumb might be:

If it is about talking to the model, prefer the AI SDK primitive.
If it is about running an agent system over time, it belongs in VoltAgent.

I would also suggest keeping an explicit escape hatch where advanced users can pass through raw AI SDK options or even access the composed AI SDK call inputs. This would make future AI SDK changes easier to adopt without requiring VoltAgent to re-model every new capability immediately.

So overall, I think AI SDK-native at the boundary, VoltAgent-native in orchestration is the right long-term direction.

[omeraplak]

Thanks again for the detailed RFC and the follow-up framing around the boundary between AI SDK and VoltAgent.

I pushed the first VoltAgent 3 prerelease work to the next branch:

• Branch: https://github.com/VoltAgent/voltagent/tree/next
• Prerelease workflow: https://github.com/VoltAgent/voltagent/actions/runs/28985879639

This is intentionally going through the next channel first, so we can validate the API shape and package/runtime changes before publishing a stable 3.x release on latest.

What landed in this first pass:

• Node.js >=22 runtime requirement
• ESM-only package exports
• AI SDK v7 dependency alignment
• object-style agent.generateText({ ... }) / agent.streamText({ ... }) calls
• AI SDK generation options at the top level, with VoltAgent runtime concerns under voltagent
• isStepCount, result.stream, and output: Output.object(...) style APIs
• AI SDK-style tool() support directly in VoltAgent
• a voltagent namespace on tools for VoltAgent metadata like name, purpose, tags, hooks, and custom metadata
• native AI SDK toolApproval forwarding for per-request approval policy
• voltagent.needsApproval kept only as static metadata / compatibility for existing VoltAgent approval and tool-policy flows
• compatibility wrappers kept for createTool, positional calls, generateObject, and streamObject, with docs guiding new code toward the AI SDK-first shape
• migration guide and release notes for the 2.x -> 3.x path
• prerelease workflow hardening so next publish requires Changesets prerelease mode with tag next

What I intentionally did not force into this first prerelease:

• removing every legacy compatibility wrapper
• splitting a separate @voltagent/compat package
• implementing the raw agent.run(..., ({ ai, voltagent }) => ...) escape hatch yet
• fully removing the existing model/provider routing experience

My current read is that this gets us most of the way toward the RFC principle without flattening VoltAgent into a thin AI SDK wrapper: AI SDK-native at the model-call boundary, VoltAgent-native in orchestration, memory, observability, tools, workflows, server integrations, and policies.

I would especially like your thoughts on the tool() design:

const refundCustomer = tool({
  description: "Refund a customer order",
  inputSchema: z.object({
    orderId: z.string(),
    reason: z.string(),
  }),
  execute: async ({ orderId, reason }) => issueRefund(orderId, reason),
  voltagent: {
    name: "refundCustomer",
    purpose: "Issue customer refunds",
  },
});

await agent.streamText({
  prompt: "Refund order order_123 if it is eligible",
  tools: { refundCustomer },
  toolApproval: {
    refundCustomer: "user-approval",
  },
});

Does this feel like the right boundary to you: native AI SDK tool shape by default, VoltAgent-specific metadata isolated under voltagent, and approval policy controlled with call-level toolApproval for new flows? Also curious whether you think createTool should stay as a long-term convenience API or only remain as migration compatibility.

[lzj960515]

Thanks for the update. The direction looks good overall, especially keeping AI SDK options at the call boundary and putting VoltAgent runtime concerns under voltagent.

On the tool() design, I think there is one boundary detail worth being very explicit about.

The example uses tool() from VoltAgent, not the raw AI SDK tool() from ai, because native AI SDK tools do not know about a voltagent field. That is fine as a convenience layer, but I think raw AI SDK tools should remain truly first-class.

For example, AI SDK v7 supports tool runtime context directly with contextSchema and toolsContext:

import { tool } from "ai";

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 ({ city }, { context }) => {
    return fetchWeather(city, {
      apiKey: context.apiKey,
      unit: context.defaultUnit,
    });
  },
});

await agent.generateText({
  prompt: "What is the weather in San Francisco?",
  tools: { weather },
  toolsContext: {
    weather: {
      apiKey: process.env.WEATHER_API_KEY!,
      defaultUnit: "fahrenheit",
    },
  },
});

I would expect this to work without importing tool from VoltAgent and without VoltAgent needing to mirror every AI SDK tool option. This is important because whenever AI SDK adds a new tool option, VoltAgent users should be able to use it immediately instead of waiting for VoltAgent to copy the option into its own tool API.

So I would separate the concepts:

1. Raw AI SDK tool definition: owned by AI SDK. VoltAgent should pass it through as-is.
2. VoltAgent metadata: optional, additive, and not sent to the model provider.

The metadata is useful, but mostly for framework/business concerns: tool catalogs, routing, observability tags, access policy, audit hooks, UI/API exposure, etc. For example:

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,
      });
    },
  }),
  {
    tags: ["billing", "dangerous", "customer-support"],
    metadata: {
      owner: "payments-team",
      riskLevel: "high",
    },
    hooks: {
      onStart: async ({ args }) => {
        auditLog("refund_started", args);
      },
      onEnd: async ({ output }) => {
        auditLog("refund_finished", output);
      },
    },
  },
);

await agent.streamText({
  prompt: "Refund order order_123 if it is eligible",
  tools: { refundCustomer },
  toolsContext: {
    refundCustomer: {
      actorId: currentUser.id,
      permissions: currentUser.permissions,
    },
  },
  toolApproval: {
    refundCustomer: "user-approval",
  },
});

The important part here is that contextSchema, execute, and toolsContext stay native AI SDK concepts. VoltAgent only adds metadata around the tool.

Because of that, I wonder if the primary API should be something like withVoltAgentMetadata(aiTool, metadata) rather than encouraging users to always import tool from @voltagent/core. A VoltAgent tool() helper can still exist as a convenience wrapper, but the docs should make it clear that users can also import tool directly from ai when they do not need VoltAgent metadata.

For createTool, my preference is to keep it as migration compatibility, not the long-term primary API. It uses VoltAgent-specific names like parameters and name, while the AI SDK direction is inputSchema and ToolSet object keys. Keeping both as first-class APIs may create more semantic drift over time.

So my recommendation would be:

• raw AI SDK tools must be first-class;
• AI SDK contextSchema / toolsContext should pass through directly;
• VoltAgent metadata should be optional and additive;
• createTool should remain as compatibility / convenience, but new docs should prefer AI SDK tool() plus optional VoltAgent metadata.

[Diluka]

I agree with this design (withVoltAgentMetadata); everything in the AI ​​SDK can be used directly in voltagent, and voltagent also provides a wrapper layer to extend the functionality of the AI ​​SDK.

[omeraplak]

Thanks for the detailed push on this. I agree with the boundary you described, and I updated the implementation in that direction.

What changed:

• Raw AI SDK tools are now treated as first-class tools in VoltAgent.
• Native AI SDK contextSchema stays on the tool definition.
• Call-level toolsContext is now passed through to AI SDK instead of being stripped.
• Added withVoltAgentMetadata(aiTool, metadata) so VoltAgent metadata can be attached out-of-band without changing the raw AI SDK tool definition or sending that metadata to the model provider.
• The VoltAgent tool() helper still exists as a convenience wrapper for inline voltagent metadata, but it no longer strips native AI SDK tool fields like contextSchema.
• createTool remains as compatibility / migration support rather than the preferred long-term API.

The intended usage now looks like this:

import { tool } from "ai";
import { Agent, withVoltAgentMetadata } from "@voltagent/core";
import { z } from "zod";

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",
    },
    hooks: {
      onStart: async ({ args }) => {
        auditLog("refund_started", args);
      },
      onEnd: async ({ output }) => {
        auditLog("refund_finished", output);
      },
    },
  },
);

const agent = new Agent({
  name: "Support Agent",
  instructions: "Help support agents with billing operations.",
  model,
  tools: {
    refundCustomer,
  },
});

await agent.streamText({
  prompt: "Refund order order_123 if it is eligible",
  toolsContext: {
    refundCustomer: {
      actorId: currentUser.id,
      permissions: currentUser.permissions,
    },
  },
  toolApproval: {
    refundCustomer: "user-approval",
  },
});

So the split is now:

• AI SDK owns the raw tool definition and native execution context (tool(), contextSchema, toolsContext, execute, etc.).
• VoltAgent metadata is optional and additive (withVoltAgentMetadata) for catalogs, routing, hooks, observability tags, API/UI exposure, and policy metadata.

I also updated the migration guide, tools docs, changeset, and added type/runtime coverage around this boundary. Validation is green for the relevant core tests and build.

[lzj960515]

This looks good to me. Thanks for iterating on this so quickly.

[Diluka]

The function name withVoltAgentMetadata is a little long. I hope a better api can be given at that time. I think this direction is good, taking ai-sdk as a first-class citizen.

For example, I hope that, like the relationship between nestjs and express, while providing enterprise-level application extensions for express, nestjs can also be perfectly compatible with the middleware of the express ecology. Even the middleware born before nestjs can be compatible.

[omeraplak]

Hey, quick update here.

We pushed the VoltAgent 3 prerelease to the next channel, including the latest AI SDK v7 tool compatibility work. The newest core package is available as @voltagent/core@3.0.0-next.1 under the next dist tag.

pnpm add @voltagent/core@next ai@^7 zod@^4

If your app uses other VoltAgent packages, please install those from the next channel too so all VoltAgent packages stay on the same prerelease line. For example:

pnpm add @voltagent/core@next @voltagent/server-hono@next @voltagent/logger@next ai@^7 zod@^4

Or, depending on what your app uses:

pnpm add @voltagent/postgres@next @voltagent/supabase@next @voltagent/voice@next

This includes the direction we discussed:

• raw AI SDK tools are treated as first-class tools
• AI SDK contextSchema and call-level toolsContext pass through directly
• VoltAgent-specific metadata is optional and additive via withVoltAgentMetadata
• VoltAgent metadata is kept out-of-band and is not sent to the model provider

Example:

import { tool } from "ai";
import { Agent, withVoltAgentMetadata } from "@voltagent/core";
import { z } from "zod";

const weather = withVoltAgentMetadata(
  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 ({ city }, { context }) => {
      return fetchWeather(city, {
        apiKey: context.apiKey,
        unit: context.defaultUnit,
      });
    },
  }),
  {
    tags: ["weather"],
    metadata: {
      owner: "support-team",
    },
  },
);

await agent.generateText({
  prompt: "What is the weather in San Francisco?",
  tools: { weather },
  toolsContext: {
    weather: {
      apiKey: process.env.WEATHER_API_KEY!,
      defaultUnit: "fahrenheit",
    },
  },
});

Would you be open to testing this from the next channel and sharing whether it covers the API boundary you had in mind? Based on that feedback, we can plan the final 3.x release path more confidently.

[lzj960515]

Okay, we'll give it a try next week.

[richardchen874-sys]

Making the outer framework ai-sdk-first is a meaningful architectural choice because it puts provider semantics, streaming, tools, and model config at the center instead of hiding them behind one vendor path.

One thing I would keep visible is provider capability metadata: tool-call support, usage reporting, reasoning fields, cache behavior, and streaming quirks. That saves a lot of pain when users plug in OpenAI-compatible providers.

I am testing an OpenAI-compatible multi-model API layer around official Chinese models, and framework-level provider capability mapping is a recurring need. Do you expect vNext users to bring their own providers, or mostly use curated defaults?

[Diluka]

@omeraplak Is it possible to access the raw data from the AI ​​SDK within any of the hooks?

Regardless of whether voltagent supports the corresponding hooks, I would like to register them directly using the ai-sdk hooks API pattern. If voltagent supports them, an additional wrapper layer can be applied; if not, they should be registered directly with the ai-sdk. The hook parameters must include the original ai-sdk parameters to ensure consistency with the ai-sdk API, while also maintaining compatibility with the ai-sdk API even when voltagent-specific parameters are present.

The core requirement is to use the ai-sdk's hooks system directly, without having to learn a separate set of APIs or wait for Voltagent to wrap or support them; this ensures immediate compatibility whenever the ai-sdk is updated.

---

@omeraplak I would like to clarify the core architectural requirement behind my previous comment.

AI SDK should be treated as the first-class API and the source of truth. VoltAgent should be an orchestration framework built on top of AI SDK, not an abstraction that replaces, narrows, or redefines the AI SDK API.

Full compatibility with the AI SDK API should be a prerequisite for extending VoltAgent.

This means that AI SDK APIs should remain available through VoltAgent with their original contracts, including:

• options and configuration;
• TypeScript types;
• lifecycle callbacks;
• callback event types and values;
• callback timing and ordering;
• callback error-handling semantics;
• runtime and tool context;
• provider-specific options;
• streaming behavior;
• result fields and semantics.

VoltAgent may orchestrate model calls and add capabilities such as agents, memory, guardrails, middleware, tracing, observability, retries, and fallbacks. However, these capabilities must be additive. They must not remove, replace, reinterpret, transform, or take ownership of existing AI SDK APIs.

There should not be a parallel VoltAgent lifecycle callback API that users must learn in addition to the AI SDK lifecycle callback API. The AI SDK lifecycle callback API should remain the single public lifecycle contract.

When an AI SDK lifecycle callback is used through VoltAgent, it should receive the original, unmodified event produced by AI SDK. VoltAgent should not replace that event with a VoltAgent-specific result, a transformed value, or a post-processed representation.

The original AI SDK callback semantics must also be preserved. Compatibility should include not only the callback name and TypeScript signature, but also its payload, lifecycle timing, invocation behavior, and error isolation.

VoltAgent-specific processing must not change the meaning or value of existing AI SDK fields. If VoltAgent adds information or behavior, it must do so without overwriting or redefining the AI SDK contract.

Forward compatibility is also essential. When AI SDK introduces a new option, lifecycle callback, event field, or other compatible API capability, it should become usable through VoltAgent without requiring VoltAgent to explicitly add it to an allowlist, wrap it, or publish a new release solely to expose it.

Users should be able to treat the AI SDK documentation as the authoritative documentation for model calls and lifecycle callbacks when working with VoltAgent. They should not need to wait for VoltAgent to adapt an AI SDK API before they can use it.

The central requirement is:

VoltAgent should extend and orchestrate AI SDK while preserving complete compatibility with the AI SDK API.

VoltAgent functionality should only be added when it can preserve that compatibility. It should never be implemented by replacing the AI SDK API with a VoltAgent-specific alternative or by exposing only a partially compatible subset.

I am intentionally not prescribing how VoltAgent should implement this internally. The request is about the public contract and expected behavior: AI SDK remains the first-class API, and VoltAgent remains a fully compatible orchestration layer on top of it.

[richardchen874-sys]

@Diluka Access to the raw AI SDK result matters because normalized hooks can hide returned-model IDs, provider usage, cache metadata, and fallback details. Our OpenAI-compatible layer keeps model, routing, usage, and cost telemetry visible across Chinese models. If that is the data you need from the hooks, I can provide free beta access so you can try the same workflow against a real multi-model endpoint and see whether the normalized fields are sufficient before depending on provider-specific payloads.