Outils de classe Apex

Qu’est-ce qu’un outil de classe Apex ?

Classe Apex est le troisième type du générateur d’outils REDA AI, avec Modèle SOQL et Mappage de fichiers. Choisissez-le lorsque :

• Le traitement exige une logique conditionnelle, plusieurs étapes ou des écritures dans plusieurs objets.
• L’outil doit appeler un système externe.
• Vous devez rapprocher les données d’enregistrements existants, dédupliquer ou appliquer des règles métier avant l’écriture.
• La structure des données extraites d’un fichier dépasse les possibilités d’une correspondance déclarative.

La plateforme gère le contrat avec l’agent : schéma JSON, validation des entrées, traitement des erreurs, confirmation des actions, journalisation et formatage des résultats. Votre classe réalise le traitement métier et reste responsable de ses contrôles d’accès.

L’interface d’exécution

Chaque outil Apex implémente une même interface globale :

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

Deux paramètres et une valeur de retour :

• toolName : nom développeur de la définition d’outil à l’origine de l’appel. Utilisez-le si une classe implémente plusieurs outils et doit choisir le traitement correspondant.
• input : paramètres fournis par l’agent et validés selon votre Schéma d'entrée (JSON), avec la clé _channel décrite ci-dessous.
• Valeur de retour : dépend de la catégorie ; consultez Contrat de retour.

Connaître le canal d’exécution

Un même outil peut être appelé depuis une conversation interne dans Salesforce, un widget public ou un agent API autonome exécuté la nuit. Il est souvent utile d’adapter le résultat au canal. REDA AI ajoute donc des clés fournies par le serveur dans input avant l’appel, à commencer par le 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);          // no internal notes, no margins
        }
        return fullInternalDetail(input);
    }
}

Les valeurs possibles sont Internal, External_Widget, Community et API, comme dans le champ Canal. Utilisez les constantes REDAAIConstants.CHANNEL_* plutôt que de recopier les valeurs. La plateforme fournit cette valeur, pas l’agent. Si le modèle tente de définir _channel, REDA AI l’écrase ; si le canal ne peut pas être résolu, la clé est supprimée. Une clé _channel présente est donc fiable ; son absence signifie « inconnu », jamais « Interne ».

Deux autres clés sont transmises de la même manière, avec la même garantie d’écrasement ou de suppression. La plateforme les fournit et ignore toute valeur proposée par le modèle :

En l’absence de conversation ou d’agent dans le contexte, les clés sont supprimées plutôt que de conserver une valeur périmée. Comme pour _channel, une valeur présente est fiable et son absence signifie « inconnu ».

Les outils existants n’ont pas besoin d’être modifiés. Un outil qui ne lit pas _channel ignore simplement cette entrée supplémentaire et conserve son comportement.

Champs de la définition de l’outil

Créer la classe Apex

Exemple minimal d’un exécuteur de catégorie Action créant un enregistrement :

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()
            };
        }
    }
}

Points à relever :

• La classe est global. Public ne suffit pas : la plateforme l’instancie via une interface globale pour que les utilisateurs du package puissent fournir des implémentations dans leur propre espace de noms.
• La classe déclare with sharing. La plateforme n’impose pas le partage à l’intérieur de votre code ; l’exécuteur est responsable de son modèle d’accès aux données.
• La clause insert as user exécute le DML en mode utilisateur et applique la sécurité au niveau des champs. C’est le choix recommandé par défaut, sauf motif explicite d’élévation.
• Les erreurs sont interceptées et renvoyées de manière structurée. Les exceptions non interceptées sont journalisées, mais une réponse explicite donne à l’agent une information utile à transmettre.

Contrat de retour

La structure de retour dépend de Catégorie :

Outils Apex pilotés par des fichiers

Activer Le traitement des fichiers avec true permet à l’agent de fournir les données extraites du fichier selon votre schéma. Le modèle extrait d’abord une structure, puis celle-ci est transmise à votre exécuteur dans la Map input.

Ce fonctionnement convient aux fichiers non tabulaires — PDF, images et documents mixtes — pour lesquels la correspondance simple entre colonnes et champs ne suffit pas.

Concevoir le schéma d’extraction

Le schéma décrit la structure des données extraites, pas le fichier brut. Pour un document de plusieurs lignes, l’agent peut produire :

{
  "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" }
  ]
}

Votre exécuteur parcourt ensuite rows, recherche les enregistrements correspondants, applique les règles métier nécessaires et écrit dans Salesforce.

Lorsque Le traitement des fichiers est activé dans le générateur d’outils, le générateur IA peut produire un exemple de structure extraite à partir d’un fichier représentatif. Utilisez cet exemple comme contrat pour écrire votre classe.

Nommage, package et résolution

• Visibilité de la classe : la classe et sa méthode execute doivent toutes deux être global, pas public.
• Implémentation : la classe doit implémenter redaai.REDAAI_Executable.
• Longueur du nom : jusqu’à 255 caractères dans le champ Classe d'exécuteur testamentaire.
• Une classe pour plusieurs outils : un exécuteur peut servir plusieurs définitions et adapter son comportement selon toolName.

Sécurité et gouvernance

• Vous êtes responsable de la sécurité du code. La plateforme n’impose pas la FLS ou le partage à l’intérieur de votre classe. Utilisez with sharing et les approches USER_MODE / as user, sauf raison explicite d’élévation.
• Reconnaissance de responsabilité à l’enregistrement. Lors du premier enregistrement d’un outil personnalisé — Apex, modèle SOQL ou correspondance de fichiers — vous acceptez une reconnaissance de responsabilité partagée pour sa sécurité, ses autorisations CRUD/FLS, son périmètre de données, la validation des entrées et sa conformité. REDA AI peut en effet l’appeler de façon autonome, y compris sur les canaux communauté et externe sans confirmation humaine. Votre acceptation, avec nom et horodatage, est enregistrée sur l’outil et complète le contrat-cadre de service REDA AI. Les outils intégrés du package ISV sont exemptés ; l’acceptation est conservée après modification et n’est requise qu’une fois par outil.
• Les entrées sont validées. La plateforme contrôle input selon le schéma avant l’appel de la classe. Effectuez néanmoins des conversions de type défensives et vérifiez les contraintes métier dans votre code.
• La confirmation reste applicable. Pour la catégorie Action, les paramètres de confirmation et d’exécution automatique déterminent la carte sur le canal interne. Les canaux externes et API suivent leurs règles propres.
• Les erreurs sont journalisées. Les exceptions non interceptées créent des incidents REDA AI avec la conversation, l’outil et le contexte technique. Une réponse d’erreur claire reste préférable pour l’utilisateur ; le journal sert de filet de sécurité.
• Exécution synchrone. Les outils Apex s’exécutent directement pendant le tour de l’agent. Pour un traitement long, votre exécuteur doit lancer une tâche Queueable, Schedulable ou par lot, puis annoncer immédiatement que le travail a commencé.

Quand choisir Apex

Bonnes pratiques

Rédigez une description précise. L’agent choisit l’outil principalement à partir de sa description. Expliquez ce qu’il fait, ce qu’il ne fait pas et ses conditions préalables.

Délimitez les schémas. Utilisez required, enum, maxLength et des types explicites. Un schéma précis réduit les entrées inattendues dans votre code.

Renvoyez toujours un message utile. Même en cas d’échec, renvoyez success: false et un message compréhensible. L’agent le transmet à l’utilisateur ; une erreur opaque rend la conversation confuse.

Terminez rapidement ou mettez en attente et annoncez-le. Évitez de bloquer le tour avec un appel externe lent. Effectuez le travail rapidement ou lancez un traitement asynchrone en indiquant qu’il est en cours.

Testez avec l’aperçu du générateur. Le panneau d’impact montre le schéma, la carte d’action et le contrat d’exécution. Repérez les écarts avant la première conversation réelle.

Questions fréquentes

Prochaines étapes

Consultez Outils de modèle SOQL pour une simple requête paramétrée, ou Traitement des documents pour comprendre le parcours des fichiers dans REDA AI.