feat (ai): add output schema for tools (#6819)

## Background

Server side tools and tools without an execute method need a way to
specify the output schema to drive type inference and validation.

## Summary

Add optional `outputSchema` property to tools.

Author: lgrammel

.changeset/tough-islands-sniff.md

@@ -0,0 +1,5 @@
+---
+'@ai-sdk/provider-utils': major
+---
+
+feat (ai): add output schema for tools

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

@@ -36,12 +36,11 @@ async function main() {
   // typed tool results for tools with execute method:
   for (const toolResult of result.toolResults) {
     switch (toolResult.toolName) {
-      // NOT AVAILABLE (NO EXECUTE METHOD)
-      // case 'cityAttractions': {
-      //   toolResult.input.city; // string
-      //   toolResult.result;
-      //   break;
-      // }
+      case 'cityAttractions': {
+        toolResult.input.city; // string
+        toolResult.output; // any since no outputSchema is provided
+        break;
+      }
 
       case 'weather': {
         toolResult.input.location; // string

examples/next-openai/app/api/use-chat-tools/route.ts

@@ -1,7 +1,6 @@
 import { openai } from '@ai-sdk/openai';
 import {
   convertToModelMessages,
-  InferToolInput,
   InferUITool,
   stepCountIs,
   streamText,
@@ -50,27 +49,23 @@ const askForConfirmationTool = tool({
   inputSchema: z.object({
     message: z.string().describe('The message to ask for confirmation.'),
   }),
+  outputSchema: z.string(),
 });
 
 const getLocationTool = tool({
   description:
     'Get the user location. Always ask for confirmation before using this tool.',
   inputSchema: z.object({}),
+  outputSchema: z.string(),
 });
 
 export type UseChatToolsMessage = UIMessage<
   never,
   UIDataTypes,
   {
     getWeatherInformation: InferUITool<typeof getWeatherInformationTool>;
-    askForConfirmation: {
-      input: InferToolInput<typeof askForConfirmationTool>;
-      output: string;
-    };
-    getLocation: {
-      input: InferToolInput<typeof getLocationTool>;
-      output: string;
-    };
+    askForConfirmation: InferUITool<typeof askForConfirmationTool>;
+    getLocation: InferUITool<typeof getLocationTool>;
   }
 >;
 

packages/ai/core/tool/tool.test-d.ts

@@ -1,7 +1,6 @@
 import { z } from 'zod';
 import {
   Tool,
-  ToolCallOptions,
   ToolExecuteFunction,
   FlexibleSchema,
 } from '@ai-sdk/provider-utils';
@@ -37,7 +36,7 @@ describe('tool helper', () => {
 
     expectTypeOf(toolType).toEqualTypeOf<Tool<never, 'test'>>();
     expectTypeOf(toolType.execute).toMatchTypeOf<
-      ToolExecuteFunction<never, 'test'>
+      ToolExecuteFunction<never, 'test'> | undefined
     >();
     expectTypeOf(toolType.execute).not.toEqualTypeOf<undefined>();
     expectTypeOf(toolType.inputSchema).toEqualTypeOf<undefined>();
@@ -54,10 +53,7 @@ describe('tool helper', () => {
 
     expectTypeOf(toolType).toEqualTypeOf<Tool<{ number: number }, 'test'>>();
     expectTypeOf(toolType.execute).toMatchTypeOf<
-      (
-        input: { number: number },
-        options: ToolCallOptions,
-      ) => PromiseLike<'test'> | 'test'
+      ToolExecuteFunction<{ number: number }, 'test'> | undefined
     >();
     expectTypeOf(toolType.execute).not.toEqualTypeOf<undefined>();
     expectTypeOf(toolType.inputSchema).toEqualTypeOf<

packages/provider-utils/src/types/tool.ts

@@ -25,6 +25,8 @@ export type ToolExecuteFunction<INPUT, OUTPUT> = (
   options: ToolCallOptions,
 ) => PromiseLike<OUTPUT> | OUTPUT;
 
+// 0 extends 1 & N checks for any
+// [N] extends [never] checks for never
 type NeverOptional<N, T> = 0 extends 1 & N
   ? Partial<T>
   : [N] extends [never]
@@ -56,20 +58,35 @@ It is also used to validate the output of the language model.
 Use descriptions to make the input understandable for the language model.
    */
     inputSchema: FlexibleSchema<INPUT>;
+
+    /**
+     * Optional function that is called when the argument streaming starts.
+     * Only called when the tool is used in a streaming context.
+     */
+    onInputStart?: (options: ToolCallOptions) => void | PromiseLike<void>;
+
+    /**
+     * Optional function that is called when an argument streaming delta is available.
+     * Only called when the tool is used in a streaming context.
+     */
+    onInputDelta?: (
+      options: { inputTextDelta: string } & ToolCallOptions,
+    ) => void | PromiseLike<void>;
+
+    /**
+     * Optional function that is called when a tool call can be started,
+     * even if the execute function is not provided.
+     */
+    onInputAvailable?: (
+      options: {
+        input: [INPUT] extends [never] ? undefined : INPUT;
+      } & ToolCallOptions,
+    ) => void | PromiseLike<void>;
   }
 > &
   NeverOptional<
     OUTPUT,
     {
-      /**
-An async function that is called with the arguments from the tool call and produces a result.
-If not provided, the tool will not be executed automatically.
-
-@args is the input of the tool call.
-@options.abortSignal is a signal that can be used to abort the tool call.
-      */
-      execute: ToolExecuteFunction<INPUT, OUTPUT>;
-
       /**
 Optional conversion function that maps the tool result to an output that can be used by the language model.
 
@@ -78,31 +95,25 @@ If not provided, the tool result will be sent as a JSON object.
       toModelOutput?: (
         output: OUTPUT,
       ) => LanguageModelV2ToolResultPart['output'];
+    } & (
+      | {
+          /**
+An async function that is called with the arguments from the tool call and produces a result.
+If not provided, the tool will not be executed automatically.
 
-      /**
-       * Optional function that is called when the argument streaming starts.
-       * Only called when the tool is used in a streaming context.
-       */
-      onInputStart?: (options: ToolCallOptions) => void | PromiseLike<void>;
+@args is the input of the tool call.
+@options.abortSignal is a signal that can be used to abort the tool call.
+      */
+          execute: ToolExecuteFunction<INPUT, OUTPUT>;
 
-      /**
-       * Optional function that is called when an argument streaming delta is available.
-       * Only called when the tool is used in a streaming context.
-       */
-      onInputDelta?: (
-        options: { inputTextDelta: string } & ToolCallOptions,
-      ) => void | PromiseLike<void>;
+          outputSchema?: FlexibleSchema<OUTPUT>;
+        }
+      | {
+          outputSchema: FlexibleSchema<OUTPUT>;
 
-      /**
-       * Optional function that is called when a tool call can be started,
-       * even if the execute function is not provided.
-       */
-      onInputAvailable?: (
-        options: {
-          input: [INPUT] extends [never] ? undefined : INPUT;
-        } & ToolCallOptions,
-      ) => void | PromiseLike<void>;
-    }
+          execute?: never;
+        }
+    )
   > &
   (
     | {