migration to AI SDK v6

[whoiskatrin]

Migrate Agents SDK to AI SDK v6 beta with unified tool pattern.

Changes
AI SDK v6 Updates

• Updated ai to ^6.0.0-beta, @ai-sdk/react and providers to ^3.0.0-beta
• Added await to all convertToModelMessages() calls (now async in v6)
• Removed deprecated mode option from generateObject calls

Unified Tool Pattern
Simplified client-side tool handling by adopting AI SDK v6's native pattern.

Before:

// Client: Define tools with custom AITool type
const tools = {
  getLocation: {
    parameters: { type: "object" },
    execute: async () => navigator.geolocation.getCurrentPosition(...)
  }
};
useAgentChat({
  tools,
  experimental_automaticToolResolution: true,
  toolsRequiringConfirmation: ["dangerousTool"]
});
// Server: Convert client schemas
const allTools = {
  ...serverTools,
  ...createToolsFromClientSchemas(clientTools)
};

After:

// Server: Define ALL tools in one place
const tools = {
  getLocation: tool({
    description: "Get user location",
    inputSchema: z.object({})
    // No execute = client handles
  }),
  payment: tool({
    inputSchema: z.object({ amount: z.number() }),
    needsApproval: ({ amount }) => amount > 100,  // Dynamic approval
    execute: async ({ amount }) => charge(amount)
  })
};
// Client: Handle via callback
useAgentChat({
  onToolCall: async ({ toolCall, addToolOutput }) => {
    if (toolCall.toolName === 'getLocation') {
      const pos = await getGeolocation();
      addToolOutput({ toolCallId: toolCall.toolCallId, output: pos });
    }
  }
});

New APIs

• onToolCall callback in useAgentChat for client-side tool execution
• addToolOutput() function for providing tool results

Deprecated (still functional)

• AITool type, extractClientToolSchemas(), createToolsFromClientSchemas()
• tools, toolsRequiringConfirmation, experimental_automaticToolResolution options
• addToolResult() → use addToolOutput()

Docs

• Added docs/migration-to-ai-sdk-v6.md with migration guide and checklist

[changeset-bot]

⚠️ No Changeset found

Latest commit: 205160d

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[claude]

Claude Code Review

Migration Quality: Strong
The v6 migration is well-executed with good backward compatibility.

Issues Found:

1. Race condition in onToolCall effect (ai-react.tsx:840-899)

   • Effect does not include useChatHelpers.addToolResult in dependencies but uses it
   • Can cause stale closure bugs if the function identity changes
   • Fix: Add to dependency array or use useCallback

2. Missing test coverage for new onToolCall pattern

   • No tests verify the new onToolCall callback works correctly
   • Existing tests only cover deprecated tools option
   • Recommendation: Add tests for the primary migration path

3. Type safety gap in addToolOutput (ai-react.tsx:1358-1371)

   • toolName parameter is optional but used as required (via empty string fallback)
   • Could cause issues with tool result tracking
   • Consider: Make toolName required or handle undefined explicitly

Architecture:

• Unified tool pattern is cleaner than v5 approach
• Deprecation strategy preserves backward compatibility
• Migration guide is comprehensive

Minor observations:

• 362-line migration doc is thorough but dense
• No examples yet use onToolCall (only deprecated patterns remain)
• Consider adding a working example to docs/

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/cloudflare/agents@733

commit: 205160d

[threepointone]

I've rebased and approved this with a couple of comments. I don't recommend landing this until the sdk release is out, because the way we now do peer deps will break people if it's not a semver version string. We can land and release it the minute we know ai sdk is going out.

[threepointone]

nice

[threepointone]

this probably needs a test