plazbot/dist/workers/types/tool.d.ts

Official Plazbot SDK for creating AI agents for WhatsApp, portals, and developers.

import type { PlzContext } from './context';
/** Tipos de datos soportados para parametros de tools */
export type ToolParameterType = 'string' | 'number' | 'boolean' | 'date' | 'email' | 'phone';
/** Definicion de un parametro individual */
export interface ToolParameter {
    type: ToolParameterType;
    description?: string;
    /** Pregunta que el agente hara al usuario si falta este dato */
    promptHint?: string;
    required?: boolean;
    /** Valores permitidos (enum) */
    enum?: string[];
    /** Valor por defecto */
    default?: unknown;
}
/** Accion que el worker puede ejecutar sobre el contacto */
export interface ToolAction {
    type: 'tag' | 'removeTag' | 'setVariable' | 'setStage' | 'setSegmentation' | 'assignAgent' | 'resolve';
    value: string;
    /** Solo para setVariable: codigo de la variable */
    code?: string;
}
/** Respuesta que retorna el handler de un tool */
export interface ToolResponse {
    /** Texto que el agente usara para formular su respuesta */
    result: string;
    /** Datos estructurados opcionales */
    data?: Record<string, unknown>;
    /** Acciones automaticas sobre el contacto */
    actions?: ToolAction[];
}
/** Configuracion completa de un tool */
export interface ToolConfig<T extends Record<string, unknown> = Record<string, unknown>> {
    /** Nombre unico del tool (slug) */
    name: string;
    /** Referencia que el agente IA usa para saber cuando invocar este tool */
    reference: string;
    /** Definicion de parametros que el agente extraera de la conversacion */
    parameters: {
        [K in keyof T]: ToolParameter;
    };
    /** Handler que se ejecuta cuando el agente invoca el tool */
    handler(input: T, plz: PlzContext): Promise<ToolResponse>;
}
/** Tool definido y listo para desplegar */
export interface ToolDefinition<T extends Record<string, unknown> = Record<string, unknown>> {
    __type: 'tool';
    config: ToolConfig<T>;
}