Herramientas de clases Apex

¿Qué es una herramienta de clase Apex?

Una herramienta de clase Apex es el tercer tipo de herramienta que puedes crear en el Generador de herramientas de REDA AI, junto a las de plantilla SOQL y las de mapeo de archivos. Recurre a ella cuando:

• El trabajo requiere lógica condicional, varios pasos o escrituras en más de un objeto
• Necesitas hacer una llamada externa a otro sistema como parte de la herramienta
• Quieres conciliar con registros existentes, eliminar duplicados o aplicar reglas de negocio antes de escribir
• Estás configurando una extracción a partir de un archivo cuya estructura de datos es demasiado rica para un mapeo declarativo

La plataforma se encarga del contrato con el agente: el JSON Schema, la validación de la entrada, el envoltorio de errores, la confirmación de acciones, el registro de auditoría y el formato del resultado. Tu clase Apex solo se ocupa del trabajo en sí.

La interfaz del ejecutor

Cada herramienta de clase Apex implementa una única interfaz global:

global interface REDAAI_Executable {
    Object execute(String toolName, Map<String, Object> input);
}

Dos parámetros, un valor de retorno:

• toolName — el nombre de desarrollador de la Definición de herramienta que originó esta llamada. Úsalo si una misma clase implementa varias herramientas y necesita ramificar según quién la invoca.
• input — los parámetros que proporcionó el agente, validados contra el JSON de tu Esquema de entrada, más la clave _channel que se describe más abajo.
• Valor de retorno — depende de la categoría de la herramienta (consulta Contrato de retorno más abajo).

Saber en qué canal te estás ejecutando

La misma herramienta puede ser invocada por un agente con el que un compañero conversa dentro de Salesforce, por un widget público de un sitio web o por un agente de API sin supervisión que se ejecuta de madrugada, y a menudo lo correcto es comportarse de forma distinta en cada caso. Por eso REDA AI añade un conjunto de claves proporcionadas por la plataforma al mapa input antes de llamarte, empezando por el canal:

global class OrderLookupTool implements REDAAI_Executable {
    global Object execute(String toolName, Map<String, Object> input) {
        String channel = (String) input.get('_channel');   // 'Internal' | 'External_Widget' | 'Community' | 'API'

        if (REDAAIConstants.CHANNEL_EXTERNAL_WIDGET.equals(channel)) {
            return summaryForPublicVisitor(input);
        }
        return fullInternalDetail(input);
    }
}

El valor es Internal, External_Widget, Community o API — los mismos valores que usa el campo Canal, así que compara con las constantes REDAAIConstants.CHANNEL_* en lugar de escribir el literal. Lo establece la plataforma, no el agente. Si el modelo intenta proporcionar _channel por su cuenta, REDA AI lo sobrescribe; y cuando el canal realmente no puede resolverse, la clave se elimina por completo en lugar de dejarla con un valor inventado por el modelo. Así, un _channel presente siempre es fiable, y su ausencia significa «desconocido», nunca «Internal».

Dos claves más llegan de la misma forma, con la misma garantía de sobrescritura y eliminación — la plataforma siempre las proporciona, y cualquier valor que el modelo intente establecer se descarta:

Ambas se eliminan en lugar de quedarse obsoletas cuando no hay conversación o agente en contexto — así que, igual que con _channel, un valor presente es fiable y su ausencia significa «desconocido».

Las herramientas existentes no necesitan ningún cambio. Una herramienta que nunca lee _channel simplemente ignora una entrada más del mapa y se comporta exactamente igual que antes.

Campos de la Definición de herramienta

Crear la clase Apex

Un ejecutor mínimo de tipo Action que crea un único registro:

global with sharing class MyToolExecutor implements redaai.REDAAI_Executable {
    global Object execute(String toolName, Map<String, Object> input) {
        try {
            String name = (String) input.get('account_name');
            Account a = new Account(Name = name);
            insert as user a;

            return new Map<String, Object>{
                'success' => true,
                'message' => 'Account created.',
                'recordId' => a.Id
            };
        } catch (Exception e) {
            return new Map<String, Object>{
                'success' => false,
                'message' => e.getMessage()
            };
        }
    }
}

Algunos detalles a tener en cuenta:

• La clase es global. Public no sirve: la plataforma instancia la clase a través de la interfaz global para que los consumidores de paquetes gestionados puedan registrar implementaciones desde sus propios espacios de nombres.
• La clase se declara with sharing. La plataforma no aplica el uso compartido por ti; el ejecutor es responsable del acceso a los datos que desee.
• La cláusula insert as user ejecuta el DML en modo de usuario para que se aplique la seguridad a nivel de campo. Es el valor predeterminado recomendado, salvo que tengas una razón específica para escalar privilegios.
• Los errores se capturan y se devuelven como una respuesta estructurada. Las excepciones no controladas igualmente se registran en el registro de incidentes, pero una respuesta limpia le da al agente algo útil que responderle al usuario.

Contrato de retorno

La estructura del retorno depende de la Categoría de la herramienta:

Herramientas Apex basadas en archivos

Establecer Procesamiento de archivos en true cambia lo que el agente te pasa. En lugar de parámetros de forma libre, la plataforma primero le pide al modelo que extraiga datos estructurados del archivo cargado usando el esquema que definiste, y luego le entrega esos datos extraídos a tu ejecutor como el Map de input.

Eso es lo que hace de las herramientas de clases Apex el patrón adecuado para trabajar con archivos no tabulares — PDF, imágenes, documentos mixtos — donde el modelo plano de columna a campo del mapeo de archivos no es suficiente.

Diseñar el esquema de entrada para la extracción

El esquema de entrada describe la estructura extraída, no el archivo en bruto. Para un documento de varias filas, el agente podría producir algo como:

{
  "rows": [
    { "external_id": "INV-1001", "amount": 250.00, "due_date": "2026-05-01" },
    { "external_id": "INV-1002", "amount": 980.50, "due_date": "2026-05-15" }
  ]
}

Tu ejecutor luego itera ese arreglo rows, busca los registros coincidentes, aplica las reglas de negocio que necesites y escribe de vuelta en Salesforce.

Cuando creas la herramienta en el Generador de herramientas con Procesamiento de archivos activado, el Generador de IA puede producir una muestra de la estructura de datos extraída a partir de un archivo representativo que cargues. Úsala como el contrato contra el cual escribes tu Apex.

Nombres, empaquetado y resolución

• Visibilidad de la clase — tanto la clase como su método execute deben declararse global (no public).
• Implementación — debe implementar redaai.REDAAI_Executable.
• Longitud del nombre de la clase — hasta 255 caracteres en el campo Clase ejecutora.
• Una clase, varias herramientas — un mismo ejecutor puede respaldar varias Definiciones de herramienta y cambiar de comportamiento según toolName.

Seguridad y gobernanza

• Tú eres responsable de la seguridad. La plataforma no aplica la FLS ni el uso compartido dentro de tu clase. Usa with sharing y los patrones USER_MODE / as user, salvo que tengas una razón explícita para escalar privilegios.
• Reconocimiento de seguridad al guardar. La primera vez que guardas una herramienta personalizada (Apex, plantilla SOQL o mapeo de archivos) en el Generador de herramientas, aceptas un reconocimiento de responsabilidad compartida en el que confirmas que eres responsable de su seguridad, sus permisos (CRUD/FLS), la delimitación de datos, la validación de entradas y el cumplimiento legal, porque REDA AI puede invocarla de forma autónoma, incluso en los canales de Comunidad y externos sin un paso de confirmación humana. Tu aceptación (nombre + marca de tiempo) se registra en la herramienta y complementa el Contrato Marco de Servicios de REDA AI. Las herramientas integradas (de ISV) están exentas; aceptas una sola vez por herramienta y esa aceptación se conserva entre ediciones.
• La entrada se valida. La plataforma valida input contra tu esquema antes de invocar tu clase — puedes confiar en los nombres y tipos de campo que declaraste, pero siempre convierte los valores de forma defensiva.
• La confirmación de acción sigue aplicándose. Establecer la Categoría en Action significa que el agente muestra una tarjeta de confirmación antes de llamar a tu clase, a menos que el agente esté configurado para ejecución automática.
• Los errores terminan en incidentes. Las excepciones no controladas se capturan como registros de incidentes de REDA AI con la conversación, el nombre de la herramienta y el contexto de la pila. Devolver una respuesta de error limpia es más amigable; el registro de incidentes es la red de seguridad.
• Ejecución sincrónica. Las herramientas de clases Apex se ejecutan de forma sincrónica como parte del turno del agente. Los trabajos de larga duración debe encolarlos tu ejecutor (Queueable, Schedulable, batch) y la respuesta inmediata debe indicarle al usuario que el trabajo ya comenzó.

Cuándo recurrir a una herramienta Apex

Prácticas recomendadas

Haz que la descripción sea implacable. La decisión del agente de llamar a tu herramienta depende casi por completo de la descripción de la herramienta. Detalla qué hace la herramienta, qué no hace y cualquier condición previa.

Mantén los esquemas ajustados. Usa required, enum, maxLength y tipos explícitos. Cuanto más ajustado sea el esquema, menos sorpresas le llegarán a tu Apex.

Devuelve siempre un mensaje útil. Incluso ante un fallo, devuelve success: false y un message legible para las personas. El agente le lee el mensaje al usuario; los errores opacos generan conversaciones confusas.

Mantente sincrónico, o encola e informa. No bloquees el turno del agente con una llamada externa lenta. O termina rápido, o encola el trabajo asíncrono y devuelve una respuesta que le indique al usuario que está en curso.

Prueba con el panel de vista previa del Generador de herramientas. El panel de impacto en vivo muestra el esquema de entrada, la tarjeta de acción y el contrato de ejecución que verá el agente — detecta ahí las discrepancias antes de la primera conversación real.

Preguntas frecuentes

Próximos pasos

Lee Herramientas de plantillas SOQL para el patrón más ligero cuando todo lo que necesitas es una consulta parametrizada, o Procesamiento de documentos para tener una visión más amplia de cómo fluyen los archivos por REDA AI.