@antipopp/agno-react 0.11.0 → 0.12.0

package/README.md

@@ -274,6 +274,51 @@ function InitComponent() {
 }
 ```
 
+### useAgnoToolExecution()
+
+Hook for Human-in-the-Loop (HITL) frontend tool execution.
+
+```tsx
+import {
+  createToolArgsValidatorFromSafeParse,
+  createValidatedToolHandler,
+  type ToolHandler,
+  useAgnoToolExecution,
+} from '@antipopp/agno-react';
+import { z } from 'zod';
+
+const navigateSchema = z.object({
+  url: z.string().url(),
+});
+
+const navigateValidator = createToolArgsValidatorFromSafeParse((args) =>
+  navigateSchema.safeParse(args)
+);
+
+const toolHandlers: Record<string, ToolHandler> = {
+  navigate_to_page: createValidatedToolHandler(navigateValidator, (args) => {
+    window.location.href = args.url;
+    return { success: true, url: args.url };
+  }),
+};
+
+function ChatWithTools() {
+  const { isPaused, isExecuting, pendingTools, executionError } =
+    useAgnoToolExecution(toolHandlers, true);
+
+  return <div>{isExecuting ? `Executing ${pendingTools.length} tools...` : null}</div>;
+}
+```
+
+Scope of this hook:
+- Listens to paused run events and tracks execution state for your UI
+- Executes local/global tool handlers and continues paused runs
+- Supports auto execution or manual approval flows
+- Hydrates tool-call UI components when sessions are loaded
+
+Validation note:
+- Tool arguments are runtime input. Prefer `createValidatedToolHandler()` with schema validation to avoid repeating manual guards.
+
 ## Complete Example
 
 ```tsx

package/dist/index.d.mts

@@ -41,8 +41,14 @@ declare function useAgnoClient(): AgnoClient;
 
 /**
  * Tool handler function type (now supports generative UI)
+ * - Receives normalized object arguments
+ * - Can return sync or async values
  */
-type ToolHandler = (args: Record<string, unknown> | string) => Promise<unknown>;
+type MaybePromise$1<T> = T | Promise<T>;
+type ToolHandler<TArgs extends ToolCall["tool_args"] = ToolCall["tool_args"], TResult = unknown> = {
+    bivarianceHack(args: TArgs): MaybePromise$1<TResult>;
+}["bivarianceHack"];
+type ToolHandlers = Record<string, ToolHandler>;
 /**
  * Get a custom render function by key
  */
@@ -85,7 +91,7 @@ interface ToolExecutionEvent {
  * const { isPaused, isExecuting, pendingTools } = useAgnoToolExecution(toolHandlers);
  * ```
  */
-declare function useAgnoToolExecution(handlers?: Record<string, ToolHandler>, autoExecute?: boolean): {
+declare function useAgnoToolExecution(handlers?: ToolHandlers, autoExecute?: boolean): {
     /** Whether the run is currently paused awaiting tool execution */
     isPaused: boolean;
     /** Whether tools are currently being executed */
@@ -109,12 +115,12 @@ declare function useAgnoToolExecution(handlers?: Record<string, ToolHandler>, au
  * Context value for tool handler registry
  */
 interface ToolHandlerContextValue {
-    handlers: Record<string, ToolHandler>;
+    handlers: ToolHandlers;
     registerHandler: (name: string, handler: ToolHandler) => void;
     unregisterHandler: (name: string) => void;
 }
 interface ToolHandlerProviderProps {
-    handlers?: Record<string, ToolHandler>;
+    handlers?: ToolHandlers;
     children: React.ReactNode;
 }
 /**
@@ -275,6 +281,49 @@ declare function registerChartComponent(name: string, renderer: ComponentRendere
  */
 declare function getChartComponent(name: string): ComponentRenderer | undefined;
 
+type MaybePromise<T> = T | Promise<T>;
+interface ToolArgsValidationSuccess<TArgs> {
+    success: true;
+    data: TArgs;
+}
+interface ToolArgsValidationFailure<TIssues = unknown> {
+    success: false;
+    message?: string;
+    issues?: TIssues;
+}
+type ToolArgsValidationResult<TArgs, TIssues = unknown> = ToolArgsValidationSuccess<TArgs> | ToolArgsValidationFailure<TIssues>;
+type ToolArgsValidator<TArgs, TIssues = unknown> = (args: Record<string, unknown>) => MaybePromise<ToolArgsValidationResult<TArgs, TIssues>>;
+interface ToolValidationError<TIssues = unknown> {
+    success: false;
+    code: "INVALID_TOOL_ARGS";
+    error: string;
+    issues?: TIssues;
+}
+interface CreateValidatedToolHandlerOptions<TIssues = unknown, TValidationError = ToolValidationError<TIssues>> {
+    errorMessage?: string;
+    mapValidationError?: (failure: ToolArgsValidationFailure<TIssues>, args: Record<string, unknown>) => TValidationError;
+}
+type SafeParseResult<TArgs, TIssues = unknown> = {
+    success: true;
+    data: TArgs;
+} | {
+    success: false;
+    error: TIssues;
+};
+interface CreateValidatorFromSafeParseOptions<TIssues = unknown> {
+    getErrorMessage?: (issues: TIssues) => string;
+}
+/**
+ * Create a ToolArgsValidator from libraries that expose safeParse-like APIs.
+ *
+ * This is validator-agnostic and works with Zod, Valibot, ArkType adapters, etc.
+ */
+declare function createToolArgsValidatorFromSafeParse<TArgs, TIssues = unknown>(safeParse: (args: Record<string, unknown>) => MaybePromise<SafeParseResult<TArgs, TIssues>>, options?: CreateValidatorFromSafeParseOptions<TIssues>): ToolArgsValidator<TArgs, TIssues>;
+/**
+ * Wrap a tool handler with runtime argument validation.
+ */
+declare function createValidatedToolHandler<TArgs, TResult = unknown, TIssues = unknown, TValidationError = ToolValidationError<TIssues>>(validator: ToolArgsValidator<TArgs, TIssues>, handler: (args: TArgs) => MaybePromise<TResult>, options?: CreateValidatedToolHandlerOptions<TIssues, TValidationError>): ToolHandler<Record<string, unknown>, TResult | TValidationError | ToolValidationError<TIssues>>;
+
 /**
  * Helper utilities for creating UI component specifications
  *
@@ -430,4 +479,4 @@ declare function resultWithCardGrid(cards: CardData[], options?: CardGridHelperO
  */
 declare function resultWithTable(data: DataRow[], columns: TableColumn[], options?: TableHelperOptions): ToolHandlerResult;
 
-export { AgnoProvider, type AgnoProviderProps, type CardGridHelperOptions, type ChartHelperOptions, ComponentRegistry, type ComponentRenderer, GenerativeUIRenderer, type GenerativeUIRendererProps, type TableHelperOptions, type ToolExecutionEvent, type ToolHandler, type ToolHandlerContextValue, ToolHandlerProvider, type ToolHandlerProviderProps, clearCustomRenderRegistry, createAreaChart, createArtifact, createBarChart, createCard, createCardGrid, createColumn, createLineChart, createMarkdown, createPieChart, createSmartChart, createTable, createToolResult, getChartComponent, getComponentRegistry, getCustomRender, registerChartComponent, resultWithBarChart, resultWithCardGrid, resultWithSmartChart, resultWithTable, useAgnoActions, useAgnoChat, useAgnoClient, useAgnoSession, useAgnoToolExecution, useToolHandlers };
+export { AgnoProvider, type AgnoProviderProps, type CardGridHelperOptions, type ChartHelperOptions, ComponentRegistry, type ComponentRenderer, type CreateValidatedToolHandlerOptions, type CreateValidatorFromSafeParseOptions, GenerativeUIRenderer, type GenerativeUIRendererProps, type SafeParseResult, type TableHelperOptions, type ToolArgsValidationFailure, type ToolArgsValidationResult, type ToolArgsValidationSuccess, type ToolArgsValidator, type ToolExecutionEvent, type ToolHandler, type ToolHandlerContextValue, ToolHandlerProvider, type ToolHandlerProviderProps, type ToolHandlers, type ToolValidationError, clearCustomRenderRegistry, createAreaChart, createArtifact, createBarChart, createCard, createCardGrid, createColumn, createLineChart, createMarkdown, createPieChart, createSmartChart, createTable, createToolArgsValidatorFromSafeParse, createToolResult, createValidatedToolHandler, getChartComponent, getComponentRegistry, getCustomRender, registerChartComponent, resultWithBarChart, resultWithCardGrid, resultWithSmartChart, resultWithTable, useAgnoActions, useAgnoChat, useAgnoClient, useAgnoSession, useAgnoToolExecution, useToolHandlers };

package/dist/index.d.ts

@@ -41,8 +41,14 @@ declare function useAgnoClient(): AgnoClient;
 
 /**
  * Tool handler function type (now supports generative UI)
+ * - Receives normalized object arguments
+ * - Can return sync or async values
  */
-type ToolHandler = (args: Record<string, unknown> | string) => Promise<unknown>;
+type MaybePromise$1<T> = T | Promise<T>;
+type ToolHandler<TArgs extends ToolCall["tool_args"] = ToolCall["tool_args"], TResult = unknown> = {
+    bivarianceHack(args: TArgs): MaybePromise$1<TResult>;
+}["bivarianceHack"];
+type ToolHandlers = Record<string, ToolHandler>;
 /**
  * Get a custom render function by key
  */
@@ -85,7 +91,7 @@ interface ToolExecutionEvent {
  * const { isPaused, isExecuting, pendingTools } = useAgnoToolExecution(toolHandlers);
  * ```
  */
-declare function useAgnoToolExecution(handlers?: Record<string, ToolHandler>, autoExecute?: boolean): {
+declare function useAgnoToolExecution(handlers?: ToolHandlers, autoExecute?: boolean): {
     /** Whether the run is currently paused awaiting tool execution */
     isPaused: boolean;
     /** Whether tools are currently being executed */
@@ -109,12 +115,12 @@ declare function useAgnoToolExecution(handlers?: Record<string, ToolHandler>, au
  * Context value for tool handler registry
  */
 interface ToolHandlerContextValue {
-    handlers: Record<string, ToolHandler>;
+    handlers: ToolHandlers;
     registerHandler: (name: string, handler: ToolHandler) => void;
     unregisterHandler: (name: string) => void;
 }
 interface ToolHandlerProviderProps {
-    handlers?: Record<string, ToolHandler>;
+    handlers?: ToolHandlers;
     children: React.ReactNode;
 }
 /**
@@ -275,6 +281,49 @@ declare function registerChartComponent(name: string, renderer: ComponentRendere
  */
 declare function getChartComponent(name: string): ComponentRenderer | undefined;
 
+type MaybePromise<T> = T | Promise<T>;
+interface ToolArgsValidationSuccess<TArgs> {
+    success: true;
+    data: TArgs;
+}
+interface ToolArgsValidationFailure<TIssues = unknown> {
+    success: false;
+    message?: string;
+    issues?: TIssues;
+}
+type ToolArgsValidationResult<TArgs, TIssues = unknown> = ToolArgsValidationSuccess<TArgs> | ToolArgsValidationFailure<TIssues>;
+type ToolArgsValidator<TArgs, TIssues = unknown> = (args: Record<string, unknown>) => MaybePromise<ToolArgsValidationResult<TArgs, TIssues>>;
+interface ToolValidationError<TIssues = unknown> {
+    success: false;
+    code: "INVALID_TOOL_ARGS";
+    error: string;
+    issues?: TIssues;
+}
+interface CreateValidatedToolHandlerOptions<TIssues = unknown, TValidationError = ToolValidationError<TIssues>> {
+    errorMessage?: string;
+    mapValidationError?: (failure: ToolArgsValidationFailure<TIssues>, args: Record<string, unknown>) => TValidationError;
+}
+type SafeParseResult<TArgs, TIssues = unknown> = {
+    success: true;
+    data: TArgs;
+} | {
+    success: false;
+    error: TIssues;
+};
+interface CreateValidatorFromSafeParseOptions<TIssues = unknown> {
+    getErrorMessage?: (issues: TIssues) => string;
+}
+/**
+ * Create a ToolArgsValidator from libraries that expose safeParse-like APIs.
+ *
+ * This is validator-agnostic and works with Zod, Valibot, ArkType adapters, etc.
+ */
+declare function createToolArgsValidatorFromSafeParse<TArgs, TIssues = unknown>(safeParse: (args: Record<string, unknown>) => MaybePromise<SafeParseResult<TArgs, TIssues>>, options?: CreateValidatorFromSafeParseOptions<TIssues>): ToolArgsValidator<TArgs, TIssues>;
+/**
+ * Wrap a tool handler with runtime argument validation.
+ */
+declare function createValidatedToolHandler<TArgs, TResult = unknown, TIssues = unknown, TValidationError = ToolValidationError<TIssues>>(validator: ToolArgsValidator<TArgs, TIssues>, handler: (args: TArgs) => MaybePromise<TResult>, options?: CreateValidatedToolHandlerOptions<TIssues, TValidationError>): ToolHandler<Record<string, unknown>, TResult | TValidationError | ToolValidationError<TIssues>>;
+
 /**
  * Helper utilities for creating UI component specifications
  *
@@ -430,4 +479,4 @@ declare function resultWithCardGrid(cards: CardData[], options?: CardGridHelperO
  */
 declare function resultWithTable(data: DataRow[], columns: TableColumn[], options?: TableHelperOptions): ToolHandlerResult;
 
-export { AgnoProvider, type AgnoProviderProps, type CardGridHelperOptions, type ChartHelperOptions, ComponentRegistry, type ComponentRenderer, GenerativeUIRenderer, type GenerativeUIRendererProps, type TableHelperOptions, type ToolExecutionEvent, type ToolHandler, type ToolHandlerContextValue, ToolHandlerProvider, type ToolHandlerProviderProps, clearCustomRenderRegistry, createAreaChart, createArtifact, createBarChart, createCard, createCardGrid, createColumn, createLineChart, createMarkdown, createPieChart, createSmartChart, createTable, createToolResult, getChartComponent, getComponentRegistry, getCustomRender, registerChartComponent, resultWithBarChart, resultWithCardGrid, resultWithSmartChart, resultWithTable, useAgnoActions, useAgnoChat, useAgnoClient, useAgnoSession, useAgnoToolExecution, useToolHandlers };
+export { AgnoProvider, type AgnoProviderProps, type CardGridHelperOptions, type ChartHelperOptions, ComponentRegistry, type ComponentRenderer, type CreateValidatedToolHandlerOptions, type CreateValidatorFromSafeParseOptions, GenerativeUIRenderer, type GenerativeUIRendererProps, type SafeParseResult, type TableHelperOptions, type ToolArgsValidationFailure, type ToolArgsValidationResult, type ToolArgsValidationSuccess, type ToolArgsValidator, type ToolExecutionEvent, type ToolHandler, type ToolHandlerContextValue, ToolHandlerProvider, type ToolHandlerProviderProps, type ToolHandlers, type ToolValidationError, clearCustomRenderRegistry, createAreaChart, createArtifact, createBarChart, createCard, createCardGrid, createColumn, createLineChart, createMarkdown, createPieChart, createSmartChart, createTable, createToolArgsValidatorFromSafeParse, createToolResult, createValidatedToolHandler, getChartComponent, getComponentRegistry, getCustomRender, registerChartComponent, resultWithBarChart, resultWithCardGrid, resultWithSmartChart, resultWithTable, useAgnoActions, useAgnoChat, useAgnoClient, useAgnoSession, useAgnoToolExecution, useToolHandlers };

package/dist/index.js

@@ -46,7 +46,9 @@ __export(src_exports, {
   createPieChart: () => createPieChart,
   createSmartChart: () => createSmartChart,
   createTable: () => createTable,
+  createToolArgsValidatorFromSafeParse: () => createToolArgsValidatorFromSafeParse,
   createToolResult: () => createToolResult,
+  createValidatedToolHandler: () => createValidatedToolHandler,
   getChartComponent: () => getChartComponent,
   getComponentRegistry: () => getComponentRegistry,
   getCustomRender: () => getCustomRender,
@@ -216,6 +218,22 @@ function useToolHandlers() {
 function isRecord(value) {
   return typeof value === "object" && value !== null;
 }
+function normalizeToolArgs(rawArgs) {
+  if (isRecord(rawArgs)) {
+    return rawArgs;
+  }
+  if (typeof rawArgs !== "string") {
+    return {};
+  }
+  try {
+    const parsed = JSON.parse(rawArgs);
+    if (isRecord(parsed)) {
+      return parsed;
+    }
+  } catch {
+  }
+  return { content: rawArgs };
+}
 function getCustomRenderFunction(value) {
   if (value.type !== "custom") {
     return void 0;
@@ -251,7 +269,7 @@ async function executeToolCall(tool, handlers) {
     };
   }
   try {
-    const result = await handler(tool.tool_args);
+    const result = await handler(normalizeToolArgs(tool.tool_args));
     const { resultData, uiComponent } = processToolResult(result, tool);
     return {
       ...tool,
@@ -277,7 +295,7 @@ async function hydrateToolUIForSession(tools, handlers, onHydrate) {
       continue;
     }
     try {
-      const result = await handler(tool.tool_args);
+      const result = await handler(normalizeToolArgs(tool.tool_args));
       const { uiComponent } = processToolResult(result, tool);
       if (uiComponent) {
         onHydrate(tool.tool_call_id, uiComponent);
@@ -922,6 +940,56 @@ function useAgnoSession() {
   };
 }
 
+// src/utils/tool-handler-validation.ts
+function toDefaultValidationError(failure, options) {
+  return {
+    success: false,
+    code: "INVALID_TOOL_ARGS",
+    error: failure.message ?? options?.errorMessage ?? "Invalid tool arguments",
+    ...failure.issues !== void 0 ? { issues: failure.issues } : {}
+  };
+}
+function createToolArgsValidatorFromSafeParse(safeParse, options) {
+  return async (args) => {
+    const parsed = await safeParse(args);
+    if (parsed.success) {
+      return {
+        success: true,
+        data: parsed.data
+      };
+    }
+    return {
+      success: false,
+      message: options?.getErrorMessage?.(parsed.error),
+      issues: parsed.error
+    };
+  };
+}
+function createValidatedToolHandler(validator, handler, options) {
+  return async (args) => {
+    let validationResult;
+    try {
+      validationResult = await validator(args);
+    } catch (error) {
+      const thrownFailure = {
+        success: false,
+        message: error instanceof Error ? error.message : "Tool arguments validation threw an unexpected error"
+      };
+      if (options?.mapValidationError) {
+        return options.mapValidationError(thrownFailure, args);
+      }
+      return toDefaultValidationError(thrownFailure, options);
+    }
+    if (!validationResult.success) {
+      if (options?.mapValidationError) {
+        return options.mapValidationError(validationResult, args);
+      }
+      return toDefaultValidationError(validationResult, options);
+    }
+    return handler(validationResult.data);
+  };
+}
+
 // src/utils/ui-helpers.ts
 function createBarChart(data, xKey, bars, options) {
   return {
@@ -1182,7 +1250,9 @@ function resultWithTable(data, columns, options) {
   createPieChart,
   createSmartChart,
   createTable,
+  createToolArgsValidatorFromSafeParse,
   createToolResult,
+  createValidatedToolHandler,
   getChartComponent,
   getComponentRegistry,
   getCustomRender,

package/dist/index.mjs

@@ -150,6 +150,22 @@ function useToolHandlers() {
 function isRecord(value) {
   return typeof value === "object" && value !== null;
 }
+function normalizeToolArgs(rawArgs) {
+  if (isRecord(rawArgs)) {
+    return rawArgs;
+  }
+  if (typeof rawArgs !== "string") {
+    return {};
+  }
+  try {
+    const parsed = JSON.parse(rawArgs);
+    if (isRecord(parsed)) {
+      return parsed;
+    }
+  } catch {
+  }
+  return { content: rawArgs };
+}
 function getCustomRenderFunction(value) {
   if (value.type !== "custom") {
     return void 0;
@@ -185,7 +201,7 @@ async function executeToolCall(tool, handlers) {
     };
   }
   try {
-    const result = await handler(tool.tool_args);
+    const result = await handler(normalizeToolArgs(tool.tool_args));
     const { resultData, uiComponent } = processToolResult(result, tool);
     return {
       ...tool,
@@ -211,7 +227,7 @@ async function hydrateToolUIForSession(tools, handlers, onHydrate) {
       continue;
     }
     try {
-      const result = await handler(tool.tool_args);
+      const result = await handler(normalizeToolArgs(tool.tool_args));
       const { uiComponent } = processToolResult(result, tool);
       if (uiComponent) {
         onHydrate(tool.tool_call_id, uiComponent);
@@ -856,6 +872,56 @@ function useAgnoSession() {
   };
 }
 
+// src/utils/tool-handler-validation.ts
+function toDefaultValidationError(failure, options) {
+  return {
+    success: false,
+    code: "INVALID_TOOL_ARGS",
+    error: failure.message ?? options?.errorMessage ?? "Invalid tool arguments",
+    ...failure.issues !== void 0 ? { issues: failure.issues } : {}
+  };
+}
+function createToolArgsValidatorFromSafeParse(safeParse, options) {
+  return async (args) => {
+    const parsed = await safeParse(args);
+    if (parsed.success) {
+      return {
+        success: true,
+        data: parsed.data
+      };
+    }
+    return {
+      success: false,
+      message: options?.getErrorMessage?.(parsed.error),
+      issues: parsed.error
+    };
+  };
+}
+function createValidatedToolHandler(validator, handler, options) {
+  return async (args) => {
+    let validationResult;
+    try {
+      validationResult = await validator(args);
+    } catch (error) {
+      const thrownFailure = {
+        success: false,
+        message: error instanceof Error ? error.message : "Tool arguments validation threw an unexpected error"
+      };
+      if (options?.mapValidationError) {
+        return options.mapValidationError(thrownFailure, args);
+      }
+      return toDefaultValidationError(thrownFailure, options);
+    }
+    if (!validationResult.success) {
+      if (options?.mapValidationError) {
+        return options.mapValidationError(validationResult, args);
+      }
+      return toDefaultValidationError(validationResult, options);
+    }
+    return handler(validationResult.data);
+  };
+}
+
 // src/utils/ui-helpers.ts
 function createBarChart(data, xKey, bars, options) {
   return {
@@ -1115,7 +1181,9 @@ export {
   createPieChart,
   createSmartChart,
   createTable,
+  createToolArgsValidatorFromSafeParse,
   createToolResult,
+  createValidatedToolHandler,
   getChartComponent,
   getComponentRegistry,
   getCustomRender,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antipopp/agno-react",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "React hooks for Agno client with frontend tool execution (HITL) support",
   "author": "antipopp",
   "license": "MIT",
@@ -34,8 +34,8 @@
     "README.md"
   ],
   "dependencies": {
-    "@antipopp/agno-types": "0.11.0",
-    "@antipopp/agno-client": "0.11.0"
+    "@antipopp/agno-client": "0.12.0",
+    "@antipopp/agno-types": "0.12.0"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0"