crewai-ts/tools/StructuredTool.d.ts

TypeScript port of crewAI for agent-based workflows

/**
 * Advanced StructuredTool implementation
 * Provides a tool with structured input and output validation
 * Optimized for memory efficiency and performance with Zod validation
 * Includes automatic schema inference, async support, and direct result features
 */
import { z } from 'zod';
import { Tool } from './BaseTool.js';
/**
 * Options for creating structured tools
 * Enhanced with memory-efficient options and advanced features
 */
export interface StructuredToolOptions<TInput, TOutput> {
    /** Name of the tool */
    name: string;
    /** Description of what the tool does */
    description: string;
    /** Input schema for validation - optional if using function inference */
    inputSchema?: z.ZodType<TInput>;
    /** Output schema for validation */
    outputSchema?: z.ZodType<TOutput>;
    /** Implementation function */
    func: (input: TInput, options?: {
        signal?: AbortSignal;
    }) => Promise<TOutput> | TOutput;
    /** Whether to return the result directly as the agent's answer */
    resultAsAnswer?: boolean;
    /** Additional metadata */
    verbose?: boolean;
    /** Cache results for identical inputs */
    cacheResults?: boolean;
    /** Timeout in milliseconds */
    timeout?: number;
    /** Number of retry attempts */
    maxRetries?: number;
    /** Categories/tags for grouping tools */
    tags?: string[];
    /** Memory optimization level (0-3, higher = more optimization) */
    memoryOptimizationLevel?: number;
}
/**
 * Function options for creating a tool from a function
 */
export interface FromFunctionOptions<TInput, TOutput> {
    /** Custom name (defaults to function name) */
    name?: string;
    /** Custom description (defaults to function docstring/comments if available) */
    description?: string;
    /** Whether to return the result directly */
    resultAsAnswer?: boolean;
    /** Optional explicit input schema (skips inference) */
    inputSchema?: z.ZodType<TInput>;
    /** Optional output schema */
    outputSchema?: z.ZodType<TOutput>;
    /** Whether to infer schema from function (default: true) */
    inferSchema?: boolean;
    /** Additional tool options */
    verbose?: boolean;
    cacheResults?: boolean;
    timeout?: number;
    maxRetries?: number;
    tags?: string[];
    /** Memory optimization level (0-3) */
    memoryOptimizationLevel?: number;
}
/**
 * StructuredTool class for creating tools with structured schema validation
 * Enhanced with:
 * - Type safety with zod schema validation
 * - Memory optimization with configurable levels
 * - Function inference and automatic schema generation
 * - Support for both sync and async functions
 * - Direct result handling for agent answers
 */
export declare class StructuredTool<TInput, TOutput> extends Tool<TInput, TOutput> {
    private readonly func;
    private readonly outputSchema?;
    private readonly resultAsAnswer;
    private readonly memoryOptimizationLevel;
    /**
     * Static method to create a StructuredTool from a function
     * Auto-infers types and creates schemas based on TypeScript type information
     */
    static fromFunction<TInput extends Record<string, any>, TOutput>(func: (args: TInput, options?: {
        signal?: AbortSignal;
    }) => Promise<TOutput> | TOutput, options?: FromFunctionOptions<TInput, TOutput>): StructuredTool<TInput, TOutput>;
    constructor(options: StructuredToolOptions<TInput, TOutput>);
    /**
     * Execute the tool with the given input
     * Supports both sync and async functions with proper error handling
     */
    protected _execute(input: TInput, options?: {
        signal?: AbortSignal;
    }): Promise<TOutput>;
    /**
     * Execute with memory optimizations based on configuration level
     * Higher levels apply more aggressive optimizations
     */
    private executeWithOptimizations;
    /**
     * Check if this tool returns direct answers
     */
    isDirectAnswer(): boolean;
    /**
     * Get the schema for this tool's arguments
     */
    getArgSchema(): z.ZodType<TInput>;
    /**
     * Get the JSON schema for arguments (for LLM consumption)
     */
    getArgSchemaForLLM(): Record<string, any>;
}
/**
 * Create a structured tool from a function
 * Factory function optimized for memory efficiency and ease of use
 *
 * @param options Tool configuration options
 * @returns A new StructuredTool instance
 */
export declare function createStructuredTool<TInput, TOutput>(options: StructuredToolOptions<TInput, TOutput>): StructuredTool<TInput, TOutput>;
/**
 * Create a structured tool from a function with optimized memory usage
 * This is a more convenient API that infers types from the function signature
 *
 * @param func The function to create a tool from
 * @param options Optional configuration
 * @returns A new StructuredTool instance
 *
 * @example
 * ```typescript
 * // Create a simple addition tool
 * const addTool = createToolFromFunction(
 *   async ({ a, b }: { a: number, b: number }) => a + b,
 *   {
 *     name: 'add',
 *     description: 'Add two numbers together',
 *     resultAsAnswer: true
 *   }
 * );
 * ```
 */
export declare function createToolFromFunction<TInput extends Record<string, any>, TOutput>(func: (args: TInput, options?: {
    signal?: AbortSignal;
}) => Promise<TOutput> | TOutput, options?: FromFunctionOptions<TInput, TOutput>): StructuredTool<TInput, TOutput>;
/**
 * Create a batch of tools from functions with shared configuration
 * Optimized to minimize memory overhead when creating multiple tools
 *
 * @param functionsMap Record of functions to create tools from
 * @param sharedOptions Options applied to all tools
 * @returns Record of tools with the same keys as the input
 */
export declare function createToolsFromFunctions<T extends Record<string, (args: any, options?: {
    signal?: AbortSignal;
}) => any>>(functionsMap: T, sharedOptions?: Omit<FromFunctionOptions<any, any>, 'name' | 'description'>): {
    [K in keyof T]: StructuredTool<Parameters<T[K]>[0], Awaited<ReturnType<T[K]>>>;
};
//# sourceMappingURL=StructuredTool.d.ts.map