Support for client-defined tools in useAgentChat

[alexanderjacobsen]

I'm building a service that lets users embed an AI chat widget into their websites, where each website can define its own client-side tools (e.g., showAlert, changeBackgroundColor,
navigateToPage).

Currently, tools must be defined server-side in onChatMessage. However, my use case requires each client to register different tools dynamically - the server doesn't know what tools a particular
website wants to expose until runtime.

Current limitation

useAgentChat creates its own transport internally and doesn't expose a way to send additional data (like tool definitions) with each chat request:

const customTransport = useMemo(() => ({
  sendMessages: async (options) => {
    return new DefaultChatTransport({
      api: agentUrlString,
      fetch: aiFetch
    }).sendMessages(options);
  },
  // No way to use prepareSendMessagesRequest here
}), [agentUrlString, aiFetch]);

The Vercel AI SDK's useChat supports this via prepareSendMessagesRequest on the transport, but useAgentChat doesn't expose it.

Proposed solution

One of these approaches would enable client-defined tools:

1. Expose prepareSendMessagesRequest in UseAgentChatOptions so clients can attach tool definitions to each request
2. Add a clientTools option to useAgentChat that automatically sends tool schemas to the server, similar to how body works in useChat
3. Document a pattern for registering tools via agent.send() on connection, which the server's onMessage can handle

[whoiskatrin]

@alexanderjacobsen yes, knew about this and it was on my todo list for a while! Will try to ship today

[whoiskatrin]

@alexanderjacobsen this should fix this issue and the other bug that you reported? #729

let me know what you think and how it works on your side

[alexanderjacobsen]

The combinedPrepare function at line 559 in ai-react.tsx only sets { clientTools } in the body, but when prepareSendMessagesRequest returns a body, the AI SDK uses it as the complete replacement,
not a merge. This means messages is never sent, causing:
Cannot read properties of undefined (reading 'map')
at autoTransformMessages

The fix should include the required fields:

if (clientToolSchemas) {
  body = { 
    id: prepareOptions.id,
    messages: prepareOptions.messages,
    trigger: prepareOptions.trigger,
    clientTools: clientToolSchemas 
  };
}

[whoiskatrin]

@alexanderjacobsen perfectly valid, i missed it, just added, once it builds you should be able to give it another go.

[alexanderjacobsen]

After client-side tool execution, I'm seeing duplicate tool UI elements.

Root cause:

1. Client executes tool and calls addToolResult() → local state updated to output-available
2. Server finishes and calls persistMessages() with its version (still input-available - server doesn't know client executed)
3. Server broadcasts CF_AGENT_CHAT_MESSAGES which calls setMessages(data.messages) at line 785 in ai-react.tsx
4. This replaces client messages with server's version, creating duplicates with different message IDs

Debug output (from iterating messages from useAgentChat):

  Tool parts: (3) [
    {key: 'URBJCCqwCeUZYJ19-2', state: 'output-available'},
    {key: 'assistant_1765449750318_0skp3xdpf-2', state: 'output-available'},
    {key: 'URBJCCqwCeUZYJ19-2', state: 'output-available'}
  ]

Note different message IDs - one from original stream, one from server broadcast.

Likely fix: persistMessages() (line 714) broadcasts to all connections including the originator. Should exclude the originating connection like line 262-268 does.

[whoiskatrin]

@alexanderjacobsen yes, filtered out, doesn't duplicate locally for me now

[alexanderjacobsen]

Client-side tool execution creates two separate assistant messages instead of updating one, causing OpenAI to reject requests with "Duplicate item found":

APICallError: Duplicate item found with id rs_0a7581aefb67f54200693aad4e0be88190b95bdba31783082e

Debug output (this.messages on second request):

this.messages count: 3
this.messages: [
  { role: "user", id: "G1yyXDEwe0MEo8o5", ... },
  {
    id: "assistant_1765453133333_jwecuct24",  // First message
    role: "assistant",
    parts: [{ type: "tool-slowOperation", state: "input-available", ... }]
  },
  {
    id: "DBZJDtigkmZFiyha",  // Second message - should have updated first
    role: "assistant",
    parts: [{ type: "tool-slowOperation", state: "output-available", ... }]
  }
]

Both messages contain the same OpenAI reasoning itemId, which gets rejected as duplicate input.

Root cause: When the tool result comes back, persistMessages creates a new assistant message instead of updating the existing one.

[whoiskatrin]

@alexanderjacobsen give it another go 🤗

[alexanderjacobsen]

Bug still present: Duplicate assistant messages accumulating in database

The merge fix helps but doesn't fully solve the duplication. The database accumulates duplicate messages during the tool call flow.

Timeline:

• First request: 1 message (user)
• Second request (tool result): 2 messages (user + assistant) ✓
• Third request ("Very nice!"): 5 messages - should be 3

Database contents on third request:

this.messages: [
  { role: "user", id: "cfmHb1UfC2rPkOwb" },  // Original request

  { id: "2fOQQfqYDCH8IAs1",  // Merged message (correct)
    parts: [
      { type: "reasoning", providerMetadata: { openai: { itemId: "rs_09fa18d4..." } } },
      { type: "tool-changeBackgroundColor", state: "output-available" },
      { type: "text", text: "Done — the background is now red." }
    ]
  },

  { id: "assistant_...7z9jhhwle",  // Duplicate - still persisted
    parts: [
      { type: "reasoning", providerMetadata: { openai: { itemId: "rs_09fa18d4..." } } },  // Same itemId
      { type: "tool-changeBackgroundColor", state: "input-available" }
    ]
  },

  { id: "assistant_...fv0mbotnt",  // Duplicate - still persisted
    parts: [
      { type: "text", text: "Done — the background is now red." }
    ]
  },

  { role: "user", id: "F6khy86gQHJHqn5K" }  // Follow-up
]

OpenAI rejects with: Duplicate item found with id rs_09fa18d4...

The _resolveMessageForToolMerge correctly merges when output-available arrives, but additional messages are still being persisted somewhere in the flow. The old input-available message and
separate text response message remain in the database.

[whoiskatrin]

@alexanderjacobsen can you give me your minimal repro please? it would be much easier for me

[alexanderjacobsen]

Does this help? gist

[alexanderjacobsen]

I was also able to replicate the error when using gpt-5-mini in the guides/human-in-the-loop when it calls a tool that executes on the client. You could try that as well

[whoiskatrin]

@alexanderjacobsen yes, seeing it now. the tricky part it wasn't reproducible with every openAI model, can see it now with gpt-5-mini

[whoiskatrin]

@alexanderjacobsen ok so the latest change fix the errors for me, give it a go

[alexanderjacobsen]

Did you forget to commit changes to ai-react.tsx? The server handles CF_AGENT_TOOL_RESULT but the client never sends it