chore(ai): document the new addToolResult interface

Co-authored-by: Nico Albanese <[email protected]>

Author: aron

content/docs/04-ai-sdk-ui/03-chatbot-tool-usage.mdx

@@ -296,6 +296,59 @@ export default function Chat() {
 }
 ```
 
+### Error handling
+
+Sometimes an error may occur during client-side tool execution. Use the `addToolResult` method with a `state` of `output-error` and `errorText` value instead of `output` record the error.
+
+```tsx filename='app/page.tsx' highlight="19,36-41"
+'use client';
+
+import { useChat } from '@ai-sdk/react';
+import {
+  DefaultChatTransport,
+  lastAssistantMessageIsCompleteWithToolCalls,
+} from 'ai';
+import { useState } from 'react';
+
+export default function Chat() {
+  const { messages, sendMessage, addToolResult } = useChat({
+    transport: new DefaultChatTransport({
+      api: '/api/chat',
+    }),
+
+    sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls,
+
+    // run client-side tools that are automatically executed:
+    async onToolCall({ toolCall }) {
+      // Check if it's a dynamic tool first for proper type narrowing
+      if (toolCall.dynamic) {
+        return;
+      }
+
+      if (toolCall.toolName === 'getWeatherInformation') {
+        try {
+          const weather = await getWeatherInformation(toolCall.input);
+
+          // No await - avoids potential deadlocks
+          addToolResult({
+            tool: 'getWeatherInformation',
+            toolCallId: toolCall.toolCallId,
+            output: weather,
+          });
+        } catch (err) {
+          addToolResult({
+            tool: 'getWeatherInformation',
+            toolCallId: toolCall.toolCallId,
+            state: 'output-error',
+            errorText: 'Unable to get the weather information',
+          });
+        }
+      }
+    },
+  });
+}
+```
+
 ## Dynamic Tools
 
 When using dynamic tools (tools with unknown types at compile time), the UI parts use a generic `dynamic-tool` type instead of specific tool types:

content/docs/07-reference/02-ai-sdk-ui/01-use-chat.mdx

@@ -419,7 +419,7 @@ Allows you to easily create a conversational user interface for your chatbot app
     },
     {
       name: 'addToolResult',
-      type: '(options: { tool: string; toolCallId: string; output: unknown }) => void',
+      type: '(options: { tool: string; toolCallId: string; output: unknown } | { tool: string; toolCallId: string; state: "output-error", errorText: string }) => void',
       description:
         'Function to add a tool result to the chat. This will update the chat messages with the tool result. If sendAutomaticallyWhen is configured, it may trigger an automatic submission.',
     },

content/docs/09-troubleshooting/05-tool-invocation-missing-result.mdx

@@ -54,14 +54,24 @@ const { messages, sendMessage, addToolResult } = useChat({
   // Handle tool calls in onToolCall
   onToolCall: async ({ toolCall }) => {
     if (toolCall.toolName === 'getLocation') {
-      const result = await getLocationData();
-
-      // Important: Don't await inside onToolCall to avoid deadlocks
-      addToolResult({
-        tool: 'getLocation',
-        toolCallId: toolCall.toolCallId,
-        output: result,
-      });
+      try {
+        const result = await getLocationData();
+
+        // Important: Don't await inside onToolCall to avoid deadlocks
+        addToolResult({
+          tool: 'getLocation',
+          toolCallId: toolCall.toolCallId,
+          output: result,
+        });
+      } catch (err) {
+        // Important: Don't await inside onToolCall to avoid deadlocks
+        addToolResult({
+          tool: 'getLocation',
+          toolCallId: toolCall.toolCallId,
+          state: 'output-error',
+          errorText: 'Failed to get location',
+        });
+      }
     }
   },
 });