Undeprecate client tool APIs for SDK/platform use cases

[threepointone]

Motivation

Closes #981.

The client tool APIs (createToolsFromClientSchemas, clientTools, AITool, extractClientToolSchemas, and the tools option on useAgentChat) were deprecated in favour of server-side tool() definitions. However, this breaks legitimate use cases for SDKs and platforms where the tool surface is determined dynamically by the embedding application at runtime — the server does not know which tools exist at deploy time.

The server-side tool() pattern is the right default for most apps (full Zod type safety, simpler code), but deprecating the only mechanism for dynamic tool registration was too aggressive.

What changed

Package code (packages/ai-chat/src/)

No breaking changes. No signature changes. All 218 tests pass.

index.ts

• Removed @deprecated tags from ClientToolSchema, clientTools on OnChatMessageOptions, and createToolsFromClientSchemas()
• Removed runtime warnDeprecated calls
• Removed now-unused private warnDeprecated helper and _deprecationWarnings set
• Updated JSDoc with "For most apps / For SDKs and platforms" guidance pattern

react.tsx

• Removed @deprecated tags from AITool, ClientToolSchema, extractClientToolSchemas(), and tools on UseAgentChatOptions
• Removed runtime warnDeprecated calls for these APIs
• Bugfix: Inlined the detectToolsRequiringConfirmation logic inside useAgentChat to stop emitting a spurious deprecation warning when users pass tools (the non-deprecated option). The detection logic is identical — tools without execute are treated as requiring confirmation — but the console.warn no longer fires unless users explicitly call the deprecated function or pass the deprecated toolsRequiringConfirmation option.
• Updated JSDoc with the same guidance pattern

New example (examples/dynamic-tools/)

A full-stack example demonstrating the SDK/platform pattern:

• Server: Generic agent using createToolsFromClientSchemas(options?.clientTools) — no tools defined at deploy time
• Client: Defines 4 browser-context tools with a sidebar to toggle them on/off, simulating an SDK where third-party developers register tools at runtime
• Follows all example conventions (Kumo, agents-ui, wrangler.jsonc, etc.)

Docs

• docs/chat-agents.md — Added tools option to useAgentChat options table (was missing), added "Dynamic Client Tools (SDK/Platform Pattern)" subsection with code examples, linked new example
• docs/migration-to-ai-sdk-v6.md — Reframed section 3 as "server-side tools (recommended)" with a new "Dynamic client tools" subsection. Trimmed deprecated table to only actually-deprecated APIs. Added "Not deprecated" callout. Updated checklist.

Cloudflare docs (separate repo, separate PR needed)

• src/content/docs/agents/api-reference/chat-agents.mdx in cloudflare/cloudflare-docs — Removed createToolsFromClientSchemas(), extractClientToolSchemas(), and tools option from deprecated table. Added "Not deprecated" note.

Notes for reviewers

1. No breaking changes — all APIs have identical signatures and behavior. The only runtime difference is fewer console.warn calls.
2. The detectToolsRequiringConfirmation inlining (react.tsx ~line 422) is the only non-trivial code change. The logic is identical to the original function, just without the deprecation warning wrapper. The original function is still exported and still deprecated for direct callers.
3. Still-deprecated APIs: toolsRequiringConfirmation, experimental_automaticToolResolution, addToolResult, detectToolsRequiringConfirmation — these are unchanged.
4. Guidance strategy: Instead of deprecation warnings, we steer users via JSDoc ("For most apps… / For SDKs and platforms…") and examples. The ai-chat and playground examples already use the server-side pattern. The new dynamic-tools example is the dedicated reference for the client-defined pattern.
5. The cloudflare-docs change is in a separate repo and will need a separate PR.

Verification

• npm run build ✅
• npm run check ✅ (44 projects typecheck, formatting clean, exports valid)
• npm run test ✅ (24 test files, 218 tests pass)

[changeset-bot]

🦋 Changeset detected

Latest commit: ef7e933

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@cloudflare/ai-chat	Patch

Not sure what this means? Click here to learn what changesets are.

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

[pkg-pr-new]

Open in StackBlitz

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

npm i https://pkg.pr.new/cloudflare/agents/@cloudflare/ai-chat@982

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

npm i https://pkg.pr.new/cloudflare/agents/hono-agents@982

commit: ef7e933