feat (core): add responseMessages to generateText result (#1732)

Author: lgrammel

.changeset/stupid-papayas-juggle.md

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

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

@@ -397,6 +397,12 @@ const result = await generateText({
       description:
         'Warnings from the model provider (e.g. unsupported settings).',
     },
+    {
+      name: 'responseMessages',
+      type: 'Array<CoreAssistantMessage | CoreToolMessage>',
+      description:
+        'The response messages that were generated during the call. It consists of an assistant message, potentially containing tool calls.  When there are tool results, there is an additional tool message with the tool results that are available. If there are tools that do not have execute functions, they are not included in the tool results and need to be added separately.',
+    },
   ]}
 />
 

examples/ai-core/src/generate-text/anthropic-chatbot-with-tools.ts

@@ -22,12 +22,13 @@ async function main() {
       messages.push({ role: 'user', content: userInput });
     }
 
-    const { text, toolCalls, toolResults } = await generateText({
-      model: anthropic('claude-3-opus-20240229'),
-      tools: { weatherTool },
-      system: `You are a helpful, respectful and honest assistant.`,
-      messages,
-    });
+    const { text, toolCalls, toolResults, responseMessages } =
+      await generateText({
+        model: anthropic('claude-3-opus-20240229'),
+        tools: { weatherTool },
+        system: `You are a helpful, respectful and honest assistant.`,
+        messages,
+      });
 
     toolResponseAvailable = false;
 
@@ -49,14 +50,7 @@ async function main() {
 
     process.stdout.write('\n\n');
 
-    messages.push({
-      role: 'assistant',
-      content: [{ type: 'text', text }, ...(toolCalls ?? [])],
-    });
-
-    if (toolResults.length > 0) {
-      messages.push({ role: 'tool', content: toolResults });
-    }
+    messages.push(...responseMessages);
 
     toolResponseAvailable = toolCalls.length > 0;
   }

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

@@ -184,3 +184,88 @@ describe('result.toolResults', () => {
     ]);
   });
 });
+
+describe('result.responseMessages', () => {
+  it('should contain assistant response message when there are no tool calls', async () => {
+    const result = await generateText({
+      model: new MockLanguageModelV1({
+        doGenerate: async ({ prompt, mode }) => {
+          return {
+            ...dummyResponseValues,
+            text: 'Hello, world!',
+          };
+        },
+      }),
+      prompt: 'test-input',
+    });
+
+    assert.deepStrictEqual(result.responseMessages, [
+      { role: 'assistant', content: [{ type: 'text', text: 'Hello, world!' }] },
+    ]);
+  });
+
+  it('should contain assistant response message and tool message when there are tool calls with results', async () => {
+    const result = await generateText({
+      model: new MockLanguageModelV1({
+        doGenerate: async ({ prompt, mode }) => {
+          return {
+            ...dummyResponseValues,
+            text: 'Hello, world!',
+            toolCalls: [
+              {
+                toolCallType: 'function',
+                toolCallId: 'call-1',
+                toolName: 'tool1',
+                args: `{ "value": "value" }`,
+              },
+            ],
+            toolResults: [
+              {
+                toolCallId: 'call-1',
+                toolName: 'tool1',
+                args: { value: 'value' },
+                result: 'result1',
+              },
+            ],
+          };
+        },
+      }),
+      tools: {
+        tool1: {
+          parameters: z.object({ value: z.string() }),
+          execute: async args => {
+            assert.deepStrictEqual(args, { value: 'value' });
+            return 'result1';
+          },
+        },
+      },
+      prompt: 'test-input',
+    });
+
+    assert.deepStrictEqual(result.responseMessages, [
+      {
+        role: 'assistant',
+        content: [
+          { type: 'text', text: 'Hello, world!' },
+          {
+            type: 'tool-call',
+            toolCallId: 'call-1',
+            toolName: 'tool1',
+            args: { value: 'value' },
+          },
+        ],
+      },
+      {
+        role: 'tool',
+        content: [
+          {
+            type: 'tool-result',
+            toolCallId: 'call-1',
+            toolName: 'tool1',
+            result: 'result1',
+          },
+        ],
+      },
+    ]);
+  });
+});

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

@@ -1,3 +1,4 @@
+import { CoreAssistantMessage, CoreToolMessage } from '../prompt';
 import { CallSettings } from '../prompt/call-settings';
 import { convertToLanguageModelPrompt } from '../prompt/convert-to-language-model-prompt';
 import { getValidatedPrompt } from '../prompt/get-validated-prompt';
@@ -184,6 +185,15 @@ Warnings from the model provider (e.g. unsupported settings)
    */
   readonly warnings: CallWarning[] | undefined;
 
+  /**
+The response messages that were generated during the call. It consists of an assistant message,
+potentially containing tool calls. 
+When there are tool results, there is an additional tool message with the tool results that are available.
+If there are tools that do not have execute functions, they are not included in the tool results and
+need to be added separately.
+   */
+  readonly responseMessages: Array<CoreAssistantMessage | CoreToolMessage>;
+
   /**
 Optional raw response data.
    */
@@ -220,7 +230,42 @@ Logprobs for the completion.
     this.warnings = options.warnings;
     this.rawResponse = options.rawResponse;
     this.logprobs = options.logprobs;
+    this.responseMessages = toResponseMessages(options);
+  }
+}
+
+/**
+Converts the result of a `generateText` call to a list of response messages.
+ */
+function toResponseMessages<TOOLS extends Record<string, CoreTool>>({
+  text,
+  toolCalls,
+  toolResults,
+}: {
+  text: string;
+  toolCalls: ToToolCallArray<TOOLS>;
+  toolResults: ToToolResultArray<TOOLS>;
+}): Array<CoreAssistantMessage | CoreToolMessage> {
+  const responseMessages: Array<CoreAssistantMessage | CoreToolMessage> = [];
+
+  responseMessages.push({
+    role: 'assistant',
+    content: [{ type: 'text', text }, ...toolCalls],
+  });
+
+  if (toolResults.length > 0) {
+    responseMessages.push({
+      role: 'tool',
+      content: toolResults.map(result => ({
+        type: 'tool-result',
+        toolCallId: result.toolCallId,
+        toolName: result.toolName,
+        result: result.result,
+      })),
+    });
   }
+
+  return responseMessages;
 }
 
 /**