agents 0.2.30 → 0.2.32

package/README.md

@@ -515,6 +515,127 @@ This creates:
 - Intuitive input handling
 - Easy conversation reset
 
+#### Client-Defined Tools
+
+For scenarios where each client needs to register its own tools dynamically (e.g., embeddable chat widgets), use the `tools` option with `execute` functions.
+
+Tools with an `execute` function are automatically:
+
+1. Sent to the server as schemas with each request
+2. Executed on the client when the AI model calls them
+
+##### Client-Side Tool Definition
+
+```tsx
+import { useAgent } from "agents/react";
+import { useAgentChat, type AITool } from "agents/ai-react";
+
+// Define tools outside component to avoid recreation on every render
+const tools: Record<string, AITool> = {
+  showAlert: {
+    description: "Shows an alert dialog to the user",
+    parameters: {
+      type: "object",
+      properties: { message: { type: "string" } },
+      required: ["message"]
+    },
+    execute: async (input) => {
+      const { message } = input as { message: string };
+      alert(message);
+      return { success: true };
+    }
+  },
+  changeBackgroundColor: {
+    description: "Changes the page background color",
+    parameters: {
+      type: "object",
+      properties: { color: { type: "string" } }
+    },
+    execute: async (input) => {
+      const { color } = input as { color: string };
+      document.body.style.backgroundColor = color;
+      return { success: true, color };
+    }
+  }
+};
+
+function EmbeddableChat() {
+  const agent = useAgent({ agent: "chat-widget" });
+
+  const { messages, input, handleInputChange, handleSubmit } = useAgentChat({
+    agent,
+    tools // Schema + execute in one place
+  });
+
+  return (
+    <div className="chat-widget">
+      {messages.map((message) => (
+        <div key={message.id}>{/* Render message */}</div>
+      ))}
+      <form onSubmit={handleSubmit}>
+        <input value={input} onChange={handleInputChange} />
+      </form>
+    </div>
+  );
+}
+```
+
+##### Server-Side Tool Handling
+
+On the server, use `createToolsFromClientSchemas` to convert client tool schemas to AI SDK format:
+
+```typescript
+import {
+  AIChatAgent,
+  createToolsFromClientSchemas
+} from "agents/ai-chat-agent";
+import { openai } from "@ai-sdk/openai";
+import { streamText, convertToModelMessages } from "ai";
+
+export class ChatWidget extends AIChatAgent {
+  async onChatMessage(onFinish, options) {
+    const result = streamText({
+      model: openai("gpt-4o"),
+      messages: convertToModelMessages(this.messages),
+      tools: {
+        // Server-side tools (execute on server)
+        getWeather: tool({
+          description: "Get weather for a city",
+          parameters: z.object({ city: z.string() }),
+          execute: async ({ city }) => fetchWeather(city)
+        }),
+        // Client-side tools (sent back to client for execution)
+        ...createToolsFromClientSchemas(options?.clientTools)
+      },
+      onFinish
+    });
+    return result.toUIMessageStreamResponse();
+  }
+}
+```
+
+##### Advanced: Custom Request Data
+
+For additional control (custom headers, dynamic context), use `prepareSendMessagesRequest`:
+
+```tsx
+const { messages, handleSubmit } = useAgentChat({
+  agent,
+  tools, // Tool schemas auto-extracted and sent
+  prepareSendMessagesRequest: ({ id, messages }) => ({
+    body: {
+      // Add dynamic context alongside auto-extracted tool schemas
+      currentUrl: window.location.href,
+      userTimezone: Intl.DateTimeFormat().resolvedOptions().timeZone
+    },
+    headers: {
+      "X-Widget-Version": "1.0.0",
+      "X-Request-ID": crypto.randomUUID()
+    }
+  })
+});
+```
+
 ### 🔗 MCP (Model Context Protocol) Integration
 
 Agents can seamlessly integrate with the Model Context Protocol, allowing them to act as both MCP servers (providing tools to AI assistants) and MCP clients (using tools from other services).

package/dist/ai-chat-agent.d.ts

@@ -1,13 +1,59 @@
 import "./context-_sPQqJWv.js";
-import "./client-DfIOsabL.js";
+import "./client-BZVYeBmf.js";
 import "./mcp-CzbSsLfc.js";
 import "./do-oauth-client-provider-B-ryFIPr.js";
 import "./index-CyDpAVHZ.js";
-import "./ai-types-D_hTbf25.js";
-import { n as AgentContext, t as Agent } from "./index-DPJ32qQn.js";
-import { StreamTextOnFinishCallback, ToolSet, UIMessage } from "ai";
+import "./ai-types-U8lYA0o8.js";
+import { n as AgentContext, t as Agent } from "./index-B6XHf8p0.js";
+import {
+  JSONSchema7,
+  StreamTextOnFinishCallback,
+  Tool,
+  ToolSet,
+  UIMessage
+} from "ai";
 
 //#region src/ai-chat-agent.d.ts
+/**
+ * Schema for a client-defined tool sent from the browser.
+ * These tools are executed on the client, not the server.
+ *
+ * Note: Uses `parameters` (JSONSchema7) rather than AI SDK's `inputSchema` (FlexibleSchema)
+ * because this is the wire format. Zod schemas cannot be serialized.
+ */
+type ClientToolSchema = {
+  /** Unique name for the tool */
+  name: string;
+  /** Human-readable description of what the tool does */
+  description?: Tool["description"];
+  /** JSON Schema defining the tool's input parameters */
+  parameters?: JSONSchema7;
+};
+/**
+ * Options passed to the onChatMessage handler.
+ */
+type OnChatMessageOptions = {
+  /** AbortSignal for cancelling the request */
+  abortSignal?: AbortSignal;
+  /**
+   * Tool schemas sent from the client for dynamic tool registration.
+   * These represent tools that will be executed on the client side.
+   * Use `createToolsFromClientSchemas()` to convert these to AI SDK tool format.
+   */
+  clientTools?: ClientToolSchema[];
+};
+/**
+ * Converts client tool schemas to AI SDK tool format.
+ *
+ * These tools have no `execute` function - when the AI model calls them,
+ * the tool call is sent back to the client for execution.
+ *
+ * @param clientTools - Array of tool schemas from the client
+ * @returns Record of AI SDK tools that can be spread into your tools object
+ */
+declare function createToolsFromClientSchemas(
+  clientTools?: ClientToolSchema[]
+): ToolSet;
 /**
  * Extension of Agent with built-in chat capabilities
  * @template Env Environment type containing bindings
@@ -32,6 +78,19 @@ declare class AIChatAgent<Env = unknown, State = unknown> extends Agent<
    * @internal Protected for testing purposes.
    */
   protected _activeRequestId: string | null;
+  /**
+   * The message currently being streamed. Used to apply tool results
+   * before the message is persisted.
+   * @internal
+   */
+  private _streamingMessage;
+  /**
+   * Promise that resolves when the current stream completes.
+   * Used to wait for message persistence before continuing after tool results.
+   * @internal
+   */
+  private _streamCompletionPromise;
+  private _streamCompletionResolve;
   /**
    * Current chunk index for the active stream
    */
@@ -112,14 +171,12 @@ declare class AIChatAgent<Env = unknown, State = unknown> extends Agent<
   /**
    * Handle incoming chat messages and generate a response
    * @param onFinish Callback to be called when the response is finished
-   * @param options.signal A signal to pass to any child requests which can be used to cancel them
+   * @param options Options including abort signal and client-defined tools
    * @returns Response to send to the client or undefined
    */
   onChatMessage(
     onFinish: StreamTextOnFinishCallback<ToolSet>,
-    options?: {
-      abortSignal: AbortSignal | undefined;
-    }
+    options?: OnChatMessageOptions
   ): Promise<Response | undefined>;
   /**
    * Save messages on the server side
@@ -130,6 +187,71 @@ declare class AIChatAgent<Env = unknown, State = unknown> extends Agent<
     messages: UIMessage[],
     excludeBroadcastIds?: string[]
   ): Promise<void>;
+  /**
+   * Merges incoming messages with existing server state.
+   * This preserves tool outputs that the server has (via _applyToolResult)
+   * but the client doesn't have yet.
+   *
+   * @param incomingMessages - Messages from the client
+   * @returns Messages with server's tool outputs preserved
+   */
+  private _mergeIncomingWithServerState;
+  /**
+   * Resolves a message for persistence, handling tool result merging.
+   * If the message contains tool parts with output-available state, checks if there's
+   * an existing message with the same toolCallId that should be updated instead of
+   * creating a duplicate. This prevents the "Duplicate item found" error from OpenAI
+   * when client-side tool results arrive in a new request.
+   *
+   * @param message - The message to potentially merge
+   * @returns The message with the correct ID (either original or merged)
+   */
+  private _resolveMessageForToolMerge;
+  /**
+   * Finds an existing assistant message that contains a tool part with the given toolCallId.
+   * Used to detect when a tool result should update an existing message rather than
+   * creating a new one.
+   *
+   * @param toolCallId - The tool call ID to search for
+   * @returns The existing message if found, undefined otherwise
+   */
+  private _findMessageByToolCallId;
+  /**
+   * Sanitizes a message for persistence by removing ephemeral provider-specific
+   * data that should not be stored or sent back in subsequent requests.
+   *
+   * This handles two issues with the OpenAI Responses API:
+   *
+   * 1. **Duplicate item IDs**: The AI SDK's @ai-sdk/openai provider (v2.0.x+)
+   *    defaults to using OpenAI's Responses API which assigns unique itemIds
+   *    to each message part. When these IDs are persisted and sent back,
+   *    OpenAI rejects them as duplicates.
+   *
+   * 2. **Empty reasoning parts**: OpenAI may return reasoning parts with empty
+   *    text and encrypted content. These cause "Non-OpenAI reasoning parts are
+   *    not supported" warnings when sent back via convertToModelMessages().
+   *
+   * @param message - The message to sanitize
+   * @returns A new message with ephemeral provider data removed
+   */
+  private _sanitizeMessageForPersistence;
+  /**
+   * Helper to strip OpenAI-specific ephemeral fields from a metadata object.
+   * Removes itemId and reasoningEncryptedContent while preserving other fields.
+   */
+  private _stripOpenAIMetadata;
+  /**
+   * Applies a tool result to an existing assistant message.
+   * This is used when the client sends CF_AGENT_TOOL_RESULT for client-side tools.
+   * The server is the source of truth, so we update the message here and broadcast
+   * the update to all clients.
+   *
+   * @param toolCallId - The tool call ID this result is for
+   * @param toolName - The name of the tool
+   * @param output - The output from the tool execution
+   * @returns true if the result was applied, false if the message was not found
+   */
+  private _applyToolResult;
   private _reply;
   /**
    * Mark a stream as errored and clean up state.
@@ -162,5 +284,10 @@ declare class AIChatAgent<Env = unknown, State = unknown> extends Agent<
   destroy(): Promise<void>;
 }
 //#endregion
-export { AIChatAgent };
+export {
+  AIChatAgent,
+  ClientToolSchema,
+  OnChatMessageOptions,
+  createToolsFromClientSchemas
+};
 //# sourceMappingURL=ai-chat-agent.d.ts.map