add client-defined tools and prepareSendMessagesRequest options

.changeset/slow-jobs-boil.md

@@ -0,0 +1,5 @@
+---
+"agents": patch
+---
+
+add client-defined tools and prepareSendMessagesRequest options

docs/client-tools-continuation.md

@@ -0,0 +1,29 @@
+# Client Tool Auto-Continuation
+
+## Overview
+
+By default, client-executed tools and server-executed tools behave differently:
+
+- **Server tools**: Execute and continue responding in the same turn
+- **Client tools**: Execute, then require a new request to continue
+
+The `autoContinueAfterToolResult` option lets client tools behave like server tools - the assistant can call a tool and immediately follow up with a response in one seamless turn.
+
+## How It Works
+
+```typescript
+import { useAgentChat } from "agents/ai-react";
+
+const { messages, addToolResult } = useAgentChat({
+  agent,
+  tools: myClientTools,
+  autoContinueAfterToolResult: true
+});
+```
+
+When enabled:
+
+1. Client executes the tool and sends the result to the server
+2. Server automatically calls `onChatMessage()` to continue
+3. The LLM's continuation is merged into the same assistant message
+4. User sees a single, seamless response

guides/human-in-the-loop/src/app.tsx

@@ -41,7 +41,9 @@ export default function Chat() {
     agent,
     experimental_automaticToolResolution: true,
     toolsRequiringConfirmation,
-    tools: clientTools satisfies Record<string, AITool>
+    tools: clientTools satisfies Record<string, AITool>,
+    // Enable server auto-continuation after tool results for seamless UX
+    autoContinueAfterToolResult: true
   });
 
   const [input, setInput] = useState("");
@@ -229,7 +231,7 @@ export default function Chat() {
                                   // we execute it and set the result, otherwise we
                                   // set the approval and let the server handle it
                                   const output = tool.execute
-                                    ? await tool.execute(input)
+                                    ? await tool.execute(part.input)
                                     : APPROVAL.YES;
                                   addToolResult({
                                     tool: toolName,

guides/human-in-the-loop/src/server.ts

@@ -27,16 +27,43 @@ export class HumanInTheLoop extends AIChatAgent<Env> {
     const lastMessage = this.messages[this.messages.length - 1];
 
     if (hasToolConfirmation(lastMessage)) {
-      // Process tool confirmations using UI stream
-      const stream = createUIMessageStream({
-        execute: async ({ writer }) => {
-          await processToolCalls(
-            { writer, messages: this.messages, tools },
-            { getWeatherInformation }
-          );
+      // Process tool confirmations - execute the tool and update messages
+      const updatedMessages = await processToolCalls(
+        { messages: this.messages, tools },
+        { getWeatherInformation }
+      );
+
+      // Update the agent's messages with the actual tool results
+      // This replaces "Yes, confirmed." with the actual tool output
+      this.messages = updatedMessages;
+      await this.persistMessages(this.messages);
+
+      // Now continue with streamText so the LLM can respond to the tool result
+      const result = streamText({
+        messages: convertToModelMessages(this.messages),
+        model: openai("gpt-4o"),
+        onFinish,
+        tools,
+        stopWhen: stepCountIs(5)
+      });
+
+      return result.toUIMessageStreamResponse({
+        messageMetadata: ({ part }) => {
+          if (part.type === "start") {
+            return {
+              model: "gpt-4o",
+              createdAt: Date.now(),
+              messageCount: this.messages.length
+            };
+          }
+          if (part.type === "finish") {
+            return {
+              responseTime: Date.now() - startTime,
+              totalTokens: part.totalUsage?.totalTokens
+            };
+          }
         }
       });
-      return createUIMessageStreamResponse({ stream });
     }
 
     // Use streamText directly and return with metadata

guides/human-in-the-loop/src/tools.ts

@@ -45,14 +45,32 @@ export const tools = {
 };
 
 // Export AITool format for client-side use
+// AITool uses JSON Schema (not Zod) because it needs to be serialized over the wire.
+// Only tools with `execute` need `parameters` - they get extracted and sent to the server.
+// Tools without `execute` are server-side only and just need description for display.
 export const clientTools: Record<string, AITool> = {
-  getLocalTime: getLocalTimeTool as AITool,
+  getLocalTime: {
+    description: "get the local time for a specified location",
+    parameters: {
+      type: "object",
+      properties: {
+        location: { type: "string" }
+      },
+      required: ["location"]
+    },
+    execute: async (input) => {
+      const { location } = input as { location: string };
+      console.log(`Getting local time for ${location}`);
+      await new Promise((res) => setTimeout(res, 2000));
+      return "10am";
+    }
+  },
+  // Server-side tools: no execute, no parameters needed (schema lives on server)
   getWeatherInformation: {
-    description: getWeatherInformationTool.description,
-    inputSchema: getWeatherInformationTool.inputSchema
+    description:
+      "Get the current weather information for a specific city. Always use this tool when the user asks about weather."
   },
   getLocalNews: {
-    description: getLocalNewsTool.description,
-    inputSchema: getLocalNewsTool.inputSchema
+    description: "get local news for a specified location"
   }
 };

guides/human-in-the-loop/src/utils.ts

@@ -1,5 +1,5 @@
 import type { UIMessage } from "@ai-sdk/react";
-import type { UIMessageStreamWriter, ToolSet } from "ai";
+import type { ToolSet } from "ai";
 import type { z } from "zod";
 
 // Helper type to infer tool arguments from Zod schema
@@ -76,12 +76,10 @@ export async function processToolCalls<
   }
 >(
   {
-    writer,
     messages,
     tools: _tools
   }: {
     tools: Tools; // used for type inference
-    writer: UIMessageStreamWriter;
     messages: UIMessage[];
   },
   executeFunctions: {
@@ -107,7 +105,7 @@ export async function processToolCalls<
           return part;
         }
 
-        let result: string;
+        let result: string | undefined;
 
         if (output === APPROVAL.YES) {
           const toolInstance =
@@ -120,37 +118,21 @@ export async function processToolCalls<
             result = await (
               toolInstance as (args: typeof toolInput) => Promise<string>
             )(toolInput);
-
-            // Stream the result directly using writer
-            const messageId = crypto.randomUUID();
-            const textStream = new ReadableStream({
-              start(controller) {
-                controller.enqueue({
-                  type: "text-start",
-                  id: messageId
-                });
-                controller.enqueue({
-                  type: "text-delta",
-                  id: messageId,
-                  delta: result
-                });
-                controller.enqueue({
-                  type: "text-end",
-                  id: messageId
-                });
-                controller.close();
-              }
-            });
-
-            writer.merge(textStream);
           } else {
             result = "Error: No execute function found on tool";
           }
         } else if (output === APPROVAL.NO) {
           result = "Error: User denied access to tool execution";
         }
 
-        return part; // Return the original part
+        // Return updated part with actual tool result (not the confirmation)
+        if (result !== undefined) {
+          return {
+            ...part,
+            output: result
+          };
+        }
+        return part;
       }
       return part; // Return unprocessed parts
     })