You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: .changeset/voltagent-3-next.md
+47-4Lines changed: 47 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -107,7 +107,7 @@ pnpm add zod@^4
107
107
108
108
### Agent usage
109
109
110
-
The object-style call shape is the preferred API. AI SDK generation options stay at the top level, while VoltAgent runtime concerns live under `voltagent`.
110
+
The object-style call shape is the preferred API. VoltAgent 3 derives agent generation options from AI SDK v7 `generateText` and `streamText`, so AI SDK settings stay at the top level while VoltAgent runtime concerns live under `voltagent`.
111
111
112
112
```ts
113
113
const result =awaitagent.generateText({
@@ -126,6 +126,33 @@ const result = await agent.generateText({
126
126
});
127
127
```
128
128
129
+
AI SDK v7 options such as `timeout`, `headers`, `include`, `activeTools`, `toolOrder`, `experimental_download`, `onChunk`, and stream lifecycle callbacks can be used directly on VoltAgent calls:
130
+
131
+
```ts
132
+
const result =awaitagent.streamText({
133
+
prompt: "Write a release note for this changelog",
134
+
timeout: {
135
+
totalMs: 30_000,
136
+
chunkMs: 5_000,
137
+
},
138
+
include: {
139
+
rawChunks: true,
140
+
},
141
+
onChunk: async ({ chunk }) => {
142
+
console.log(chunk.type);
143
+
},
144
+
voltagent: {
145
+
context: {
146
+
requestId: "req-789",
147
+
},
148
+
},
149
+
});
150
+
```
151
+
152
+
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.
153
+
154
+
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.
155
+
129
156
The same shape works for streaming:
130
157
131
158
```ts
@@ -151,7 +178,7 @@ for await (const part of result.stream) {
151
178
152
179
### Tool usage
153
180
154
-
VoltAgent now accepts AI SDK-style tool sets directly, so projects can use `tool()`without wrapping every tool in `createTool`.
181
+
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.
`createTool` remains available for existing tools and for codebases that prefer the VoltAgent-native helper.
224
+
Register the tool under the canonical name the model should call:
225
+
226
+
```ts
227
+
const agent =newAgent({
228
+
name: "Support Agent",
229
+
model,
230
+
tools: {
231
+
refundCustomer,
232
+
},
233
+
});
234
+
```
235
+
236
+
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.
237
+
238
+
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.
239
+
240
+
`createTool` is now a legacy compatibility helper for existing class-style tools. New code should use `tool()`.
Copy file name to clipboardExpand all lines: docs/ai-sdk-first-vnext-plan.md
+260-1Lines changed: 260 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -838,6 +838,263 @@ Exit criteria:
838
838
- Users can follow the migration guide from VoltAgent 2.x/AI SDK 6 to vNext/AI SDK 7.
839
839
- Website build succeeds.
840
840
841
+
#### 9.6.1 Follow-up Audit: Remaining v2 Usage in Examples and website/docs
842
+
843
+
Audit scope:
844
+
845
+
-`examples`
846
+
-`website/docs`
847
+
- Exclude historical `CHANGELOG.md` files unless they are copied into live docs.
848
+
849
+
Current finding: the first migration pass updated the core API docs and migration guide, but many live examples and topic docs still show v2-era usage. These should be cleaned before promoting the 3.x next release beyond early validation.
850
+
851
+
1. Replace preferred tool examples from `createTool` to AI SDK-style `tool()`.
852
+
853
+
Update live docs and examples so new code imports `tool` from `@voltagent/core`, uses `inputSchema`, and registers tools as a `ToolSet` object:
854
+
855
+
```ts
856
+
import { Agent, tool } from"@voltagent/core";
857
+
import { z } from"zod";
858
+
859
+
const tools = {
860
+
getWeather: tool({
861
+
description: "Get the weather for a city",
862
+
inputSchema: z.object({
863
+
city: z.string(),
864
+
}),
865
+
execute: async ({ city }) => ({ city, temperature: 72 }),
866
+
voltagent: {
867
+
tags: ["weather"],
868
+
},
869
+
}),
870
+
};
871
+
872
+
const agent =newAgent({
873
+
name: "assistant",
874
+
model: "openai/gpt-4o-mini",
875
+
tools,
876
+
});
877
+
```
878
+
879
+
Keep `createTool` only in migration/deprecation sections that explicitly explain legacy compatibility.
880
+
881
+
Priority docs:
882
+
-`website/docs/agents/overview.md`
883
+
-`website/docs/agents/tools.md`
884
+
-`website/docs/tools/overview.md`
885
+
-`website/docs/tools/tool-routing.md`
886
+
-`website/docs/agents/context.md`
887
+
-`website/docs/agents/hooks.md`
888
+
-`website/docs/agents/cancellation.md`
889
+
-`website/docs/agents/dynamic-agents.md`
890
+
-`website/docs/agents/plan-agent.md`
891
+
-`website/docs/agents/mcp/mcp-server.md`
892
+
-`website/docs/integrations/nextjs.md`
893
+
-`website/docs/ui/assistant-ui.md`
894
+
-`website/docs/ui/copilotkit.md`
895
+
-`website/docs/workspaces/overview.md`
896
+
-`website/docs/workflows/steps/and-agent.md`
897
+
-`website/docs/workflows/steps/and-then.md`
898
+
-`website/docs/observability/logging.md`
899
+
900
+
Priority examples:
901
+
-`examples/with-tools`
902
+
-`examples/with-tool-routing`
903
+
-`examples/with-client-side-tools`
904
+
-`examples/next-js-chatbot-starter-template`
905
+
-`examples/with-nextjs`
906
+
-`examples/with-nextjs-resumable-stream`
907
+
-`examples/with-assistant-ui`
908
+
-`examples/with-copilotkit`
909
+
-`examples/with-mcp-server`
910
+
-`examples/with-mcp-elicitation`
911
+
-`examples/with-a2a-server`
912
+
-`examples/with-playwright`
913
+
-`examples/with-whatsapp`
914
+
-`examples/with-ad-creator`
915
+
-`examples/github-repo-analyzer`
916
+
-`examples/github-star-stories`
917
+
-`examples/with-voltagent-exporter`
918
+
-`examples/with-langfuse`
919
+
-`examples/with-voltagent-actions`
920
+
921
+
2. Update old tool field names in docs and examples.
922
+
923
+
Replace v2-style tool fields in preferred examples:
924
+
-`parameters` -> `inputSchema`
925
+
-`name` inside the tool definition -> object key in the `tools` object
926
+
- VoltAgent-only tool metadata -> `voltagent`
927
+
- tool execution context access from `execute` -> AI SDK execution options or `voltagent.hooks`
928
+
929
+
Do not rewrite workflow step schemas that intentionally use `inputSchema`; those are not tool API leftovers.
930
+
931
+
Code/API follow-up found during audit:
932
+
-`ToolRoutingConfig.pool` and `ToolRoutingConfig.expose` currently accept arrays of class-style tools/toolkits/provider tools, but not named AI SDK `ToolSet` records. Do not convert tool-routing docs to `tool()` + object syntax until the type/runtime support exists.
933
+
-`createToolkit` can type-accept AI SDK tool objects, but array registration cannot infer names from a `ToolSet` key. Keep toolkit docs marked as compatibility-only until toolkit APIs support named AI SDK tools directly.
934
+
935
+
3. Update agent docs for AI SDK compatibility boundaries.
936
+
937
+
Add or expand a short section in agent docs explaining:
938
+
- AI SDK generation settings mostly pass through.
939
+
- VoltAgent owns `runtimeContext`, `toolsContext`, `telemetry`, `experimental_telemetry`, `maxRetries`, `abortSignal`, lifecycle callback composition, model resolution, messages, tools, and structured output wiring.
940
+
- Use VoltAgent `context`, `memory`, `voltagent` runtime options, hooks, and OpenTelemetry instead of AI SDK `runtimeContext`, `toolsContext`, or `telemetry`.
-`website/docs/agents/tools.md` should link back to the agent-level ownership section.
948
+
949
+
4. Normalize memory examples to the 3.x preferred envelope.
950
+
951
+
Preferred new-code shape:
952
+
953
+
```ts
954
+
awaitagent.generateText("Continue the conversation", {
955
+
memory: {
956
+
userId: "user-123",
957
+
conversationId: "thread-456",
958
+
options: {
959
+
contextLimit: 10,
960
+
},
961
+
},
962
+
});
963
+
```
964
+
965
+
Update user-facing examples that still show top-level `userId`, `conversationId`, `contextLimit`, `semanticMemory`, `conversationPersistence`, or `messageMetadataPersistence`. Keep top-level fields only in migration sections, compatibility notes, REST API schema examples, or UI request payload examples where the HTTP contract still uses those names.
-`examples/with-client-side-tools/package.json` uses legacy `@voltagent/vercel-ai` and `@voltagent/vercel-ui`. These can be removed immediately because the example does not import them.
- Keep workspace package ranges that still point at local `2.0.0-next.0` packages until the changeset version step bumps those packages. Moving them to `^3.0.0-next.0` before versioning breaks local `pnpm install` because the workspace package versions do not satisfy the range yet.
1047
+
-`examples/with-playwright/tsconfig.json` still sets `"module": "CommonJS"`.
1048
+
1049
+
7. Review legacy provider documentation.
1050
+
1051
+
`website/docs/getting-started/providers-models.md` still contains an older native-provider migration section. Keep it only as a clearly labeled historical migration note and make the current 3.x recommendation direct AI SDK providers/model strings.
1052
+
1053
+
`website/docs/community/contributing.md` mentions deprecated provider packages; verify the wording still matches the 3.x package policy.
1054
+
1055
+
8. Telemetry docs cleanup.
1056
+
1057
+
Ensure live docs do not imply AI SDK `telemetry` can be passed through `Agent` or `tool()`. The correct 3.x guidance is:
1058
+
- Use VoltAgent OpenTelemetry/observability for Agent calls and VoltAgent-managed tools.
1059
+
- Use AI SDK telemetry only when calling AI SDK directly outside VoltAgent.
1060
+
- Provider-defined tools are passed through and may have provider-owned observability semantics.
0 commit comments