client/server tool invocations with useChat and streamText (#1514)

Author: lgrammel

.changeset/good-feet-accept.md

@@ -0,0 +1,5 @@
+---
+'ai': patch
+---
+
+feat (ai): support client/server tool calls with useChat and streamText

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

@@ -0,0 +1,31 @@
+import { openai } from '@ai-sdk/openai';
+import { convertToCoreMessages, streamText } from 'ai';
+import { z } from 'zod';
+
+export const dynamic = 'force-dynamic';
+export const maxDuration = 60;
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+
+  const result = await streamText({
+    model: openai('gpt-4-turbo'),
+    messages: convertToCoreMessages(messages),
+    tools: {
+      restartEngine: {
+        description:
+          'Restarts the engine. Always ask for confirmation before using this tool.',
+        parameters: z.object({}),
+        execute: async () => 'Engine restarted.',
+      },
+      askForConfirmation: {
+        description: 'Ask the user for confirmation.',
+        parameters: z.object({
+          message: z.string().describe('The message to ask for confirmation.'),
+        }),
+      },
+    },
+  });
+
+  return result.toAIStreamResponse();
+}

examples/next-openai/app/api/use-chat-tool-call-ui/route.ts

@@ -0,0 +1,34 @@
+import { openai } from '@ai-sdk/openai';
+import { streamText } from 'ai';
+import { z } from 'zod';
+
+export const dynamic = 'force-dynamic';
+export const maxDuration = 60;
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+
+  const result = await streamText({
+    model: openai('gpt-4-turbo'),
+    messages,
+    tools: {
+      weather: {
+        description: 'show the weather in a given city to the user',
+        parameters: z.object({ city: z.string() }),
+        execute: async ({}: { city: string }) => {
+          // Random delay between 1000ms (1s) and 3000ms (3s):
+          const delay = Math.floor(Math.random() * (3000 - 1000 + 1)) + 1000;
+          await new Promise(resolve => setTimeout(resolve, delay));
+
+          // Random weather:
+          const weatherOptions = ['sunny', 'cloudy', 'rainy', 'snowy', 'windy'];
+          return weatherOptions[
+            Math.floor(Math.random() * weatherOptions.length)
+          ];
+        },
+      },
+    },
+  });
+
+  return result.toAIStreamResponse();
+}

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

@@ -0,0 +1,90 @@
+'use client';
+
+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-client-tool' });
+
+  return (
+    <div className="flex flex-col w-full max-w-md py-24 mx-auto stretch">
+      {messages?.map((m: Message) => (
+        <div key={m.id} className="whitespace-pre-wrap">
+          <strong>{`${m.role}: `}</strong>
+          {m.content}
+          {m.toolInvocations?.map((toolInvocation: ToolInvocation) => {
+            const toolCallId = toolInvocation.toolCallId;
+
+            // render confirmation tool
+            if (toolInvocation.toolName === 'askForConfirmation') {
+              return (
+                <div key={toolCallId} className="text-gray-500">
+                  {toolInvocation.args.message}
+                  <div className="flex gap-2">
+                    {'result' in toolInvocation ? (
+                      <b>{toolInvocation.result}</b>
+                    ) : (
+                      <>
+                        <button
+                          className="px-4 py-2 font-bold text-white bg-blue-500 rounded hover:bg-blue-700"
+                          onClick={() =>
+                            experimental_addToolResult({
+                              toolCallId,
+                              result: 'Yes, confirmed.',
+                            })
+                          }
+                        >
+                          Yes
+                        </button>
+                        <button
+                          className="px-4 py-2 font-bold text-white bg-red-500 rounded hover:bg-red-700"
+                          onClick={() =>
+                            experimental_addToolResult({
+                              toolCallId,
+                              result: 'No, denied',
+                            })
+                          }
+                        >
+                          No
+                        </button>
+                      </>
+                    )}
+                  </div>
+                </div>
+              );
+            }
+
+            // other tools:
+            return 'result' in toolInvocation ? (
+              <div key={toolCallId} className="text-gray-500">
+                <strong>{`${toolInvocation.toolName}: `}</strong>
+                {toolInvocation.result}
+              </div>
+            ) : (
+              <div key={toolCallId} className="text-gray-500">
+                Calling {toolInvocation.toolName}...
+              </div>
+            );
+          })}
+          <br />
+          <br />
+        </div>
+      ))}
+
+      <form onSubmit={handleSubmit}>
+        <input
+          className="fixed bottom-0 w-full max-w-md p-2 mb-8 border border-gray-300 rounded shadow-xl"
+          value={input}
+          placeholder="Say something..."
+          onChange={handleInputChange}
+        />
+      </form>
+    </div>
+  );
+}

examples/next-openai/app/use-chat-client-tool/page.tsx

@@ -0,0 +1,44 @@
+'use client';
+
+import { ToolInvocation } from 'ai';
+import { useChat } from 'ai/react';
+
+export default function Chat() {
+  const { messages, input, handleInputChange, handleSubmit } = useChat({
+    api: '/api/use-chat-tool-result',
+  });
+
+  return (
+    <div className="flex flex-col w-full max-w-md py-24 mx-auto stretch">
+      {messages.map(m => (
+        <div key={m.id} className="whitespace-pre-wrap">
+          <strong>{`${m.role}: `}</strong>
+          {m.content}
+          {m.toolInvocations?.map((toolInvocation: ToolInvocation) => {
+            if (toolInvocation.toolName === 'weather') {
+              const { city } = toolInvocation.args;
+              return (
+                <i key={toolInvocation.toolCallId} className="before:block">
+                  {'result' in toolInvocation
+                    ? `Weather in ${city}: ${toolInvocation.result}`
+                    : `Calling weather tool for ${city}...`}
+                </i>
+              );
+            }
+          })}
+          <br />
+          <br />
+        </div>
+      ))}
+
+      <form onSubmit={handleSubmit}>
+        <input
+          className="fixed bottom-0 w-full max-w-md p-2 mb-8 border border-gray-300 rounded shadow-xl"
+          value={input}
+          placeholder="Say something..."
+          onChange={handleInputChange}
+        />
+      </form>
+    </div>
+  );
+}