diff --git a/src/content/docs/agents/guides/migrate-to-ai-sdk-v6.mdx b/src/content/docs/agents/guides/migrate-to-ai-sdk-v6.mdx new file mode 100644 index 000000000000000..51613a039a7396e --- /dev/null +++ b/src/content/docs/agents/guides/migrate-to-ai-sdk-v6.mdx @@ -0,0 +1,462 @@ +--- +pcx_content_type: navigation +title: Migrate to AI SDK v6 +sidebar: + order: 10 +description: Upgrade your Agents SDK project from AI SDK v5 to v6 with this comprehensive migration guide covering breaking changes, new features, and step-by-step instructions +--- + +import { PackageManagers, TypeScriptExample } from "~/components"; + +## Overview + +This guide helps you migrate your existing code from **AI SDK v5.x** to **AI SDK v6.x** (beta) when using the Agents SDK. + +AI SDK v6 introduces new capabilities like tool approval, but **migrating from v5 to v6 should be straightforward with minimal code changes** for most users. + +:::note + +AI SDK v6 is currently in beta. APIs may still change. For production projects, consider waiting for the stable release. + +::: + +## Installation + +Update your dependencies to use the beta versions: + + + +For the Agents SDK, update `package.json`: + + + +```json +{ + "dependencies": { + "ai": "^6.0.0-beta", + "@ai-sdk/openai": "^3.0.0-beta", + "@ai-sdk/react": "^3.0.0-beta" + } +} +``` + + + +## Breaking Changes + +### Unified Tool Pattern (Client-Side Tools) + +The Agents SDK now uses AI SDK v6's unified tool pattern. The old `AITool`, `toolsRequiringConfirmation`, and `experimental_automaticToolResolution` options are deprecated. + +#### Before (v5 - Deprecated) + + + +```typescript +// Client: Define client-side tools with AITool type +const clientTools: Record = { + getLocation: { + description: "Get user location", + parameters: { type: "object", properties: {} }, + execute: async () => navigator.geolocation.getCurrentPosition(...) + }, + askConfirmation: { + description: "Ask user for confirmation", + parameters: { type: "object", properties: { message: { type: "string" } } } + // No execute = requires confirmation + } +}; + +useAgentChat({ + agent, + tools: clientTools, + experimental_automaticToolResolution: true, + toolsRequiringConfirmation: ["askConfirmation"] +}); + +// Server: Convert client schemas to tools +const response = await this.onChatMessage(onFinish, { clientTools }); +const tools = { + ...serverTools, + ...createToolsFromClientSchemas(clientTools) +}; +``` + + + +#### After (v6 - Recommended) + + + +```typescript +// Server: Define ALL tools on the server +const tools = { + // Server-executed tool + getWeather: tool({ + description: "Get weather for a city", + inputSchema: z.object({ city: z.string() }), + execute: async ({ city }) => fetchWeather(city) + }), + + // Client-executed tool (no execute = client handles via onToolCall) + getLocation: tool({ + description: "Get user location from browser", + inputSchema: z.object({}) + // No execute function + }), + + // Tool requiring approval (dynamic based on input) + processPayment: tool({ + description: "Process a payment", + inputSchema: z.object({ amount: z.number() }), + needsApproval: async ({ amount }) => amount > 100, + execute: async ({ amount }) => charge(amount) + }) +}; + +// Client: Handle client-side tools via onToolCall callback +useAgentChat({ + agent, + onToolCall: async ({ toolCall, addToolOutput }) => { + if (toolCall.toolName === "getLocation") { + const position = await new Promise((resolve, reject) => { + navigator.geolocation.getCurrentPosition(resolve, reject); + }); + addToolOutput({ + toolCallId: toolCall.toolCallId, + output: { + lat: position.coords.latitude, + lng: position.coords.longitude + } + }); + } + } +}); +``` + + + +**Key benefits of the new pattern:** + +- **Server-defined tools**: All tools are defined in one place on the server +- **Dynamic approval**: Use `needsApproval` to conditionally require user confirmation +- **Cleaner client code**: Use `onToolCall` callback instead of managing tool configs +- **Type safety**: Full TypeScript support with proper tool typing + +### convertToModelMessages() is now async + +The `convertToModelMessages()` function is now asynchronous. Update all calls to await the result. + +#### Before (v5) + + + +```typescript +import { convertToModelMessages } from "ai"; + +const result = streamText({ + messages: convertToModelMessages(this.messages), + model: openai("gpt-4o") +}); +``` + + + +#### After (v6) + + + +```typescript +import { convertToModelMessages } from "ai"; + +const result = streamText({ + messages: await convertToModelMessages(this.messages), + model: openai("gpt-4o") +}); +``` + + + +### CoreMessage type removed + +The `CoreMessage` type has been removed. Use `ModelMessage` instead, and replace `convertToCoreMessages()` with `convertToModelMessages()`. + +#### Before (v5) + + + +```typescript +import { convertToCoreMessages, type CoreMessage } from "ai"; + +const coreMessages: CoreMessage[] = convertToCoreMessages(messages); +``` + + + +#### After (v6) + + + +```typescript +import { convertToModelMessages, type ModelMessage } from "ai"; + +const modelMessages: ModelMessage[] = await convertToModelMessages(messages); +``` + + + +### isToolUIPart and getToolName behavior changed + +In v5, `isToolUIPart` and `getToolName` only checked static tool parts. In v6, they now check **both static and dynamic tool parts**. + +If you need the v5 behavior (static-only checks), use the new functions: + +- `isToolUIPart` (v5) → `isStaticToolUIPart` (v6) +- `getToolName` (v5) → `getStaticToolName` (v6) + +**For most Agents SDK users, no changes are needed** since the v6 behavior (checking both static and dynamic) is typically what you want. + +### generateObject mode option removed + +The `mode` option for `generateObject` has been removed. Remove any `mode: "json"` or similar options. + +#### Before (v5) + + + +```typescript +const result = await generateObject({ + mode: "json", + model, + schema, + prompt +}); +``` + + + +#### After (v6) + + + +```typescript +const result = await generateObject({ + model, + schema, + prompt +}); +``` + + + +## Deprecations + +### Agents SDK Deprecated APIs + +The following Agents SDK APIs are deprecated in favor of the unified tool pattern: + +| Deprecated | Replacement | +| -------------------------------------- | ------------------------------------------------ | +| `AITool` type | Use AI SDK's `tool()` function on server | +| `extractClientToolSchemas()` | Define tools on server, no client schemas needed | +| `createToolsFromClientSchemas()` | Define tools on server with `tool()` | +| `toolsRequiringConfirmation` option | Use `needsApproval` on server tools | +| `experimental_automaticToolResolution` | Use `onToolCall` callback | +| `tools` option in `useAgentChat` | Use `onToolCall` for client-side execution | +| `addToolResult()` | Use `addToolOutput()` | + +### generateObject and streamObject are deprecated + +While still functional in v6, these functions are deprecated. The recommended approach is to use `generateText`/`streamText` with the `Output.object()` helper: + +#### Before (v5) + + + +```typescript +import { generateObject } from "ai"; + +const { object } = await generateObject({ + model: openai("gpt-4"), + schema: z.object({ name: z.string() }), + prompt: "Generate a name" +}); +``` + + + +#### After (v6 recommended) + + + +```typescript +import { generateText, Output, stepCountIs } from "ai"; + +const { output } = await generateText({ + model: openai("gpt-4"), + output: Output.object({ + schema: z.object({ name: z.string() }) + }), + stopWhen: stepCountIs(2), + prompt: "Generate a name" +}); +``` + + + +:::note + +When using structured output with `generateText`, you must configure multiple steps with `stopWhen` because generating the structured output is itself a step. + +::: + +## New Features in v6 + +### Agent Abstraction + +AI SDK v6 introduces a new `Agent` interface and `ToolLoopAgent` class for building agents with full control over execution flow: + + + +```typescript +import { ToolLoopAgent } from "ai"; + +const weatherAgent = new ToolLoopAgent({ + model: openai("gpt-4o"), + instructions: "You are a helpful weather assistant.", + tools: { + weather: weatherTool + } +}); + +const result = await weatherAgent.generate({ + prompt: "What is the weather in San Francisco?" +}); +``` + + + +### Tool Execution Approval + +Request user confirmation before executing tools with the `needsApproval` option: + + + +```typescript +import { tool } from "ai"; + +const paymentTool = tool({ + description: "Process a payment", + inputSchema: z.object({ + amount: z.number(), + recipient: z.string() + }), + needsApproval: async ({ amount }) => amount > 1000, + execute: async ({ amount, recipient }) => { + return await processPayment(amount, recipient); + } +}); +``` + + + +### Structured Output with Tool Calling + +You can now generate structured output alongside multi-step tool calling: + + + +```typescript +import { ToolLoopAgent, Output, tool } from "ai"; + +const agent = new ToolLoopAgent({ + model: openai("gpt-4o"), + tools: { weather: weatherTool }, + output: Output.object({ + schema: z.object({ + summary: z.string(), + temperature: z.number(), + recommendation: z.string() + }) + }) +}); +``` + + + +### Reranking Support + +AI SDK v6 adds native support for reranking documents: + + + +```typescript +import { rerank } from "ai"; +import { cohere } from "@ai-sdk/cohere"; + +const { ranking } = await rerank({ + model: cohere.reranking("rerank-v3.5"), + documents: ["sunny day", "rainy afternoon", "snowy night"], + query: "talk about rain", + topN: 2 +}); +``` + + + +## Third-Party Provider Compatibility + +Some third-party AI SDK providers may not yet support v6. If you encounter type errors with providers like `workers-ai-provider`, you may need to: + +1. Wait for the provider to release a v6-compatible version +2. Use a type assertion as a temporary workaround: + + + +```typescript +// Temporary workaround for incompatible providers +model: workersai("model-name") as unknown as Parameters< + typeof streamText +>[0]["model"]; +``` + + + +## Migration Checklist + +### Package Updates + +- Update `ai` package to `^6.0.0-beta` +- Update `@ai-sdk/react` to `^3.0.0-beta` +- Update `@ai-sdk/openai` (and other providers) to `^3.0.0-beta` + +### AI SDK Changes + +- Add `await` to all `convertToModelMessages()` calls +- Replace `CoreMessage` with `ModelMessage` +- Replace `convertToCoreMessages()` with `convertToModelMessages()` +- Remove `mode` option from `generateObject` calls + +### Agents SDK Tool Pattern Migration + +- Move client tool definitions to server using `tool()` from "ai" +- Replace `tools` option with `onToolCall` callback in `useAgentChat` +- Replace `toolsRequiringConfirmation` with `needsApproval` on server tools +- Replace `experimental_automaticToolResolution` with `onToolCall` +- Replace `addToolResult()` calls with `addToolOutput()` +- Remove `createToolsFromClientSchemas()` usage + +### Verification + +- Run type check: `npm run typecheck` +- Run tests: `npm test` + +## Related resources + +- [Official AI SDK v6 migration guide](https://ai-sdk.dev/docs/migration-guides/migration-guide-6-0) +- [AI SDK v6 announcement](https://ai-sdk.dev/docs/announcing-ai-sdk-6-beta) +- [AI SDK documentation](https://sdk.vercel.ai/docs) +- [Agents SDK GitHub repository](https://github.com/cloudflare/agents) diff --git a/src/content/docs/agents/reference/index.mdx b/src/content/docs/agents/reference/index.mdx new file mode 100644 index 000000000000000..6745aca65e7abd7 --- /dev/null +++ b/src/content/docs/agents/reference/index.mdx @@ -0,0 +1,12 @@ +--- +title: Reference +pcx_content_type: navigation +sidebar: + order: 5 +--- + +import { DirectoryListing } from "~/components" + +Reference documentation for the Agents SDK, including migration guides: + + diff --git a/src/content/docs/agents/reference/migrate-to-ai-sdk-v6.mdx b/src/content/docs/agents/reference/migrate-to-ai-sdk-v6.mdx new file mode 100644 index 000000000000000..480d05050bb2a82 --- /dev/null +++ b/src/content/docs/agents/reference/migrate-to-ai-sdk-v6.mdx @@ -0,0 +1,432 @@ +--- +title: Migrate to AI SDK v6 +pcx_content_type: how-to +sidebar: + order: 1 +description: Learn how to migrate your Agents SDK code from AI SDK v5 to v6 +--- + +import { PackageManagers, TypeScriptExample } from "~/components"; + +This guide helps you migrate your existing code from **AI SDK v5.x** to **AI SDK v6.x** when using the Agents SDK. + +## Overview + +AI SDK v6 introduces new capabilities like tool approval, but **migrating from v5 to v6 should be straightforward with minimal code changes** for most users. + +## Installation + +Update your dependencies to use the latest versions: + + + +## Breaking changes + +### Unified tool pattern (client-side tools) + +The Agents SDK now uses AI SDK v6's unified tool pattern. The old `AITool`, `toolsRequiringConfirmation`, and `experimental_automaticToolResolution` options are deprecated. + +#### Before (v5 - Deprecated) + + + +```ts +// Client: Define client-side tools with AITool type +const clientTools: Record = { + getLocation: { + description: "Get user location", + parameters: { type: "object", properties: {} }, + execute: async () => navigator.geolocation.getCurrentPosition(...) + }, + askConfirmation: { + description: "Ask user for confirmation", + parameters: { type: "object", properties: { message: { type: "string" } } } + // No execute = requires confirmation + } +}; + +useAgentChat({ + agent, + tools: clientTools, + experimental_automaticToolResolution: true, + toolsRequiringConfirmation: ["askConfirmation"] +}); + +// Server: Convert client schemas to tools +const response = await this.onChatMessage(onFinish, { clientTools }); +const tools = { + ...serverTools, + ...createToolsFromClientSchemas(clientTools) +}; +``` + + + +#### After (v6 - Recommended) + + + +```ts +// Server: Define ALL tools on the server +const tools = { + // Server-executed tool + getWeather: tool({ + description: "Get weather for a city", + inputSchema: z.object({ city: z.string() }), + execute: async ({ city }) => fetchWeather(city) + }), + + // Client-executed tool (no execute = client handles via onToolCall) + getLocation: tool({ + description: "Get user location from browser", + inputSchema: z.object({}) + // No execute function + }), + + // Tool requiring approval (dynamic based on input) + processPayment: tool({ + description: "Process a payment", + inputSchema: z.object({ amount: z.number() }), + needsApproval: async ({ amount }) => amount > 100, + execute: async ({ amount }) => charge(amount) + }) +}; + +// Client: Handle client-side tools via onToolCall callback +useAgentChat({ + agent, + onToolCall: async ({ toolCall, addToolOutput }) => { + if (toolCall.toolName === "getLocation") { + const position = await new Promise((resolve, reject) => { + navigator.geolocation.getCurrentPosition(resolve, reject); + }); + addToolOutput({ + toolCallId: toolCall.toolCallId, + output: { + lat: position.coords.latitude, + lng: position.coords.longitude + } + }); + } + } +}); +``` + + + +**Key benefits of the new pattern:** + +- **Server-defined tools**: All tools are defined in one place on the server +- **Dynamic approval**: Use `needsApproval` to conditionally require user confirmation +- **Cleaner client code**: Use `onToolCall` callback instead of managing tool configs +- **Type safety**: Full TypeScript support with proper tool typing + +### `convertToModelMessages()` is now async + +The `convertToModelMessages()` function is now asynchronous. Update all calls to await the result. + +#### Before (v5) + + + +```ts +import { convertToModelMessages } from "ai"; + +const result = streamText({ + messages: convertToModelMessages(this.messages), + model: openai("gpt-4o") +}); +``` + + + +#### After (v6) + + + +```ts +import { convertToModelMessages } from "ai"; + +const result = streamText({ + messages: await convertToModelMessages(this.messages), + model: openai("gpt-4o") +}); +``` + + + +### `CoreMessage` type removed + +The `CoreMessage` type has been removed. Use `ModelMessage` instead, and replace `convertToCoreMessages()` with `convertToModelMessages()`. + +#### Before (v5) + + + +```ts +import { convertToCoreMessages, type CoreMessage } from "ai"; + +const coreMessages: CoreMessage[] = convertToCoreMessages(messages); +``` + + + +#### After (v6) + + + +```ts +import { convertToModelMessages, type ModelMessage } from "ai"; + +const modelMessages: ModelMessage[] = await convertToModelMessages(messages); +``` + + + +### `isToolUIPart` and `getToolName` behavior changed + +In v5, `isToolUIPart` and `getToolName` only checked static tool parts. In v6, they now check **both static and dynamic tool parts**. + +If you need the v5 behavior (static-only checks), use the new functions: + +- `isToolUIPart` (v5) → `isStaticToolUIPart` (v6) +- `getToolName` (v5) → `getStaticToolName` (v6) + +**For most Agents SDK users, no changes are needed** since the v6 behavior (checking both static and dynamic) is typically what you want. + +### `generateObject` mode option removed + +The `mode` option for `generateObject` has been removed. Remove any `mode: "json"` or similar options. + +#### Before (v5) + + + +```ts +const result = await generateObject({ + mode: "json", + model, + schema, + prompt +}); +``` + + + +#### After (v6) + + + +```ts +const result = await generateObject({ + model, + schema, + prompt +}); +``` + + + +## Deprecations + +### Agents SDK deprecated APIs + +The following Agents SDK APIs are deprecated in favor of the unified tool pattern: + +| Deprecated | Replacement | +| -------------------------------------- | ------------------------------------------------ | +| `AITool` type | Use AI SDK `tool()` function on server | +| `extractClientToolSchemas()` | Define tools on server, no client schemas needed | +| `createToolsFromClientSchemas()` | Define tools on server with `tool()` | +| `toolsRequiringConfirmation` option | Use `needsApproval` on server tools | +| `experimental_automaticToolResolution` | Use `onToolCall` callback | +| `tools` option in `useAgentChat` | Use `onToolCall` for client-side execution | +| `addToolResult()` | Use `addToolOutput()` | + +### `generateObject` and `streamObject` are deprecated + +While still functional in v6, these functions are deprecated. The recommended approach is to use `generateText`/`streamText` with the `Output.object()` helper: + +#### Before (v5) + + + +```ts +import { generateObject } from "ai"; + +const { object } = await generateObject({ + model: openai("gpt-4"), + schema: z.object({ name: z.string() }), + prompt: "Generate a name" +}); +``` + + + +#### After (v6 recommended) + + + +```ts +import { generateText, Output, stepCountIs } from "ai"; + +const { output } = await generateText({ + model: openai("gpt-4"), + output: Output.object({ + schema: z.object({ name: z.string() }) + }), + stopWhen: stepCountIs(2), + prompt: "Generate a name" +}); +``` + + + +:::note + +When using structured output with `generateText`, you must configure multiple steps with `stopWhen` because generating the structured output is itself a step. + +::: + +## New features in v6 + +### Agent abstraction + +AI SDK v6 introduces a new `Agent` interface and `ToolLoopAgent` class for building agents with full control over execution flow: + + + +```ts +import { ToolLoopAgent } from "ai"; + +const weatherAgent = new ToolLoopAgent({ + model: openai("gpt-4o"), + instructions: "You are a helpful weather assistant.", + tools: { + weather: weatherTool + } +}); + +const result = await weatherAgent.generate({ + prompt: "What is the weather in San Francisco?" +}); +``` + + + +### Tool execution approval + +Request user confirmation before executing tools with the `needsApproval` option: + + + +```ts +import { tool } from "ai"; + +const paymentTool = tool({ + description: "Process a payment", + inputSchema: z.object({ + amount: z.number(), + recipient: z.string() + }), + needsApproval: async ({ amount }) => amount > 1000, + execute: async ({ amount, recipient }) => { + return await processPayment(amount, recipient); + } +}); +``` + + + +### Structured output with tool calling + +You can now generate structured output alongside multi-step tool calling: + + + +```ts +import { ToolLoopAgent, Output, tool } from "ai"; + +const agent = new ToolLoopAgent({ + model: openai("gpt-4o"), + tools: { weather: weatherTool }, + output: Output.object({ + schema: z.object({ + summary: z.string(), + temperature: z.number(), + recommendation: z.string() + }) + }) +}); +``` + + + +### Reranking support + +AI SDK v6 adds native support for reranking documents: + + + +```ts +import { rerank } from "ai"; +import { cohere } from "@ai-sdk/cohere"; + +const { ranking } = await rerank({ + model: cohere.reranking("rerank-v3.5"), + documents: ["sunny day", "rainy afternoon", "snowy night"], + query: "talk about rain", + topN: 2 +}); +``` + + + +## Third-party provider compatibility + +Some third-party AI SDK providers may not yet support v6. If you encounter type errors with providers like `workers-ai-provider`, you may need to: + +1. Wait for the provider to release a v6-compatible version +2. Use a type assertion as a temporary workaround: + + + +```ts +// Temporary workaround for incompatible providers +model: workersai("model-name") as unknown as Parameters< + typeof streamText +>[0]["model"]; +``` + + + +## Migration checklist + +### Package updates + +- Update `ai` package to `^6.0.0` +- Update `@ai-sdk/react` to `^3.0.0` +- Update `@ai-sdk/openai` (and other providers) to `^3.0.0` + +### AI SDK changes + +- Add `await` to all `convertToModelMessages()` calls +- Replace `CoreMessage` with `ModelMessage` +- Replace `convertToCoreMessages()` with `convertToModelMessages()` +- Remove `mode` option from `generateObject` calls + +### Agents SDK tool pattern migration + +- Move client tool definitions to server using `tool()` from `"ai"` +- Replace `tools` option with `onToolCall` callback in `useAgentChat` +- Replace `toolsRequiringConfirmation` with `needsApproval` on server tools +- Replace `experimental_automaticToolResolution` with `onToolCall` +- Replace `addToolResult()` calls with `addToolOutput()` +- Remove `createToolsFromClientSchemas()` usage + +## More resources + +- [Official AI SDK v6 migration guide](https://ai-sdk.dev/docs/migration-guides/migration-guide-6-0) +- [AI SDK v6 announcement](https://vercel.com/blog/ai-sdk-6) +- [AI SDK documentation](https://sdk.vercel.ai/docs) +- [Agents SDK GitHub repository](https://github.com/cloudflare/agents/issues)