chore (ui): move maxAutomaticRoundtrips and addToolResult out of experimental (#1778)

Author: lgrammel

.changeset/silly-pianos-speak.md

@@ -0,0 +1,5 @@
+---
+'ai': patch
+---
+
+chore (ui): move maxAutomaticRoundtrips and addToolResult out of experimental

content/docs/05-ai-sdk-ui/03-chatbot-with-tool-calling.mdx

@@ -29,7 +29,7 @@ The flow is as follows:
    You can return the tool result from the callback.
 1. Client-side tool that require user interactions can be displayed in the UI.
    The tool calls and results are available in the `toolInvocations` property of the last assistant message.
-1. When the user interaction is done, `experimental_addToolResult` can be used to add the tool result to the chat.
+1. When the user interaction is done, `addToolResult` can be used to add the tool result to the chat.
 1. When there are tool calls in the last assistant message and all tool results are available, the client sends the updated messages back to the server.
    This triggers another iteration of this flow.
 
@@ -39,9 +39,9 @@ The tool result contains all information about the tool call as well as the resu
 
 <Note>
   In order to automatically send another request to the server when all tool
-  calls are server-side, you need to set `experimental_maxAutomaticRoundtrips`
-  to a value greater than 0 in the `useChat` options. It is disabled by default
-  for backward compatibility.
+  calls are server-side, you need to set `maxAutomaticRoundtrips` to a value
+  greater than 0 in the `useChat` options. It is disabled by default for
+  backward compatibility.
 </Note>
 
 ## Example
@@ -113,9 +113,9 @@ There are three things worth mentioning:
 1. The `toolInvocations` property of the last assistant message contains all tool calls and results.
    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 `experimental_addToolResult`.
+   The result is added to the chat using `addToolResult`.
 
-1. The `experimental_maxAutomaticRoundtrips` option is set to 5.
+1. The `maxAutomaticRoundtrips` option is set to 5.
    This enables several tool use iterations between the client and the server.
 
 ```tsx filename='app/page.tsx'
@@ -125,23 +125,23 @@ import { ToolInvocation } from 'ai';
 import { Message, useChat } from 'ai/react';
 
 export default function Chat() {
-  const {
-    messages,
-    input,
-    handleInputChange,
-    handleSubmit,
-    experimental_addToolResult,
-  } = useChat({
-    experimental_maxAutomaticRoundtrips: 5,
-
-    // run client-side tools that are automatically executed:
-    async onToolCall({ toolCall }) {
-      if (toolCall.toolName === 'getLocation') {
-        const cities = ['New York', 'Los Angeles', 'Chicago', 'San Francisco'];
-        return cities[Math.floor(Math.random() * cities.length)];
-      }
-    },
-  });
+  const { messages, input, handleInputChange, handleSubmit, addToolResult } =
+    useChat({
+      maxAutomaticRoundtrips: 5,
+
+      // run client-side tools that are automatically executed:
+      async onToolCall({ toolCall }) {
+        if (toolCall.toolName === 'getLocation') {
+          const cities = [
+            'New York',
+            'Los Angeles',
+            'Chicago',
+            'San Francisco',
+          ];
+          return cities[Math.floor(Math.random() * cities.length)];
+        }
+      },
+    });
 
   return (
     <div>
@@ -164,7 +164,7 @@ export default function Chat() {
                       <>
                         <button
                           onClick={() =>
-                            experimental_addToolResult({
+                            addToolResult({
                               toolCallId,
                               result: 'Yes, confirmed.',
                             })
@@ -174,7 +174,7 @@ export default function Chat() {
                         </button>
                         <button
                           onClick={() =>
-                            experimental_addToolResult({
+                            addToolResult({
                               toolCallId,
                               result: 'No, denied',
                             })

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

@@ -105,7 +105,7 @@ Allows you to easily create a conversational user interface for your chatbot app
         "An optional boolean that determines whether to send extra fields you've added to `messages`. Defaults to `false` and only the `content` and `role` fields will be sent to the API endpoint.",
     },
     {
-      name: 'experimental_maxAutomaticRoundtrips',
+      name: 'maxAutomaticRoundtrips',
       type: 'number',
       description:
         'React only. Maximal number of automatic roundtrips for tool calls. An automatic tool call roundtrip is a call to the server with the  tool call results when all tool calls in the last assistant  message have results. A maximum number is required to prevent infinite loops in the case of misconfigured tools. By default, it is set to 0, which will disable the feature.',
@@ -184,7 +184,7 @@ Allows you to easily create a conversational user interface for your chatbot app
       description: 'Data returned from experimental_StreamData',
     },
     {
-      name: 'experimental_addToolResult',
+      name: 'addToolResult',
       type: '({toolCallId: string; result: any;}) => void',
       description:
         'React only. Function to add a tool result to the chat. This will update the chat messages with the tool result and call the API route if all tool results for the last message are available.',

examples/next-openai/app/use-chat-tools/page.tsx

@@ -4,24 +4,24 @@ import { ToolInvocation } from 'ai';
 import { Message, useChat } from 'ai/react';
 
 export default function Chat() {
-  const {
-    messages,
-    input,
-    handleInputChange,
-    handleSubmit,
-    experimental_addToolResult,
-  } = useChat({
-    api: '/api/use-chat-tools',
-    experimental_maxAutomaticRoundtrips: 5,
+  const { messages, input, handleInputChange, handleSubmit, addToolResult } =
+    useChat({
+      api: '/api/use-chat-tools',
+      maxAutomaticRoundtrips: 5,
 
-    // run client-side tools that are automatically executed:
-    async onToolCall({ toolCall }) {
-      if (toolCall.toolName === 'getLocation') {
-        const cities = ['New York', 'Los Angeles', 'Chicago', 'San Francisco'];
-        return cities[Math.floor(Math.random() * cities.length)];
-      }
-    },
-  });
+      // run client-side tools that are automatically executed:
+      async onToolCall({ toolCall }) {
+        if (toolCall.toolName === 'getLocation') {
+          const cities = [
+            'New York',
+            'Los Angeles',
+            'Chicago',
+            'San Francisco',
+          ];
+          return cities[Math.floor(Math.random() * cities.length)];
+        }
+      },
+    });
 
   return (
     <div className="flex flex-col w-full max-w-md py-24 mx-auto stretch">
@@ -45,7 +45,7 @@ export default function Chat() {
                         <button
                           className="px-4 py-2 font-bold text-white bg-blue-500 rounded hover:bg-blue-700"
                           onClick={() =>
-                            experimental_addToolResult({
+                            addToolResult({
                               toolCallId,
                               result: 'Yes, confirmed.',
                             })
@@ -56,7 +56,7 @@ export default function Chat() {
                         <button
                           className="px-4 py-2 font-bold text-white bg-red-500 rounded hover:bg-red-700"
                           onClick={() =>
-                            experimental_addToolResult({
+                            addToolResult({
                               toolCallId,
                               result: 'No, denied',
                             })

packages/core/react/use-chat.ts

@@ -1,6 +1,5 @@
 import { useCallback, useEffect, useId, useRef, useState } from 'react';
 import useSWR, { KeyedMutator } from 'swr';
-import { ToolCall as CoreToolCall } from '../core/generate-text/tool-call';
 import { callChatApi } from '../shared/call-chat-api';
 import { generateId as generateIdFunc } from '../shared/generate-id';
 import { processChatStream } from '../shared/process-chat-stream';
@@ -224,6 +223,7 @@ export function useChat({
   experimental_onToolCall,
   onToolCall,
   experimental_maxAutomaticRoundtrips = 0,
+  maxAutomaticRoundtrips = experimental_maxAutomaticRoundtrips,
   streamMode,
   onResponse,
   onFinish,
@@ -236,6 +236,10 @@ export function useChat({
   api?: string | StreamingReactResponseAction;
   key?: string;
   /**
+@deprecated Use `maxAutomaticRoundtrips` instead.
+   */
+  experimental_maxAutomaticRoundtrips?: number;
+  /**
 Maximal number of automatic roundtrips for tool calls.
 
 An automatic tool call roundtrip is a call to the server with the 
@@ -247,15 +251,25 @@ case of misconfigured tools.
 
 By default, it's set to 0, which will disable the feature.
    */
-  experimental_maxAutomaticRoundtrips?: number;
+  maxAutomaticRoundtrips?: number;
 } = {}): UseChatHelpers & {
+  /**
+   * @deprecated Use `addToolResult` instead.
+   */
   experimental_addToolResult: ({
     toolCallId,
     result,
   }: {
     toolCallId: string;
     result: any;
   }) => void;
+  addToolResult: ({
+    toolCallId,
+    result,
+  }: {
+    toolCallId: string;
+    result: any;
+  }) => void;
 } {
   // Generate a unique id for the chat if not provided.
   const hookId = useId();
@@ -370,12 +384,11 @@ By default, it's set to 0, which will disable the feature.
         // ensure there is a last message:
         lastMessage != null &&
         // check if the feature is enabled:
-        experimental_maxAutomaticRoundtrips > 0 &&
+        maxAutomaticRoundtrips > 0 &&
         // check that roundtrip is possible:
         isAssistantMessageWithCompletedToolCalls(lastMessage) &&
         // limit the number of automatic roundtrips:
-        countTrailingAssistantMessages(messages) <=
-          experimental_maxAutomaticRoundtrips
+        countTrailingAssistantMessages(messages) <= maxAutomaticRoundtrips
       ) {
         await triggerRequest({ messages });
       }
@@ -396,7 +409,7 @@ By default, it's set to 0, which will disable the feature.
       experimental_onFunctionCall,
       experimental_onToolCall,
       onToolCall,
-      experimental_maxAutomaticRoundtrips,
+      maxAutomaticRoundtrips,
       messagesRef,
       abortControllerRef,
       generateId,
@@ -524,6 +537,38 @@ By default, it's set to 0, which will disable the feature.
     setInput(e.target.value);
   };
 
+  const addToolResult = ({
+    toolCallId,
+    result,
+  }: {
+    toolCallId: string;
+    result: any;
+  }) => {
+    const updatedMessages = messagesRef.current.map((message, index, arr) =>
+      // update the tool calls in the last assistant message:
+      index === arr.length - 1 &&
+      message.role === 'assistant' &&
+      message.toolInvocations
+        ? {
+            ...message,
+            toolInvocations: message.toolInvocations.map(toolInvocation =>
+              toolInvocation.toolCallId === toolCallId
+                ? { ...toolInvocation, result }
+                : toolInvocation,
+            ),
+          }
+        : message,
+    );
+
+    mutate(updatedMessages, false);
+
+    // auto-submit when all tool calls in the last assistant message have results:
+    const lastMessage = updatedMessages[updatedMessages.length - 1];
+    if (isAssistantMessageWithCompletedToolCalls(lastMessage)) {
+      triggerRequest({ messages: updatedMessages });
+    }
+  };
+
   return {
     messages: messages || [],
     error,
@@ -537,37 +582,8 @@ By default, it's set to 0, which will disable the feature.
     handleSubmit,
     isLoading,
     data: streamData,
-    experimental_addToolResult: ({
-      toolCallId,
-      result,
-    }: {
-      toolCallId: string;
-      result: any;
-    }) => {
-      const updatedMessages = messagesRef.current.map((message, index, arr) =>
-        // update the tool calls in the last assistant message:
-        index === arr.length - 1 &&
-        message.role === 'assistant' &&
-        message.toolInvocations
-          ? {
-              ...message,
-              toolInvocations: message.toolInvocations.map(toolInvocation =>
-                toolInvocation.toolCallId === toolCallId
-                  ? { ...toolInvocation, result }
-                  : toolInvocation,
-              ),
-            }
-          : message,
-      );
-
-      mutate(updatedMessages, false);
-
-      // auto-submit when all tool calls in the last assistant message have results:
-      const lastMessage = updatedMessages[updatedMessages.length - 1];
-      if (isAssistantMessageWithCompletedToolCalls(lastMessage)) {
-        triggerRequest({ messages: updatedMessages });
-      }
-    },
+    addToolResult,
+    experimental_addToolResult: addToolResult,
   };
 }