feat (core): add maxAutomaticRoundtrips setting to generateText (#1750)

Author: lgrammel

.changeset/sour-eagles-tease.md

@@ -0,0 +1,5 @@
+---
+'ai': patch
+---
+
+feat (core): add maxAutomaticRoundtrips setting to generateText

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

@@ -21,7 +21,9 @@ const result = await generateText({
 });
 ```
 
-## Parameters
+## API Signature
+
+### Parameters
 
 <PropertiesTable
   content={[
@@ -317,10 +319,17 @@ const result = await generateText({
       description:
         'An optional abort signal that can be used to cancel the call.',
     },
+    {
+      name: 'maxAutomaticRoundtrips',
+      type: 'number',
+      isOptional: true,
+      description:
+        'Maximum number of automatic roundtrips for tool calls. An automatic tool call roundtrip is another LLM call with the tool call results when all tool calls of 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.',
+    },
   ]}
 />
 
-## Result Object
+### Returns
 
 <PropertiesTable
   content={[

examples/ai-core/package.json

@@ -10,6 +10,7 @@
     "@ai-sdk/openai": "latest",
     "ai": "latest",
     "dotenv": "16.4.5",
+    "mathjs": "12.4.2",
     "zod": "3.23.8",
     "zod-to-json-schema": "3.22.4"
   },

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

@@ -0,0 +1,48 @@
+import { openai } from '@ai-sdk/openai';
+import { generateText, tool } from 'ai';
+import dotenv from 'dotenv';
+import * as mathjs from 'mathjs';
+import { z } from 'zod';
+
+dotenv.config();
+
+const problem =
+  'A taxi driver earns $9461 per 1-hour work. ' +
+  'If he works 12 hours a day and in 1 hour he uses 12-liters petrol with price $134 for 1-liter. ' +
+  'How much money does he earn in one day?';
+
+async function main() {
+  console.log(`PROBLEM: ${problem}\n`);
+
+  await generateText({
+    model: openai('gpt-4-turbo'),
+    system:
+      'You are solving math problems. ' +
+      'Reason step by step. ' +
+      'Use the calculator when necessary. ' +
+      'The calculator can only do simple additions, subtractions, multiplications, and divisions. ' +
+      'When you give the final answer, provide an explanation for how you got it.',
+    prompt: problem,
+    tools: {
+      calculate: tool({
+        description:
+          'A tool for evaluating mathematical expressions. Example expressions: ' +
+          "'1.2 * (2 + 4.5)', '12.7 cm to inch', 'sin(45 deg) ^ 2'.",
+        parameters: z.object({ expression: z.string() }),
+        execute: async ({ expression }) => mathjs.evaluate(expression),
+      }),
+      answer: tool({
+        description: 'A tool for providing the final answer.',
+        parameters: z.object({ answer: z.string() }),
+        execute: async ({ answer }) => {
+          console.log(`ANSWER: ${answer}`);
+          process.exit(0);
+        },
+      }),
+    },
+    toolChoice: 'required',
+    maxAutomaticRoundtrips: 10,
+  });
+}
+
+main().catch(console.error);

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

@@ -268,4 +268,211 @@ describe('result.responseMessages', () => {
       },
     ]);
   });
+
+  it('should contain assistant response message and tool message from all roundtrips', async () => {
+    let responseCount = 0;
+    const result = await generateText({
+      model: new MockLanguageModelV1({
+        doGenerate: async ({ prompt, mode }) => {
+          switch (responseCount++) {
+            case 0:
+              return {
+                ...dummyResponseValues,
+                toolCalls: [
+                  {
+                    toolCallType: 'function',
+                    toolCallId: 'call-1',
+                    toolName: 'tool1',
+                    args: `{ "value": "value" }`,
+                  },
+                ],
+                toolResults: [
+                  {
+                    toolCallId: 'call-1',
+                    toolName: 'tool1',
+                    args: { value: 'value' },
+                    result: 'result1',
+                  },
+                ],
+              };
+            case 1:
+              return {
+                ...dummyResponseValues,
+                text: 'Hello, world!',
+              };
+            default:
+              throw new Error(`Unexpected response count: ${responseCount}`);
+          }
+        },
+      }),
+      tools: {
+        tool1: {
+          parameters: z.object({ value: z.string() }),
+          execute: async args => {
+            assert.deepStrictEqual(args, { value: 'value' });
+            return 'result1';
+          },
+        },
+      },
+      prompt: 'test-input',
+      maxAutomaticRoundtrips: 2,
+    });
+
+    assert.deepStrictEqual(result.responseMessages, [
+      {
+        role: 'assistant',
+        content: [
+          { type: 'text', text: '' },
+          {
+            type: 'tool-call',
+            toolCallId: 'call-1',
+            toolName: 'tool1',
+            args: { value: 'value' },
+          },
+        ],
+      },
+      {
+        role: 'tool',
+        content: [
+          {
+            type: 'tool-result',
+            toolCallId: 'call-1',
+            toolName: 'tool1',
+            result: 'result1',
+          },
+        ],
+      },
+      {
+        role: 'assistant',
+        content: [{ type: 'text', text: 'Hello, world!' }],
+      },
+    ]);
+  });
+});
+
+describe('maxAutomaticRoundtrips', () => {
+  it('should return text, tool calls and tool results from last roundtrip', async () => {
+    let responseCount = 0;
+    const result = await generateText({
+      model: new MockLanguageModelV1({
+        doGenerate: async ({ prompt, mode }) => {
+          switch (responseCount++) {
+            case 0:
+              assert.deepStrictEqual(mode, {
+                type: 'regular',
+                toolChoice: { type: 'auto' },
+                tools: [
+                  {
+                    type: 'function',
+                    name: 'tool1',
+                    description: undefined,
+                    parameters: {
+                      $schema: 'http://json-schema.org/draft-07/schema#',
+                      additionalProperties: false,
+                      properties: { value: { type: 'string' } },
+                      required: ['value'],
+                      type: 'object',
+                    },
+                  },
+                ],
+              });
+              assert.deepStrictEqual(prompt, [
+                {
+                  role: 'user',
+                  content: [{ type: 'text', text: 'test-input' }],
+                },
+              ]);
+              return {
+                ...dummyResponseValues,
+                toolCalls: [
+                  {
+                    toolCallType: 'function',
+                    toolCallId: 'call-1',
+                    toolName: 'tool1',
+                    args: `{ "value": "value" }`,
+                  },
+                ],
+                toolResults: [
+                  {
+                    toolCallId: 'call-1',
+                    toolName: 'tool1',
+                    args: { value: 'value' },
+                    result: 'result1',
+                  },
+                ],
+              };
+            case 1:
+              assert.deepStrictEqual(mode, {
+                type: 'regular',
+                toolChoice: { type: 'auto' },
+                tools: [
+                  {
+                    type: 'function',
+                    name: 'tool1',
+                    description: undefined,
+                    parameters: {
+                      $schema: 'http://json-schema.org/draft-07/schema#',
+                      additionalProperties: false,
+                      properties: { value: { type: 'string' } },
+                      required: ['value'],
+                      type: 'object',
+                    },
+                  },
+                ],
+              });
+              assert.deepStrictEqual(prompt, [
+                {
+                  role: 'user',
+                  content: [{ type: 'text', text: 'test-input' }],
+                },
+                {
+                  role: 'assistant',
+                  content: [
+                    { type: 'text', text: '' },
+                    {
+                      type: 'tool-call',
+                      toolCallId: 'call-1',
+                      toolName: 'tool1',
+                      args: { value: 'value' },
+                    },
+                  ],
+                },
+                {
+                  role: 'tool',
+                  content: [
+                    {
+                      type: 'tool-result',
+                      toolCallId: 'call-1',
+                      toolName: 'tool1',
+                      result: 'result1',
+                    },
+                  ],
+                },
+              ]);
+              return {
+                ...dummyResponseValues,
+                text: 'Hello, world!',
+              };
+            default:
+              throw new Error(`Unexpected response count: ${responseCount}`);
+          }
+        },
+      }),
+      tools: {
+        tool1: {
+          parameters: z.object({ value: z.string() }),
+          execute: async args => {
+            assert.deepStrictEqual(args, { value: 'value' });
+            return 'result1';
+          },
+        },
+      },
+      prompt: 'test-input',
+      maxAutomaticRoundtrips: 2,
+    });
+
+    assert.deepStrictEqual(result.text, 'Hello, world!');
+    assert.deepStrictEqual(result.toolCalls, []);
+    assert.deepStrictEqual(result.toolResults, []);
+  });
 });