feat(ai): chat.addToolResult() is now chat.addToolOutput() (#10039)

## Summary

* Renamed `addToolResult()` into `addToolOutput()`
* `addToolResult` in `chat` and `useChat` is left with deprecation
notice, pointing to `addToolOutput`
* Updated method call in tests; Copied one test with `addToolResult` to
make sure it works the same
* Updated docs & v5 migration guide
* Added codemod

## Related Issues

Fixes #8575

---------

Co-authored-by: Gregor Martynus <[email protected]>

Author: bel0v

.changeset/early-maps-grin.md

@@ -0,0 +1,6 @@
+---
+'@ai-sdk/react': patch
+'ai': patch
+---
+
+feat(ai): `chat.addToolResult()` is now `chat.addToolOutput()`

content/cookbook/01-next/75-human-in-the-loop.mdx

@@ -185,7 +185,7 @@ export async function POST(req: Request) {
 
 On the frontend, you map through the messages, either rendering the message content or checking for tool invocations and rendering custom UI.
 
-You can check if the tool requiring confirmation has been called and, if so, present options to either confirm or deny the proposed tool call. This confirmation is done using the `addToolResult` function to create a tool result and append it to the associated tool call.
+You can check if the tool requiring confirmation has been called and, if so, present options to either confirm or deny the proposed tool call. This confirmation is done using the `addToolOutput` function to create a tool result and append it to the associated tool call.
 
 ```tsx filename="app/page.tsx"
 'use client';
@@ -195,7 +195,7 @@ import { DefaultChatTransport, isToolUIPart, getToolName } from 'ai';
 import { useState } from 'react';
 
 export default function Chat() {
-  const { messages, addToolResult, sendMessage } = useChat({
+  const { messages, addToolOutput, sendMessage } = useChat({
     transport: new DefaultChatTransport({
       api: '/api/chat',
     }),
@@ -227,7 +227,7 @@ export default function Chat() {
                       <div>
                         <button
                           onClick={async () => {
-                            await addToolResult({
+                            await addToolOutput({
                               toolCallId,
                               tool: toolName,
                               output: 'Yes, confirmed.',
@@ -239,7 +239,7 @@ export default function Chat() {
                         </button>
                         <button
                           onClick={async () => {
-                            await addToolResult({
+                            await addToolOutput({
                               toolCallId,
                               tool: toolName,
                               output: 'No, denied.',
@@ -281,13 +281,13 @@ export default function Chat() {
 ```
 
 <Note>
-  The `sendMessage()` function after `addToolResult` will trigger a call to your
+  The `sendMessage()` function after `addToolOutput` will trigger a call to your
   route handler.
 </Note>
 
 ### Handle Confirmation Response
 
-Adding a tool result and sending the message will trigger another call to your route handler. Before sending the new messages to the language model, you pull out the last message and map through the message parts to see if the tool requiring confirmation was called and whether it's in a "result" state. If those conditions are met, you check the confirmation state (the tool result state that you set on the frontend with the `addToolResult` function).
+Adding a tool result and sending the message will trigger another call to your route handler. Before sending the new messages to the language model, you pull out the last message and map through the message parts to see if the tool requiring confirmation was called and whether it's in a "result" state. If those conditions are met, you check the confirmation state (the tool result state that you set on the frontend with the `addToolOutput` function).
 
 ```ts filename="api/chat/route.ts"
 import { openai } from '@ai-sdk/openai';
@@ -388,7 +388,7 @@ async function executeWeatherTool({ city }: { city: string }) {
 }
 ```
 
-In this implementation, you use simple strings like "Yes, the user confirmed" or "No, the user declined" as states. If confirmed, you execute the tool. If declined, you do not execute the tool. In both cases, you update the tool result from the arbitrary data you sent with the `addToolResult` function to either the result of the execute function or an "Execution declined" statement. You send the updated tool result back to the frontend to maintain state synchronization.
+In this implementation, you use simple strings like "Yes, the user confirmed" or "No, the user declined" as states. If confirmed, you execute the tool. If declined, you do not execute the tool. In both cases, you update the tool result from the arbitrary data you sent with the `addToolOutput` function to either the result of the execute function or an "Execution declined" statement. You send the updated tool result back to the frontend to maintain state synchronization.
 
 After handling the tool result, your API route continues. This triggers another generation with the updated tool result, allowing the LLM to continue attempting to solve the query.
 
@@ -666,7 +666,7 @@ import { useState } from 'react';
 import { HumanInTheLoopUIMessage, MyTools } from '../api/chat/types';
 
 export default function Chat() {
-  const { messages, addToolResult, sendMessage } =
+  const { messages, addToolOutput, sendMessage } =
     useChat<HumanInTheLoopUIMessage>({
       transport: new DefaultChatTransport({
         api: '/api/chat',
@@ -716,7 +716,7 @@ export default function Chat() {
                       <button
                         className="px-4 py-2 font-bold text-white bg-blue-500 rounded hover:bg-blue-700"
                         onClick={async () => {
-                          await addToolResult({
+                          await addToolOutput({
                             toolCallId,
                             tool: toolName,
                             output: APPROVAL.YES,
@@ -729,7 +729,7 @@ export default function Chat() {
                       <button
                         className="px-4 py-2 font-bold text-white bg-red-500 rounded hover:bg-red-700"
                         onClick={async () => {
-                          await addToolResult({
+                          await addToolOutput({
                             toolCallId,
                             tool: toolName,
                             output: APPROVAL.NO,

content/cookbook/01-next/90-render-visual-interface-in-chat.mdx

@@ -54,7 +54,7 @@ import { ChatMessage } from './api/chat/route';
 
 export default function Chat() {
   const [input, setInput] = useState('');
-  const { messages, sendMessage, addToolResult } = useChat<ChatMessage>({
+  const { messages, sendMessage, addToolOutput } = useChat<ChatMessage>({
     transport: new DefaultChatTransport({
       api: '/api/chat',
     }),
@@ -67,7 +67,7 @@ export default function Chat() {
         const cities = ['New York', 'Los Angeles', 'Chicago', 'San Francisco'];
 
         // No await - avoids potential deadlocks
-        addToolResult({
+        addToolOutput({
           tool: 'getLocation',
           toolCallId: toolCall.toolCallId,
           output: cities[Math.floor(Math.random() * cities.length)],
@@ -100,7 +100,7 @@ export default function Chat() {
                           <button
                             className="px-4 py-2 font-bold text-white bg-blue-500 rounded hover:bg-blue-700"
                             onClick={() =>
-                              addToolResult({
+                              addToolOutput({
                                 tool: 'askForConfirmation',
                                 toolCallId: part.toolCallId,
                                 output: 'Yes, confirmed.',
@@ -112,7 +112,7 @@ export default function Chat() {
                           <button
                             className="px-4 py-2 font-bold text-white bg-red-500 rounded hover:bg-red-700"
                             onClick={() =>
-                              addToolResult({
+                              addToolOutput({
                                 tool: 'askForConfirmation',
                                 toolCallId: part.toolCallId,
                                 output: 'No, denied',

content/docs/04-ai-sdk-ui/03-chatbot-tool-usage.mdx

@@ -20,10 +20,10 @@ The flow is as follows:
 1. All tool calls are forwarded to the client.
 1. Server-side tools are executed using their `execute` method and their results are forwarded to the client.
 1. Client-side tools that should be automatically executed are handled with the `onToolCall` callback.
-   You must call `addToolResult` to provide the tool result.
+   You must call `addToolOutput` to provide the tool result.
 1. Client-side tool that require user interactions can be displayed in the UI.
    The tool calls and results are available as tool invocation parts in the `parts` property of the last assistant message.
-1. When the user interaction is done, `addToolResult` can be used to add the tool result to the chat.
+1. When the user interaction is done, `addToolOutput` can be used to add the tool result to the chat.
 1. The chat can be configured to automatically submit when all tool results are available using `sendAutomaticallyWhen`.
    This triggers another iteration of this flow.
 
@@ -104,21 +104,21 @@ There are three things worth mentioning:
 
 1. The [`onToolCall`](/docs/reference/ai-sdk-ui/use-chat#on-tool-call) callback is used to handle client-side tools that should be automatically executed.
    In this example, the `getLocation` tool is a client-side tool that returns a random city.
-   You call `addToolResult` to provide the result (without `await` to avoid potential deadlocks).
+   You call `addToolOutput` to provide the result (without `await` to avoid potential deadlocks).
 
    <Note>
      Always check `if (toolCall.dynamic)` first in your `onToolCall` handler.
      Without this check, TypeScript will throw an error like: `Type 'string' is
      not assignable to type '"toolName1" | "toolName2"'` when you try to use
-     `toolCall.toolName` in `addToolResult`.
+     `toolCall.toolName` in `addToolOutput`.
    </Note>
 
 2. The [`sendAutomaticallyWhen`](/docs/reference/ai-sdk-ui/use-chat#send-automatically-when) option with `lastAssistantMessageIsCompleteWithToolCalls` helper automatically submits when all tool results are available.
 
 3. The `parts` array of assistant messages contains tool parts with typed names like `tool-askForConfirmation`.
    The client-side tool `askForConfirmation` is displayed in the UI.
    It asks the user for confirmation and displays the result once the user confirms or denies the execution.
-   The result is added to the chat using `addToolResult` with the `tool` parameter for type safety.
+   The result is added to the chat using `addToolOutput` with the `tool` parameter for type safety.
 
 ```tsx filename='app/page.tsx' highlight="2,6,10,14-20"
 'use client';
@@ -131,7 +131,7 @@ import {
 import { useState } from 'react';
 
 export default function Chat() {
-  const { messages, sendMessage, addToolResult } = useChat({
+  const { messages, sendMessage, addToolOutput } = useChat({
     transport: new DefaultChatTransport({
       api: '/api/chat',
     }),
@@ -149,7 +149,7 @@ export default function Chat() {
         const cities = ['New York', 'Los Angeles', 'Chicago', 'San Francisco'];
 
         // No await - avoids potential deadlocks
-        addToolResult({
+        addToolOutput({
           tool: 'getLocation',
           toolCallId: toolCall.toolCallId,
           output: cities[Math.floor(Math.random() * cities.length)],
@@ -186,7 +186,7 @@ export default function Chat() {
                         <div>
                           <button
                             onClick={() =>
-                              addToolResult({
+                              addToolOutput({
                                 tool: 'askForConfirmation',
                                 toolCallId: callId,
                                 output: 'Yes, confirmed.',
@@ -197,7 +197,7 @@ export default function Chat() {
                           </button>
                           <button
                             onClick={() =>
-                              addToolResult({
+                              addToolOutput({
                                 tool: 'askForConfirmation',
                                 toolCallId: callId,
                                 output: 'No, denied',
@@ -298,7 +298,7 @@ export default function Chat() {
 
 ### Error handling
 
-Sometimes an error may occur during client-side tool execution. Use the `addToolResult` method with a `state` of `output-error` and `errorText` value instead of `output` record the error.
+Sometimes an error may occur during client-side tool execution. Use the `addToolOutput` method with a `state` of `output-error` and `errorText` value instead of `output` record the error.
 
 ```tsx filename='app/page.tsx' highlight="19,36-41"
 'use client';
@@ -311,7 +311,7 @@ import {
 import { useState } from 'react';
 
 export default function Chat() {
-  const { messages, sendMessage, addToolResult } = useChat({
+  const { messages, sendMessage, addToolOutput } = useChat({
     transport: new DefaultChatTransport({
       api: '/api/chat',
     }),
@@ -330,13 +330,13 @@ export default function Chat() {
           const weather = await getWeatherInformation(toolCall.input);
 
           // No await - avoids potential deadlocks
-          addToolResult({
+          addToolOutput({
             tool: 'getWeatherInformation',
             toolCallId: toolCall.toolCallId,
             output: weather,
           });
         } catch (err) {
-          addToolResult({
+          addToolOutput({
             tool: 'getWeatherInformation',
             toolCallId: toolCall.toolCallId,
             state: 'output-error',

content/docs/07-reference/02-ai-sdk-ui/01-use-chat.mdx

@@ -230,7 +230,7 @@ Allows you to easily create a conversational user interface for your chatbot app
       type: '({toolCall: ToolCall}) => void | Promise<void>',
       isOptional: true,
       description:
-        'Optional callback function that is invoked when a tool call is received. You must call addToolResult to provide the tool result.',
+        'Optional callback function that is invoked when a tool call is received. You must call addToolOutput to provide the tool result.',
     },
     {
       name: 'sendAutomaticallyWhen',
@@ -418,7 +418,7 @@ Allows you to easily create a conversational user interface for your chatbot app
         'Function to resume an interrupted streaming response. Useful when a network error occurs during streaming.',
     },
     {
-      name: 'addToolResult',
+      name: 'addToolOutput',
       type: '(options: { tool: string; toolCallId: string; output: unknown } | { tool: string; toolCallId: string; state: "output-error", errorText: string }) => void',
       description:
         'Function to add a tool result to the chat. This will update the chat messages with the tool result. If sendAutomaticallyWhen is configured, it may trigger an automatic submission.',

content/docs/08-migration-guides/26-migration-guide-5-0.mdx

@@ -1294,15 +1294,15 @@ import {
   lastAssistantMessageIsCompleteWithToolCalls,
 } from 'ai';
 
-const { messages, sendMessage, addToolResult } = useChat({
+const { messages, sendMessage, addToolOutput } = useChat({
   // Automatically submit when all tool results are available
   sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls,
 
   async onToolCall({ toolCall }) {
     const result = await executeToolCall(toolCall);
 
-    // Important: Don't await addToolResult inside onToolCall to avoid deadlocks
-    addToolResult({
+    // Important: Don't await addToolOutput inside onToolCall to avoid deadlocks
+    addToolOutput({
       tool: toolCall.toolName,
       toolCallId: toolCall.toolCallId,
       output: result,
@@ -1313,7 +1313,7 @@ const { messages, sendMessage, addToolResult } = useChat({
 
 <Note>
   Important: When using `sendAutomaticallyWhen`, don't use `await` with
-  `addToolResult` inside `onToolCall` as it can cause deadlocks. The `await` is
+  `addToolOutput` inside `onToolCall` as it can cause deadlocks. The `await` is
   useful when you're not using automatic submission and need to ensure the
   messages are updated before manually calling `sendMessage()`.
 </Note>
@@ -1613,9 +1613,9 @@ import type { RequestOptions } from 'ai';
 import type { CompletionRequestOptions } from 'ai';
 ```
 
-#### addToolResult Changes
+#### addToolResult Renamed to addToolOutput
 
-In the `addToolResult` function, the `result` parameter has been renamed to `output` for consistency with other tool-related APIs.
+The `addToolResult` method has been renamed to `addToolOutput`. Additionally, the `result` parameter has been renamed to `output` for consistency with other tool-related APIs.
 
 ```tsx filename="AI SDK 4.0"
 const { addToolResult } = useChat();
@@ -1628,24 +1628,29 @@ addToolResult({
 ```
 
 ```tsx filename="AI SDK 5.0"
-const { addToolResult } = useChat();
+const { addToolOutput } = useChat();
 
-// Add tool result with 'output' parameter and 'tool' name for type safety
-addToolResult({
+// Add tool output with 'output' parameter and 'tool' name for type safety
+addToolOutput({
   tool: 'getWeather',
   toolCallId: 'tool-call-123',
   output: 'Weather: 72°F, sunny',
 });
 ```
 
+<Note>
+  `addToolResult` is still available but deprecated. It will be removed in
+  version 6.
+</Note>
+
 #### Tool Result Submission Changes
 
 The automatic tool result submission behavior has been updated in `useChat` and the `Chat` component. You now have more control and flexibility over when tool results are submitted.
 
 - `onToolCall` no longer supports returning values to automatically submit tool results
-- You must explicitly call `addToolResult` to provide tool results
+- You must explicitly call `addToolOutput` to provide tool results
 - Use `sendAutomaticallyWhen` with `lastAssistantMessageIsCompleteWithToolCalls` helper for automatic submission
-- Important: Don't use `await` with `addToolResult` inside `onToolCall` to avoid deadlocks
+- Important: Don't use `await` with `addToolOutput` inside `onToolCall` to avoid deadlocks
 - The `maxSteps` parameter has been removed from the `Chat` component and `useChat` hook
 - For multi-step tool execution, use server-side `stopWhen` conditions instead (see [maxSteps Removal](#maxsteps-removal))
 
@@ -1670,7 +1675,7 @@ import {
   lastAssistantMessageIsCompleteWithToolCalls,
 } from 'ai';
 
-const { messages, sendMessage, addToolResult } = useChat({
+const { messages, sendMessage, addToolOutput } = useChat({
   // Automatic submission with helper
   sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls,
 
@@ -1679,7 +1684,7 @@ const { messages, sendMessage, addToolResult } = useChat({
       const cities = ['New York', 'Los Angeles', 'Chicago', 'San Francisco'];
 
       // Important: Don't await inside onToolCall to avoid deadlocks
-      addToolResult({
+      addToolOutput({
         tool: 'getLocation',
         toolCallId: toolCall.toolCallId,
         output: cities[Math.floor(Math.random() * cities.length)],