chore (core, ui): rename maxAutomaticRoundtrips to maxToolRoundtrips (#1799)

Author: lgrammel

.changeset/mean-shrimps-lie.md

@@ -0,0 +1,5 @@
+---
+'ai': patch
+---
+
+chore (core, ui): rename maxAutomaticRoundtrips to maxToolRoundtrips

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

@@ -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 `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 `maxToolRoundtrips` to a value greater
+  than 0 in the `useChat` options. It is disabled by default for backward
+  compatibility.
 </Note>
 
 ## Example
@@ -115,7 +115,7 @@ There are three things worth mentioning:
    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`.
 
-1. The `maxAutomaticRoundtrips` option is set to 5.
+1. The `maxToolRoundtrips` option is set to 5.
    This enables several tool use iterations between the client and the server.
 
 ```tsx filename='app/page.tsx'
@@ -127,7 +127,7 @@ import { Message, useChat } from 'ai/react';
 export default function Chat() {
   const { messages, input, handleInputChange, handleSubmit, addToolResult } =
     useChat({
-      maxAutomaticRoundtrips: 5,
+      maxToolRoundtrips: 5,
 
       // run client-side tools that are automatically executed:
       async onToolCall({ toolCall }) {

content/docs/07-reference/ai-sdk-core/01-generate-text.mdx

@@ -320,7 +320,7 @@ const result = await generateText({
         'An optional abort signal that can be used to cancel the call.',
     },
     {
-      name: 'maxAutomaticRoundtrips',
+      name: 'maxToolRoundtrips',
       type: 'number',
       isOptional: true,
       description:

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: 'maxAutomaticRoundtrips',
+      name: 'maxToolRoundtrips',
       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.',

content/examples/02-next-pages/tools/render-interface-during-tool-call.mdx

@@ -48,7 +48,7 @@ export default function Chat() {
   const { messages, input, handleInputChange, handleSubmit, addToolResult } =
     useChat({
       api: '/api/use-chat-tools-ui',
-      experimental_maxAutomaticRoundtrips: 5,
+      maxToolRoundtrips: 5,
 
       // run client-side tools that are automatically executed:
       async onToolCall({ toolCall }) {

content/examples/03-node/03-tools/05-call-tools-with-automatic-roundtrips.mdx

@@ -8,7 +8,7 @@ description: Learn how to call tools with automatic roundtrips in a Node.js appl
 Models call tools to gather information or perform actions that are not directly available to the model.
 When tool results are available, the model can use them to generate another response.
 
-You can enable automatic roundtrips in `generateText` by setting the `maxAutomaticRoundtrips` option to
+You can enable automatic roundtrips in `generateText` by setting the `maxToolRoundtrips` option to
 a number greater than 0.
 This option specifies the maximum number of automatic roundtrips that can be made to prevent infinite loops.
 
@@ -19,7 +19,7 @@ import { z } from 'zod'
 
 const { text } = await generateText({
   model: openai('gpt-4-turbo'),
-  maxAutomaticRoundtrips: 5
+  maxToolRoundtrips: 5
   tools: {
     weather: tool({
       description: 'Get the weather in a location',

examples/ai-core/src/complex/math-agent/agent.ts

@@ -41,7 +41,7 @@ async function main() {
       }),
     },
     toolChoice: 'required',
-    maxAutomaticRoundtrips: 10,
+    maxToolRoundtrips: 10,
   });
 }
 

examples/ai-core/src/generate-text/google-vertex-tool-call.ts

@@ -24,7 +24,7 @@ async function main() {
         },
       }),
     },
-    maxAutomaticRoundtrips: 5,
+    maxToolRoundtrips: 5,
   });
 
   console.log(text);

examples/next-openai-pages/pages/use-chat-tools-ui.tsx

@@ -5,7 +5,7 @@ export default function Chat() {
   const { messages, input, handleInputChange, handleSubmit, addToolResult } =
     useChat({
       api: '/api/use-chat-tools-ui',
-      experimental_maxAutomaticRoundtrips: 5,
+      maxAutomaticRoundtrips: 5,
 
       // run client-side tools that are automatically executed:
       async onToolCall({ toolCall }) {
@@ -22,9 +22,9 @@ export default function Chat() {
     });
 
   return (
-    <div className="flex flex-col w-full max-w-md py-24 mx-auto stretch gap-4">
+    <div className="flex flex-col w-full max-w-md gap-4 py-24 mx-auto stretch">
       {messages?.map((m: Message) => (
-        <div key={m.id} className="whitespace-pre-wrap flex flex-col gap-1">
+        <div key={m.id} className="flex flex-col gap-1 whitespace-pre-wrap">
           <strong>{`${m.role}: `}</strong>
           {m.content}
           {m.toolInvocations?.map((toolInvocation: ToolInvocation) => {
@@ -35,7 +35,7 @@ export default function Chat() {
               return (
                 <div
                   key={toolCallId}
-                  className="text-gray-500 flex flex-col gap-2"
+                  className="flex flex-col gap-2 text-gray-500"
                 >
                   {toolInvocation.args.message}
                   <div className="flex gap-2">
@@ -79,15 +79,15 @@ export default function Chat() {
                   key={toolCallId}
                   className="flex flex-col gap-2 p-4 bg-blue-400 rounded-lg"
                 >
-                  <div className="flex flex-row justify-between items-center">
-                    <div className="text-4xl text-blue-50 font-medium">
+                  <div className="flex flex-row items-center justify-between">
+                    <div className="text-4xl font-medium text-blue-50">
                       {toolInvocation.result.value}°
                       {toolInvocation.result.unit === 'celsius' ? 'C' : 'F'}
                     </div>
 
-                    <div className="h-9 w-9 bg-amber-400 rounded-full flex-shrink-0" />
+                    <div className="flex-shrink-0 rounded-full h-9 w-9 bg-amber-400" />
                   </div>
-                  <div className="flex flex-row gap-2 text-blue-50 justify-between">
+                  <div className="flex flex-row justify-between gap-2 text-blue-50">
                     {toolInvocation.result.weeklyForecast.map(
                       (forecast: any) => (
                         <div
@@ -104,7 +104,7 @@ export default function Chat() {
               ) : toolInvocation.toolName === 'getLocation' ? (
                 <div
                   key={toolCallId}
-                  className="text-gray-500 bg-gray-100 rounded-lg p-4"
+                  className="p-4 text-gray-500 bg-gray-100 rounded-lg"
                 >
                   User is in {toolInvocation.result}.
                 </div>

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

@@ -7,7 +7,7 @@ export default function Chat() {
   const { messages, input, handleInputChange, handleSubmit, addToolResult } =
     useChat({
       api: '/api/use-chat-tools',
-      maxAutomaticRoundtrips: 5,
+      maxToolRoundtrips: 5,
 
       // run client-side tools that are automatically executed:
       async onToolCall({ toolCall }) {

packages/core/core/generate-text/generate-text.test.ts

@@ -315,7 +315,7 @@ describe('result.responseMessages', () => {
         },
       },
       prompt: 'test-input',
-      maxAutomaticRoundtrips: 2,
+      maxToolRoundtrips: 2,
     });
 
     assert.deepStrictEqual(result.responseMessages, [
@@ -350,7 +350,7 @@ describe('result.responseMessages', () => {
   });
 });
 
-describe('maxAutomaticRoundtrips', () => {
+describe('maxToolRoundtrips', () => {
   it('should return text, tool calls and tool results from last roundtrip', async () => {
     let responseCount = 0;
     const result = await generateText({
@@ -468,7 +468,7 @@ describe('maxAutomaticRoundtrips', () => {
         },
       },
       prompt: 'test-input',
-      maxAutomaticRoundtrips: 2,
+      maxToolRoundtrips: 2,
     });
 
     assert.deepStrictEqual(result.text, 'Hello, world!');

packages/core/core/generate-text/generate-text.ts

@@ -54,7 +54,7 @@ If set and supported by the model, calls will generate deterministic results.
 @param maxRetries - Maximum number of retries. Set to 0 to disable retries. Default: 2.
 @param abortSignal - An optional abort signal that can be used to cancel the call.
 
-@param maxAutomaticRoundtrips - Maximal number of automatic roundtrips for tool calls.
+@param maxToolRoundtrips - Maximal number of automatic roundtrips for tool calls.
 
 @returns
 A result object that contains the generated text, the results of the tool calls, and additional information.
@@ -69,6 +69,7 @@ export async function generateText<TOOLS extends Record<string, CoreTool>>({
   maxRetries,
   abortSignal,
   maxAutomaticRoundtrips = 0,
+  maxToolRoundtrips = maxAutomaticRoundtrips,
   ...settings
 }: CallSettings &
   Prompt & {
@@ -87,6 +88,11 @@ The tool choice strategy. Default: 'auto'.
      */
     toolChoice?: CoreToolChoice<TOOLS>;
 
+    /**
+@deprecated Use `maxToolRoundtrips` instead.
+     */
+    maxAutomaticRoundtrips?: number;
+
     /**
 Maximal number of automatic roundtrips for tool calls.
 
@@ -99,7 +105,7 @@ case of misconfigured tools.
 
 By default, it's set to 0, which will disable the feature.
      */
-    maxAutomaticRoundtrips?: number;
+    maxToolRoundtrips?: number;
   }): Promise<GenerateTextResult<TOOLS>> {
   const retry = retryWithExponentialBackoff({ maxRetries });
   const validatedPrompt = getValidatedPrompt({ system, prompt, messages });
@@ -156,7 +162,7 @@ By default, it's set to 0, which will disable the feature.
     // all current tool calls have results:
     currentToolResults.length === currentToolCalls.length &&
     // the number of roundtrips is less than the maximum:
-    roundtrips++ < maxAutomaticRoundtrips
+    roundtrips++ < maxToolRoundtrips
   );
 
   return new GenerateTextResult({

packages/core/react/use-chat.ts

@@ -224,6 +224,7 @@ export function useChat({
   onToolCall,
   experimental_maxAutomaticRoundtrips = 0,
   maxAutomaticRoundtrips = experimental_maxAutomaticRoundtrips,
+  maxToolRoundtrips = maxAutomaticRoundtrips,
   streamMode,
   onResponse,
   onFinish,
@@ -236,9 +237,15 @@ export function useChat({
   api?: string | StreamingReactResponseAction;
   key?: string;
   /**
-@deprecated Use `maxAutomaticRoundtrips` instead.
+@deprecated Use `maxToolRoundtrips` instead.
    */
   experimental_maxAutomaticRoundtrips?: number;
+
+  /**
+@deprecated Use `maxToolRoundtrips` instead.
+   */
+  maxAutomaticRoundtrips?: number;
+
   /**
 Maximal number of automatic roundtrips for tool calls.
 
@@ -251,7 +258,7 @@ case of misconfigured tools.
 
 By default, it's set to 0, which will disable the feature.
    */
-  maxAutomaticRoundtrips?: number;
+  maxToolRoundtrips?: number;
 } = {}): UseChatHelpers & {
   /**
    * @deprecated Use `addToolResult` instead.
@@ -384,11 +391,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:
-        maxAutomaticRoundtrips > 0 &&
+        maxToolRoundtrips > 0 &&
         // check that roundtrip is possible:
         isAssistantMessageWithCompletedToolCalls(lastMessage) &&
         // limit the number of automatic roundtrips:
-        countTrailingAssistantMessages(messages) <= maxAutomaticRoundtrips
+        countTrailingAssistantMessages(messages) <= maxToolRoundtrips
       ) {
         await triggerRequest({ messages });
       }
@@ -409,7 +416,7 @@ By default, it's set to 0, which will disable the feature.
       experimental_onFunctionCall,
       experimental_onToolCall,
       onToolCall,
-      maxAutomaticRoundtrips,
+      maxToolRoundtrips,
       messagesRef,
       abortControllerRef,
       generateId,