@super_studio/ecforce-ai-agent-react 1.1.2 → 1.2.0-canary.1

package/dist/lib/client-tools.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-tools.d.mts","names":[],"sources":["../../src/lib/client-tools.ts"],"sourcesContent":[],"mappings":";;;KAOY,oBAAA,GAAuB;KAGvB,oBAAA;EAHA,IAAA,EAAA,MAAA;EAGA,WAAA,EAAA,MAAA;EASA,WAAA,EAAA,MAAA;EAMA,OAAA,CAAA,EAAA,MAAA;EAKA,mBAAA,CAAA,EAAA,OAAoB;EAAuB,UAAA,EAdzC,oBAcyC;CAYzC;AAEa,KAzBf,wBAAA,GAyBe;EAAP,MAAA,EAAA,MAAA;EAAwB,IAAA,EAAA,MAAA;EAAO,IAAA,EAAA,OAAA;AAiEnD,CAAA;AAAoD,KApFxC,oBAAA,GAoFwC;EAClD,UAAA,EApFY,oBAoFZ;EACA,OAAA,EAAA,CAAA,IAAA,EAAA,OAAA,EAAA,GApF4B,OAoF5B,CAAA,OAAA,CAAA,GAAA,OAAA;CACA;AACA,KAnFU,oBAmFV,CAAA,oBAnFmD,CAAA,CAAE,UAmFrD,CAAA,GAAA;EACA;EACA,IAAA,EAAA,MAAA;EACA;EACsB,WAAA,EAAA,MAAA;EAArB;EAAoB,WAAA,EAAA,MAAA;;;;;;cA3ET;;kBAEI,CAAA,CAAE,OAAO,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAiE5B,kCAAkC,CAAA,CAAE;;;;;;;;GAQjD,qBAAqB"}

package/dist/lib/client-tools.mjs

@@ -0,0 +1,91 @@
+"use client";
+
+import { useChatbot } from "../components/provider/chatbot-provider.mjs";
+import React from "react";
+import { zodToJsonSchema } from "zod-to-json-schema";
+
+//#region src/lib/client-tools.ts
+const CLIENT_TOOL_NAME_PREFIX = "page_";
+function normalizeClientToolName(name) {
+	if (name.startsWith(CLIENT_TOOL_NAME_PREFIX)) return name;
+	return `${CLIENT_TOOL_NAME_PREFIX}${name}`;
+}
+function isZodV4Schema(parameters) {
+	return "_zod" in parameters;
+}
+function parametersToJsonSchema(parameters, zodModule) {
+	if (zodModule && isZodV4Schema(parameters)) {
+		const nativeToJsonSchema = zodModule.z.toJSONSchema;
+		if (typeof nativeToJsonSchema === "function") return nativeToJsonSchema(parameters);
+	}
+	return zodToJsonSchema(parameters, { $refStrategy: "none" });
+}
+/**
+* チャットボットから呼び出せるクライアントツールを登録します。
+*
+* @example
+* ```tsx
+* import { z } from "zod";
+* import { useClientTool } from "@super_studio/ecforce-ai-agent-react";
+*
+* export function InventoryToolRegistration() {
+*   useClientTool({
+*     name: "lookup_inventory",
+*     displayName: "在庫確認",
+*     description: "商品コードから在庫数を取得します。",
+*     summary: "商品在庫を返します。",
+*     parameters: z.object({
+*       sku: z.string().describe("商品コード"),
+*     }),
+*     execute: async ({ sku }) => {
+*       return { sku, available: true };
+*     },
+*   });
+*
+*   return null;
+* }
+* ```
+*/
+function useClientTool({ name, displayName, description, summary, requireConfirmation = false, parameters, execute }) {
+	const { registerClientTool, unregisterClientTool } = useChatbot();
+	const executeRef = React.useRef(execute);
+	const normalizedName = React.useMemo(() => normalizeClientToolName(name), [name]);
+	React.useEffect(() => {
+		executeRef.current = execute;
+	}, [execute]);
+	React.useEffect(() => {
+		let isCancelled = false;
+		(async () => {
+			const zodModule = isZodV4Schema(parameters) ? await import("zod") : void 0;
+			if (isCancelled) return;
+			registerClientTool({
+				definition: {
+					name: normalizedName,
+					displayName,
+					description,
+					summary,
+					requireConfirmation,
+					parameters: parametersToJsonSchema(parameters, zodModule)
+				},
+				execute: (args) => executeRef.current(args)
+			});
+		})();
+		return () => {
+			isCancelled = true;
+			unregisterClientTool(normalizedName);
+		};
+	}, [
+		description,
+		displayName,
+		normalizedName,
+		parameters,
+		registerClientTool,
+		requireConfirmation,
+		summary,
+		unregisterClientTool
+	]);
+}
+
+//#endregion
+export { useClientTool };
+//# sourceMappingURL=client-tools.mjs.map

package/dist/lib/client-tools.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-tools.mjs","names":[],"sources":["../../src/lib/client-tools.ts"],"sourcesContent":["\"use client\";\n\nimport React from \"react\";\nimport type { z } from \"zod\";\nimport { zodToJsonSchema } from \"zod-to-json-schema\";\nimport { useChatbot } from \"../components/provider/chatbot-provider\";\n\nexport type ClientToolJsonSchema = Record<string, unknown>;\nconst CLIENT_TOOL_NAME_PREFIX = \"page_\";\n\nexport type ClientToolDefinition = {\n  name: string;\n  displayName: string;\n  description: string;\n  summary?: string;\n  requireConfirmation?: boolean;\n  parameters: ClientToolJsonSchema;\n};\n\nexport type ClientToolExecuteRequest = {\n  callId: string;\n  name: string;\n  args: unknown;\n};\n\nexport type RegisteredClientTool = {\n  definition: ClientToolDefinition;\n  execute: (args: unknown) => Promise<unknown> | unknown;\n};\n\nexport type UseClientToolOptions<TParameters extends z.ZodTypeAny> = {\n  /** ツール名です。`page_`のプレフィックスが自動で追加されます。 */\n  name: string;\n  /** UI上に表示するツール名です。 */\n  displayName: string;\n  /** LLMが見れるツールの詳細説明です。 */\n  description: string;\n  /** ユーザーに表示するツールの要約です。 */\n  summary?: string;\n  /** 実行前にユーザー確認を要求するかを指定します。 */\n  requireConfirmation?: boolean;\n  /** ツールの引数を定義するZodスキーマです。 */\n  parameters: TParameters;\n  /** 検証済み引数を受け取り、ツール本体の処理を実行します。 */\n  execute: (args: z.output<TParameters>) => Promise<unknown> | unknown;\n};\n\nfunction normalizeClientToolName(name: string) {\n  if (name.startsWith(CLIENT_TOOL_NAME_PREFIX)) {\n    return name;\n  }\n\n  return `${CLIENT_TOOL_NAME_PREFIX}${name}`;\n}\n\nfunction isZodV4Schema(parameters: z.ZodTypeAny) {\n  return \"_zod\" in (parameters as object);\n}\n\nfunction parametersToJsonSchema(\n  parameters: z.ZodTypeAny,\n  zodModule?: typeof import(\"zod\"),\n): ClientToolJsonSchema {\n  if (zodModule && isZodV4Schema(parameters)) {\n    const nativeToJsonSchema = (\n      zodModule.z as typeof zodModule.z & {\n        toJSONSchema?: (schema: z.ZodTypeAny) => ClientToolJsonSchema;\n      }\n    ).toJSONSchema;\n\n    if (typeof nativeToJsonSchema === \"function\") {\n      return nativeToJsonSchema(parameters);\n    }\n  }\n\n  return zodToJsonSchema(\n    parameters as unknown as Parameters<typeof zodToJsonSchema>[0],\n    {\n      $refStrategy: \"none\",\n    },\n  ) as ClientToolJsonSchema;\n}\n\n/**\n * チャットボットから呼び出せるクライアントツールを登録します。\n *\n * @example\n * ```tsx\n * import { z } from \"zod\";\n * import { useClientTool } from \"@super_studio/ecforce-ai-agent-react\";\n *\n * export function InventoryToolRegistration() {\n *   useClientTool({\n *     name: \"lookup_inventory\",\n *     displayName: \"在庫確認\",\n *     description: \"商品コードから在庫数を取得します。\",\n *     summary: \"商品在庫を返します。\",\n *     parameters: z.object({\n *       sku: z.string().describe(\"商品コード\"),\n *     }),\n *     execute: async ({ sku }) => {\n *       return { sku, available: true };\n *     },\n *   });\n *\n *   return null;\n * }\n * ```\n */\nexport function useClientTool<TParameters extends z.ZodTypeAny>({\n  name,\n  displayName,\n  description,\n  summary,\n  requireConfirmation = false,\n  parameters,\n  execute,\n}: UseClientToolOptions<TParameters>) {\n  const { registerClientTool, unregisterClientTool } = useChatbot();\n  const executeRef = React.useRef(execute);\n  const normalizedName = React.useMemo(\n    () => normalizeClientToolName(name),\n    [name],\n  );\n\n  React.useEffect(() => {\n    executeRef.current = execute;\n  }, [execute]);\n\n  React.useEffect(() => {\n    let isCancelled = false;\n\n    void (async () => {\n      const zodModule = isZodV4Schema(parameters) ? await import(\"zod\") : undefined;\n      if (isCancelled) {\n        return;\n      }\n\n      registerClientTool({\n        definition: {\n          name: normalizedName,\n          displayName,\n          description,\n          summary,\n          requireConfirmation,\n          parameters: parametersToJsonSchema(parameters, zodModule),\n        },\n        execute: (args) => executeRef.current(args as z.output<TParameters>),\n      });\n    })();\n\n    return () => {\n      isCancelled = true;\n      unregisterClientTool(normalizedName);\n    };\n  }, [\n    description,\n    displayName,\n    normalizedName,\n    parameters,\n    registerClientTool,\n    requireConfirmation,\n    summary,\n    unregisterClientTool,\n  ]);\n}\n"],"mappings":";;;;;;;AAQA,MAAM,0BAA0B;AAuChC,SAAS,wBAAwB,MAAc;AAC7C,KAAI,KAAK,WAAW,wBAAwB,CAC1C,QAAO;AAGT,QAAO,GAAG,0BAA0B;;AAGtC,SAAS,cAAc,YAA0B;AAC/C,QAAO,UAAW;;AAGpB,SAAS,uBACP,YACA,WACsB;AACtB,KAAI,aAAa,cAAc,WAAW,EAAE;EAC1C,MAAM,qBACJ,UAAU,EAGV;AAEF,MAAI,OAAO,uBAAuB,WAChC,QAAO,mBAAmB,WAAW;;AAIzC,QAAO,gBACL,YACA,EACE,cAAc,QACf,CACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BH,SAAgB,cAAgD,EAC9D,MACA,aACA,aACA,SACA,sBAAsB,OACtB,YACA,WACoC;CACpC,MAAM,EAAE,oBAAoB,yBAAyB,YAAY;CACjE,MAAM,aAAa,MAAM,OAAO,QAAQ;CACxC,MAAM,iBAAiB,MAAM,cACrB,wBAAwB,KAAK,EACnC,CAAC,KAAK,CACP;AAED,OAAM,gBAAgB;AACpB,aAAW,UAAU;IACpB,CAAC,QAAQ,CAAC;AAEb,OAAM,gBAAgB;EACpB,IAAI,cAAc;AAElB,GAAM,YAAY;GAChB,MAAM,YAAY,cAAc,WAAW,GAAG,MAAM,OAAO,SAAS;AACpE,OAAI,YACF;AAGF,sBAAmB;IACjB,YAAY;KACV,MAAM;KACN;KACA;KACA;KACA;KACA,YAAY,uBAAuB,YAAY,UAAU;KAC1D;IACD,UAAU,SAAS,WAAW,QAAQ,KAA8B;IACrE,CAAC;MACA;AAEJ,eAAa;AACX,iBAAc;AACd,wBAAqB,eAAe;;IAErC;EACD;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@super_studio/ecforce-ai-agent-react",
-  "version": "1.1.2",
+  "version": "1.2.0-canary.1",
   "main": "./dist/index.mjs",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.mts",
@@ -20,18 +20,26 @@
   },
   "dependencies": {
     "@radix-ui/react-dialog": "1.1.14",
-    "@radix-ui/react-tooltip": "1.2.7"
+    "@radix-ui/react-tooltip": "1.2.7",
+    "zod-to-json-schema": "3.25.2"
   },
   "peerDependencies": {
     "react": ">=16",
-    "react-dom": ">=16"
+    "react-dom": ">=16",
+    "zod": ">=3"
+  },
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@types/node": "22.14.0",
     "@types/react": "19.2.7",
     "@types/react-dom": "19.2.3",
     "react": "19.2.4",
-    "react-dom": "19.2.4"
+    "react-dom": "19.2.4",
+    "zod": "4.1.12"
   },
   "scripts": {
     "dev": "tsdown --watch",

package/src/components/provider/chatbot-provider.tsx

@@ -1,11 +1,12 @@
 "use client";
 
 import React from "react";
+import type { RegisteredClientTool } from "../../lib/client-tools";
 import {
-  type SendAppMessagePayload,
   useChatbotFrameHandler,
   type InitProps,
   type MCP,
+  type SendAppMessagePayload,
 } from "./use-chatbot-frame-handler";
 import { useChatbotWindowStates } from "./use-chatbot-window-states";
 
@@ -34,6 +35,10 @@ type ChatbotContextType = {
   setSessionToken: (sessionToken: string) => void;
   /** アプリからメッセージを送信 */
   sendAppMessage: (payload: SendAppMessagePayload) => void;
+  /** Client Toolを登録 */
+  registerClientTool: (tool: RegisteredClientTool) => void;
+  /** Client Toolを解除 */
+  unregisterClientTool: (name: string) => void;
   /** チャットボットが準備できたか */
   isReady: boolean;
   /** チャットボットが初期化されたか */
@@ -49,6 +54,34 @@ const ChatbotContext = React.createContext<ChatbotContextType | undefined>(
   undefined,
 );
 
+/**
+ * `ChatbotProvider` が提供するチャットボット状態と操作 API を取得します。
+ *
+ * @returns チャットボットの表示状態、初期化 API、Client Tool の登録 API を含むコンテキスト値。
+ *
+ * @example
+ * ```tsx
+ * import { useChatbot } from "@super_studio/ecforce-ai-agent-react";
+ *
+ * export function OpenChatButton() {
+ *   const { open, setOpen, sendAppMessage } = useChatbot();
+ *
+ *   return (
+ *     <button
+ *       type="button"
+ *       onClick={() => {
+ *         setOpen(!open);
+ *         sendAppMessage({
+ *           message: "EC Forceの注文状況を確認したいです",
+ *         });
+ *       }}
+ *     >
+ *       Open chat
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
 export function useChatbot() {
   const context = React.useContext(ChatbotContext);
   if (!context) {
@@ -76,6 +109,8 @@ export function ChatbotProvider({ children }: ChatbotProviderProps) {
     setAppName,
     setSessionToken,
     sendAppMessage,
+    registerClientTool,
+    unregisterClientTool,
     init,
     isReady,
     isInitialized,
@@ -96,6 +131,8 @@ export function ChatbotProvider({ children }: ChatbotProviderProps) {
     setIsFullScreen,
     setSessionToken,
     sendAppMessage,
+    registerClientTool,
+    unregisterClientTool,
     init,
     setMcps,
     setAppName,

package/src/components/provider/use-chatbot-frame-handler.tsx

@@ -1,6 +1,11 @@
 "use client";
 
 import React from "react";
+import type {
+  ClientToolDefinition,
+  ClientToolExecuteRequest,
+  RegisteredClientTool,
+} from "../../lib/client-tools";
 
 export type IframeMessage =
   | { type: "CHATBOT_READY" }
@@ -10,7 +15,10 @@ export type IframeMessage =
   | { type: "SHRINK_CHATBOT" }
   | { type: "FULLSCREEN_CHATBOT" }
   | { type: "EXIT_FULLSCREEN_CHATBOT" }
-  | { type: "RELOAD_CHATBOT" };
+  | { type: "RELOAD_CHATBOT" }
+  | ({
+      type: "EXECUTE_CLIENT_TOOL";
+    } & ClientToolExecuteRequest);
 
 export type MCP = {
   name: string;
@@ -25,16 +33,24 @@ export type InitProps = {
 };
 
 export type AppMessageAttachment = {
+  /** 添付ファイルの表示名です。 */
   fileName: string;
+  /** 添付ファイルの MIME type です。 */
   mediaType: string;
+  /** 添付ファイルを取得できる URL です。 */
   url: string;
 };
 
 export type SendAppMessagePayload = {
+  /** チャット上に表示するタイトルです。 */
   title?: string;
+  /** ユーザーに表示するメッセージ本文です。 */
   message: string;
+  /** UI に表示せず、裏側のコンテキストとして渡すメッセージです。 */
   hiddenMessage?: string;
+  /** 新規チャットを開始してから送るかを指定します。 */
   startOnNewChat?: boolean;
+  /** メッセージと一緒に渡す添付ファイル一覧です。 */
   attachments?: AppMessageAttachment[];
 };
 
@@ -60,23 +76,86 @@ export type ParentMessage =
   | {
       type: "appMessage";
       payload: SendAppMessagePayload;
+    }
+  | {
+      type: "registerClientTools";
+      tools: ClientToolDefinition[];
+    }
+  | {
+      type: "unregisterClientTools";
+      names: string[];
+    }
+  | {
+      type: "clientToolResult";
+      callId: string;
+      result?: unknown;
+      error?: string;
     };
 
+function serializeError(error: unknown) {
+  if (error instanceof Error) {
+    return error.message;
+  }
+
+  if (typeof error === "string") {
+    return error;
+  }
+
+  return "Unknown client tool error";
+}
+
+type UseChatbotFrameHandlerProps = {
+  /** チャットボットの開閉状態を更新します。 */
+  setOpen: (open: boolean) => void;
+  /** 展開状態を更新します。 */
+  setIsExpanded: (expanded: boolean) => void;
+  /** フルスクリーン状態を更新します。 */
+  setIsFullScreen: (fullScreen: boolean) => void;
+};
+
+/**
+ * iframe と親アプリ間のメッセージ送受信を管理し、チャットボット制御 API をまとめます。
+ *
+ * @returns iframe 初期化、メッセージ送信、Client Tool 登録に使うハンドラ一式を返します。
+ *
+ * @example
+ * ```tsx
+ * export function FrameBridge() {
+ *   const [open, setOpen] = React.useState(false);
+ *   const [isExpanded, setIsExpanded] = React.useState(false);
+ *   const [isFullScreen, setIsFullScreen] = React.useState(false);
+ *   const { setIframeEl, init, sendAppMessage, isReady } =
+ *     useChatbotFrameHandler({
+ *       setOpen,
+ *       setIsExpanded,
+ *       setIsFullScreen,
+ *     });
+ *
+ *   React.useEffect(() => {
+ *     if (isReady) {
+ *       init({ appName: "EC Force" });
+ *       sendAppMessage({ message: "在庫を確認したいです" });
+ *     }
+ *   }, [init, isReady, sendAppMessage]);
+ *
+ *   return <iframe ref={setIframeEl} src="https://example.com/embed" />;
+ * }
+ * ```
+ */
 export function useChatbotFrameHandler({
   setOpen,
   setIsExpanded,
   setIsFullScreen,
-}: {
-  setOpen: (open: boolean) => void;
-  setIsExpanded: (expanded: boolean) => void;
-  setIsFullScreen: (fullScreen: boolean) => void;
-}) {
+}: UseChatbotFrameHandlerProps) {
   const [iframeEl, setIframeEl] = React.useState<HTMLIFrameElement | null>(
     null,
   );
   const [isReady, setIsReady] = React.useState(false);
   const [isInitialized, setIsInitialized] = React.useState(false);
   const pendingAppMessageRef = React.useRef<SendAppMessagePayload | null>(null);
+  const clientToolRegistryRef = React.useRef(
+    new Map<string, RegisteredClientTool>(),
+  );
 
   // helper to post message to the iframe
   const postMessage = React.useCallback(
@@ -158,6 +237,54 @@ export function useChatbotFrameHandler({
     flushPendingAppMessage();
   }, [flushPendingAppMessage]);
 
+  const registerClientTool = React.useCallback(
+    (tool: RegisteredClientTool) => {
+      clientToolRegistryRef.current.set(tool.definition.name, tool);
+      if (!isReady || !isInitialized) {
+        return;
+      }
+
+      postMessage({
+        type: "registerClientTools",
+        tools: [tool.definition],
+      });
+    },
+    [isInitialized, isReady, postMessage],
+  );
+
+  const unregisterClientTool = React.useCallback(
+    (name: string) => {
+      const deleted = clientToolRegistryRef.current.delete(name);
+      if (!deleted || !isReady || !isInitialized) {
+        return;
+      }
+
+      postMessage({
+        type: "unregisterClientTools",
+        names: [name],
+      });
+    },
+    [isInitialized, isReady, postMessage],
+  );
+
+  React.useEffect(() => {
+    if (!isReady || !isInitialized) {
+      return;
+    }
+
+    const tools = [...clientToolRegistryRef.current.values()].map(
+      (tool) => tool.definition,
+    );
+    if (tools.length === 0) {
+      return;
+    }
+
+    postMessage({
+      type: "registerClientTools",
+      tools,
+    });
+  }, [isInitialized, isReady, postMessage]);
+
   // Initialize and setup listeners
   React.useEffect(() => {
     const iframe = iframeEl;
@@ -199,6 +326,36 @@ export function useChatbotFrameHandler({
           // reload iframe
           iframe.src = iframe.src;
           break;
+        case "EXECUTE_CLIENT_TOOL": {
+          const { callId, name, args } = event.data;
+          const tool = clientToolRegistryRef.current.get(name);
+          if (!tool) {
+            postMessage({
+              type: "clientToolResult",
+              callId,
+              error: `Client tool not found: ${name}`,
+            });
+            break;
+          }
+
+          void (async () => {
+            try {
+              const result = await tool.execute(args);
+              postMessage({
+                type: "clientToolResult",
+                callId,
+                result,
+              });
+            } catch (error) {
+              postMessage({
+                type: "clientToolResult",
+                callId,
+                error: serializeError(error),
+              });
+            }
+          })();
+          break;
+        }
       }
     };
 
@@ -222,6 +379,8 @@ export function useChatbotFrameHandler({
     setAppName,
     setSessionToken,
     sendAppMessage,
+    registerClientTool,
+    unregisterClientTool,
     setIframeEl,
     isReady,
     isInitialized,

package/src/components/provider/use-chatbot-window-states.tsx

@@ -2,6 +2,31 @@
 
 import React from "react";
 
+/**
+ * チャットボット UI の開閉・展開・フルスクリーン状態を管理します。
+ *
+ * @returns 初回オープン判定と、各表示状態、その更新関数を返します。
+ *
+ * @example
+ * ```tsx
+ * export function ChatbotWindowController() {
+ *   const { open, setOpen, isExpanded, setIsExpanded } =
+ *     useChatbotWindowStates();
+ *
+ *   return (
+ *     <button
+ *       type="button"
+ *       onClick={() => {
+ *         setOpen(!open);
+ *         setIsExpanded(!isExpanded);
+ *       }}
+ *     >
+ *       Toggle window
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
 export function useChatbotWindowStates() {
   const [hasOpened, setHasOpened] = React.useState(false);
   const [open, setOpen] = React.useState(false);

package/src/index.ts

@@ -3,3 +3,4 @@ export * from "./components/chatbot-frame";
 export * from "./components/chatbot-sheet";
 export * from "./components/sheet";
 export * from "./components/tooltip";
+export * from "./lib/client-tools";

package/src/lib/client-tools.ts

@@ -0,0 +1,166 @@
+"use client";
+
+import React from "react";
+import type { z } from "zod";
+import { zodToJsonSchema } from "zod-to-json-schema";
+import { useChatbot } from "../components/provider/chatbot-provider";
+
+export type ClientToolJsonSchema = Record<string, unknown>;
+const CLIENT_TOOL_NAME_PREFIX = "page_";
+
+export type ClientToolDefinition = {
+  name: string;
+  displayName: string;
+  description: string;
+  summary?: string;
+  requireConfirmation?: boolean;
+  parameters: ClientToolJsonSchema;
+};
+
+export type ClientToolExecuteRequest = {
+  callId: string;
+  name: string;
+  args: unknown;
+};
+
+export type RegisteredClientTool = {
+  definition: ClientToolDefinition;
+  execute: (args: unknown) => Promise<unknown> | unknown;
+};
+
+export type UseClientToolOptions<TParameters extends z.ZodTypeAny> = {
+  /** ツール名です。`page_`のプレフィックスが自動で追加されます。 */
+  name: string;
+  /** UI上に表示するツール名です。 */
+  displayName: string;
+  /** LLMが見れるツールの詳細説明です。 */
+  description: string;
+  /** ユーザーに表示するツールの要約です。 */
+  summary?: string;
+  /** 実行前にユーザー確認を要求するかを指定します。 */
+  requireConfirmation?: boolean;
+  /** ツールの引数を定義するZodスキーマです。 */
+  parameters: TParameters;
+  /** 検証済み引数を受け取り、ツール本体の処理を実行します。 */
+  execute: (args: z.output<TParameters>) => Promise<unknown> | unknown;
+};
+
+function normalizeClientToolName(name: string) {
+  if (name.startsWith(CLIENT_TOOL_NAME_PREFIX)) {
+    return name;
+  }
+
+  return `${CLIENT_TOOL_NAME_PREFIX}${name}`;
+}
+
+function isZodV4Schema(parameters: z.ZodTypeAny) {
+  return "_zod" in (parameters as object);
+}
+
+function parametersToJsonSchema(
+  parameters: z.ZodTypeAny,
+  zodModule?: typeof import("zod"),
+): ClientToolJsonSchema {
+  if (zodModule && isZodV4Schema(parameters)) {
+    const nativeToJsonSchema = (
+      zodModule.z as typeof zodModule.z & {
+        toJSONSchema?: (schema: z.ZodTypeAny) => ClientToolJsonSchema;
+      }
+    ).toJSONSchema;
+
+    if (typeof nativeToJsonSchema === "function") {
+      return nativeToJsonSchema(parameters);
+    }
+  }
+
+  return zodToJsonSchema(
+    parameters as unknown as Parameters<typeof zodToJsonSchema>[0],
+    {
+      $refStrategy: "none",
+    },
+  ) as ClientToolJsonSchema;
+}
+
+/**
+ * チャットボットから呼び出せるクライアントツールを登録します。
+ *
+ * @example
+ * ```tsx
+ * import { z } from "zod";
+ * import { useClientTool } from "@super_studio/ecforce-ai-agent-react";
+ *
+ * export function InventoryToolRegistration() {
+ *   useClientTool({
+ *     name: "lookup_inventory",
+ *     displayName: "在庫確認",
+ *     description: "商品コードから在庫数を取得します。",
+ *     summary: "商品在庫を返します。",
+ *     parameters: z.object({
+ *       sku: z.string().describe("商品コード"),
+ *     }),
+ *     execute: async ({ sku }) => {
+ *       return { sku, available: true };
+ *     },
+ *   });
+ *
+ *   return null;
+ * }
+ * ```
+ */
+export function useClientTool<TParameters extends z.ZodTypeAny>({
+  name,
+  displayName,
+  description,
+  summary,
+  requireConfirmation = false,
+  parameters,
+  execute,
+}: UseClientToolOptions<TParameters>) {
+  const { registerClientTool, unregisterClientTool } = useChatbot();
+  const executeRef = React.useRef(execute);
+  const normalizedName = React.useMemo(
+    () => normalizeClientToolName(name),
+    [name],
+  );
+
+  React.useEffect(() => {
+    executeRef.current = execute;
+  }, [execute]);
+
+  React.useEffect(() => {
+    let isCancelled = false;
+
+    void (async () => {
+      const zodModule = isZodV4Schema(parameters) ? await import("zod") : undefined;
+      if (isCancelled) {
+        return;
+      }
+
+      registerClientTool({
+        definition: {
+          name: normalizedName,
+          displayName,
+          description,
+          summary,
+          requireConfirmation,
+          parameters: parametersToJsonSchema(parameters, zodModule),
+        },
+        execute: (args) => executeRef.current(args as z.output<TParameters>),
+      });
+    })();
+
+    return () => {
+      isCancelled = true;
+      unregisterClientTool(normalizedName);
+    };
+  }, [
+    description,
+    displayName,
+    normalizedName,
+    parameters,
+    registerClientTool,
+    requireConfirmation,
+    summary,
+    unregisterClientTool,
+  ]);
+}