add client-defined tools and prepareSendMessagesRequest options by whoiskatrin · Pull Request #729 · cloudflare/agents

whoiskatrin · 2025-12-10T14:03:37Z

Fix client-side tool execution and message duplication

Add support for client-defined tools via useAgentChat with automatic and manual (human-in-the-loop) execution modes
Fix duplicate assistant messages when client-side tools execute by sending CF_AGENT_TOOL_RESULT to server as source of truth
Improve message ID synchronization between client and server by matching on toolCallId when IDs differ
Add toolsRequiringConfirmation option for human-in-the-loop workflows
Exclude originating connection from CF_AGENT_CHAT_MESSAGES broadcasts to prevent message conflicts

changeset-bot · 2025-12-10T14:03:40Z

🦋 Changeset detected

Latest commit: 2f2edf6

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

This PR includes changesets to release 1 package

Name	Type
agents	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 · 2025-12-10T14:05:13Z

Open in StackBlitz

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

commit: 2f2edf6

claude · 2025-12-10T14:07:38Z

Claude Code Review

Summary

This PR adds client-side tool execution with automatic/manual modes and fixes duplicate message issues. The implementation is generally solid with comprehensive tests.

Issues Found

1. Race condition in _applyToolResult (ai-chat-agent.ts:1108-1114)

The retry loop uses a hardcoded 10-attempt limit with 100ms delays (1 second total). If the message is not persisted within 1 second, the tool result is lost silently:

for (let attempt = 0; attempt < 10; attempt++) {
  message = this._findMessageByToolCallId(toolCallId);
  if (message) break;
  await new Promise((resolve) => setTimeout(resolve, 100));
}

This is fragile - under load or with slow database operations, tool results can be dropped. Consider:

Increase timeout or make it configurable
Add warning log with the attempt count when it succeeds after retries
Consider throwing an error instead of returning false to make failures visible

2. Potential memory leak in clientToolResults state (ai-react.tsx:590-592)

const [clientToolResults, setClientToolResults] = useState<
  Map<string, unknown>
>(new Map());

This Map grows indefinitely - every tool execution adds an entry but nothing ever removes old ones. In long conversations with many tool calls, this could accumulate significant memory. The state appears to be used for tracking but never cleaned up.

3. Missing validation in createToolsFromClientSchemas (ai-chat-agent.ts:78-86)

The function warns about duplicate tool names but still processes them:

if (seenNames.has(t.name)) {
  console.warn(`Duplicate tool name "${t.name}" found...`);
}

The later definition silently overwrites the earlier one. Consider either:

Throwing an error for duplicates (safer)
Or skip the duplicate instead of overwriting (preserve first definition)

4. autoContinueAfterToolResult dependency issue (ai-react.tsx:734-740)

The autoContinueAfterToolResult is in the useEffect dependency array but is referenced inside a deeply nested async closure. If the value changes between tool execution start and the server message send, stale values could be used. Consider capturing it at the start of the effect.

5. Test timeout values inconsistency

client-tool-duplicate-message.test.ts:208: Uses 800ms timeout for auto-continue test
client-tools-broadcast.test.ts:36,101: Uses 2000ms timeout
Comment says "wait 500ms" but test waits 800ms

These magic numbers should be constants with documented rationale.

Testing

Excellent test coverage including:

Message deduplication via toolCallId
Auto-continuation behavior
OpenAI metadata stripping
Broadcast exclusion
Empty reasoning part filtering

Tests are thorough but would benefit from testing the race condition edge cases in _applyToolResult.

This update documents two new features added in PR #729: 1. **clientTools option**: Allows clients to dynamically register tools that are sent to the Agent with each request. This enables embeddable chat widgets and multi-tenant applications where different clients need different tool capabilities. 2. **prepareSendMessagesRequest callback**: Provides advanced control over request customization, allowing developers to add dynamic context, custom headers, and other request modifications before sending messages to the Agent. Key additions: - Updated UseAgentChatOptions type signature to include new options - Added comprehensive examples showing clientTools usage with tool execution handlers - Added example demonstrating prepareSendMessagesRequest for dynamic context - Documented TypeScript types: ClientTool, JSONSchemaType, PrepareSendMessagesRequestOptions, PrepareSendMessagesRequestResult - Explained use cases for client-defined tools (embeddable widgets, multi-tenant apps, dynamic tool registration) - Clarified that both options can be combined for hybrid client/server tool capabilities Synced from: cloudflare/agents PR #729 cloudflare/agents#729 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Document new client-defined tools feature from cloudflare/agents#729: - Add comprehensive guide for client-defined tools - Update API reference with new types and functions - Document useAgentChat tools parameter - Document prepareSendMessagesRequest callback - Document createToolsFromClientSchemas function Related to: cloudflare/agents#729 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

…nd trigger

mattzcarey · 2025-12-11T10:41:07Z

+  /** Human-readable description of what the tool does */
+  description?: string;
+  /** JSON Schema defining the tool's input parameters */
+  parameters?: Record<string, unknown>;


nit: naming here. Can we not build this type from ai sdk tools omitting execute

mattzcarey · 2025-12-11T10:42:43Z

+ * Supports common JSON Schema properties with an index signature
+ * for extension properties like $ref, format, minimum, maximum, etc.
+ */
+export type JSONSchemaType = {


there are so many different specs for json schema. MCP standardise on 2020-12. you can use https://www.npmjs.com/package/json-schema-typed as a type lib for this.

mattzcarey · 2025-12-11T10:43:29Z

+  /**
+   * @deprecated Use `parameters` instead. Will be removed in a future version.
+   */
  inputSchema?: unknown;


intereste on this change and why we are vendoring this type ourselves not using ai sdk.

mattzcarey · 2025-12-11T10:43:54Z

+export type ClientToolSchema = {
+  /** Unique name for the tool */
+  name: string;
+  /** Human-readable description of what the tool does */
+  description?: string;
+  /** JSON Schema defining the tool's input parameters */
+  parameters?: Record<string, unknown>;
+};


looks like a type not a schema? and same as above...

yes yes, fixing this, my oversight

mattzcarey · 2025-12-11T10:45:15Z

+function toParametersRecord(
+  params: JSONSchemaType | unknown | undefined
+): Record<string, unknown> | undefined {
+  if (params === undefined || params === null) {
+    return undefined;
+  }
+  // JSONSchemaType and plain objects are compatible with Record<string, unknown>
+  if (typeof params === "object") {
+    return params as Record<string, unknown>;
+  }
+  // Primitive values shouldn't be used as parameters, but handle gracefully
+  return undefined;
+}


technically a boolean is a valid json schema. You want to use the Interface object on the JSONSchema type here to restrict the type to something which will go over wire. this shouldnt be necessary.

mattzcarey

tentative approval. I think there is a bit of cleaning that can be done with types.

This PR adds comprehensive documentation for the new client-defined tools feature introduced in cloudflare/agents#729. Key additions: - New API reference page for client-defined tools - Detailed explanation of client-side tool registration - Examples of browser-specific tool actions (alerts, DOM manipulation) - Server-side integration using createToolsFromClientSchemas() - Advanced usage patterns with custom request data - API reference for AITool, ClientToolSchema, and OnChatMessageOptions types - Best practices for security, error handling, and TypeScript usage The documentation follows the Diátaxis framework, providing both reference material and practical examples for implementing dynamic tool registration in embeddable chat widgets and multi-tenant applications. Related to: cloudflare/agents#729 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Adds comprehensive documentation for the new client-defined tools feature introduced in PR #729, which allows clients to dynamically register tools that execute in the browser. Changes: - Added Client-Defined Tools section to agents-api.mdx - Documented AITool type with execute functions - Added client-side tool definition examples - Documented createToolsFromClientSchemas() server-side utility - Added prepareSendMessagesRequest option documentation - Updated useAgentChat type definition with new options This documentation covers: - How to define tools on the client with execute functions - Automatic schema extraction and transmission to server - Server-side handling of client tool schemas - Advanced custom request data patterns Related to cloudflare/agents#729

…uest Sync documentation from cloudflare/agents PR #729: - Add comprehensive client-defined tools guide - Update AIChatAgent API to document options parameter - Add createToolsFromClientSchemas helper documentation - Update human-in-the-loop guide with new tool format - Document prepareSendMessagesRequest option - Add useAgentChat tools and customization examples Related PR: cloudflare/agents#729

… messages

This update documents the new client-defined tools feature that enables dynamic tool registration from browser clients, essential for embeddable chat widgets and multi-tenant applications. Changes: - Add client-defined tools guide with comprehensive examples - Update useAgentChat API reference with new options: - tools: Client-side tool definitions with execute functions - toolsRequiringConfirmation: Human-in-the-loop tool approval - prepareSendMessagesRequest: Custom request data/headers - Document AIChatAgent server-side API updates: - OnChatMessageOptions type with clientTools parameter - createToolsFromClientSchemas() helper function - ClientToolSchema and AITool type definitions The new guide covers: - Client-side tool definition with JSON Schema and execute functions - Server-side tool handling with createToolsFromClientSchemas() - Human-in-the-loop workflows with toolsRequiringConfirmation - Custom request data with prepareSendMessagesRequest - Server-only tools without client execute functions - Best practices for security and performance Related to cloudflare/agents#729 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

… update message handling to merge tool results into existing assistant messages

… handling

…tions This documentation update corresponds to PR #729 in cloudflare/agents. Key changes: - Updated human-in-the-loop guide with new client-side tool definitions using JSON Schema - Added documentation for autoContinueAfterToolResult option in useAgentChat - Updated server-side tool processing to properly handle tool results - Added comprehensive examples for client-side tools with human-in-the-loop workflows - Updated agents-api documentation with new useAgentChat options: - tools: Client-side tools with optional execute functions - toolsRequiringConfirmation: List of tools requiring human approval - autoContinueAfterToolResult: Automatic continuation after tool execution Related PR: cloudflare/agents#729

Add client-defined tools and options for message requests.

Document new features from cloudflare/agents PR #729: - Add client-side tools support via useAgentChat - Add toolsRequiringConfirmation option for human-in-the-loop - Add autoContinueAfterToolResult for seamless tool execution - Update human-in-the-loop guide with new patterns - Update API reference with detailed tool configuration examples Synced from: cloudflare/agents#729 Generated with Claude Code https://claude.com/claude-code Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

add client-defined tools and prepareSendMessagesRequest options

129e6b6

agents-git-bot Bot mentioned this pull request Dec 10, 2025

Sync docs for PR 729: add client-defined tools and prepareSendMessagesRequest options cloudflare/cloudflare-docs#27039

Closed

fix client tools execution

68071e6

whoiskatrin added 2 commits December 10, 2025 15:19

minor nits

e6e76cf

some claude review feedback

bc2e874

whoiskatrin requested review from ghostwriternr and mattzcarey December 10, 2025 15:42

whoiskatrin added 2 commits December 10, 2025 15:43

refactor

fca9db3

Refactor useAgentChat

f99d9b7

whoiskatrin added 4 commits December 10, 2025 15:59

more nits

63f9996

take a different approach

3620f91

cleanup after the refactor

800bbd9

fix param convertion

a526cc0

improve tool execution handling in useAgentChat

44e9333

whoiskatrin mentioned this pull request Dec 10, 2025

Support for client-defined tools in useAgentChat #727

Closed

fix request body structure in useAgentChat to include id, messages, a…

6cdec1f

…nd trigger

mattzcarey reviewed Dec 11, 2025

View reviewed changes

mattzcarey approved these changes Dec 11, 2025

View reviewed changes

whoiskatrin added 5 commits December 11, 2025 11:26

fix types

461306e

fix msg duplication

44e9f40

fix the duplication issue in client tools

7bbbb1b

fix types

0faeb1a

fix types

365394d

remove example from the git

ab2b997

Send tool results to server as source of truth

afb31c1

remove automatic message sending after tool results

6cae864

cleanup the tests

8585098

whoiskatrin force-pushed the add-client-tools branch from d09d42a to 8585098 Compare December 12, 2025 09:35

fix OpenAI item ID stripping to prevent duplicate errors in persisted…

dc0736b

… messages

whoiskatrin force-pushed the add-client-tools branch from ada8304 to dc0736b Compare December 12, 2025 11:28

minor nits

939c0fc

add server-side auto-continuation after tool results for improved UX;…

b8026ae

… update message handling to merge tool results into existing assistant messages

update useAgentChat to include autoContinueAfterToolResult in message…

27f8a8e

… handling

whoiskatrin added 3 commits December 12, 2025 15:06

fix for non human in the loop tools

88ed2e2

update the tests

7d1aede

Update slow-jobs-boil.md with new options

2f2edf6

Add client-defined tools and options for message requests.

whoiskatrin merged commit 79843bd into main Dec 12, 2025
5 checks passed

whoiskatrin deleted the add-client-tools branch December 12, 2025 18:16

github-actions Bot mentioned this pull request Dec 12, 2025

Version Packages #730

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

add client-defined tools and prepareSendMessagesRequest options#729

add client-defined tools and prepareSendMessagesRequest options#729
whoiskatrin merged 30 commits into
mainfrom
add-client-tools

whoiskatrin commented Dec 10, 2025 •

edited

Loading

Uh oh!

changeset-bot Bot commented Dec 10, 2025 •

edited

Loading

Uh oh!

pkg-pr-new Bot commented Dec 10, 2025 •

edited

Loading

Uh oh!

claude Bot commented Dec 10, 2025 •

edited

Loading

Uh oh!

mattzcarey Dec 11, 2025

Uh oh!

mattzcarey Dec 11, 2025

Uh oh!

mattzcarey Dec 11, 2025

Uh oh!

mattzcarey Dec 11, 2025

Uh oh!

whoiskatrin Dec 11, 2025

Uh oh!

mattzcarey Dec 11, 2025

Uh oh!

whoiskatrin Dec 11, 2025

Uh oh!

mattzcarey left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

whoiskatrin commented Dec 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Fix client-side tool execution and message duplication

Uh oh!

changeset-bot Bot commented Dec 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

pkg-pr-new Bot commented Dec 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

claude Bot commented Dec 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Claude Code Review

Summary

Issues Found

Testing

Uh oh!

mattzcarey Dec 11, 2025

Choose a reason for hiding this comment

Uh oh!

mattzcarey Dec 11, 2025

Choose a reason for hiding this comment

Uh oh!

mattzcarey Dec 11, 2025

Choose a reason for hiding this comment

Uh oh!

mattzcarey Dec 11, 2025

Choose a reason for hiding this comment

Uh oh!

whoiskatrin Dec 11, 2025

Choose a reason for hiding this comment

Uh oh!

mattzcarey Dec 11, 2025

Choose a reason for hiding this comment

Uh oh!

whoiskatrin Dec 11, 2025

Choose a reason for hiding this comment

Uh oh!

mattzcarey left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

whoiskatrin commented Dec 10, 2025 •

edited

Loading

changeset-bot Bot commented Dec 10, 2025 •

edited

Loading

pkg-pr-new Bot commented Dec 10, 2025 •

edited

Loading

claude Bot commented Dec 10, 2025 •

edited

Loading