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

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.