Référence des outils intégrés

Comment lire cette référence

Chaque outil est décrit selon les mêmes critères. Les canaux indiqués constituent une référence de configuration : vérifiez la définition de l’outil dans votre version installée, car les métadonnées et les restrictions peuvent varier.

• Catégorie : Tool pour la lecture seule ; Action pour les opérations qui modifient des données Salesforce.
• Confirmation : indique si l’outil demande une carte de confirmation sur le canal interne. Les exceptions et les autres canaux sont détaillés ci-dessous ; les outils de lecture n’en demandent jamais.
• Canaux : canaux de déploiement autorisés. Certains outils, comme la suppression et les notifications internes, sont réservés aux utilisateurs internes Salesforce.
• Entrées par lot : possibilité de transmettre plusieurs entrées dans un même appel pour réduire les allers-retours du modèle.
• Ancien niveau : valeur historique, désormais ignorée à l’exécution. Consultez Chargement des outils et coût.

Les outils intégrés appliquent CRUD, FLS et partage avec les autorisations de l’utilisateur. L’exception Contexte d'exécution = Système sur le canal API élève l’accès aux objets et champs, sans élargir le partage des enregistrements.

Outils de lecture

Les outils de lecture récupèrent des données et renvoient du JSON à l’agent. Ils n’écrivent rien et ne demandent donc pas de confirmation.

soql_query

Exécute une requête SELECT en mode utilisateur avec CRUD, FLS et partage, sous réserve de l’exception API décrite ci-dessus. La plateforme ajoute une limite de lignes si elle manque et limite la longueur du résultat sérialisé. Les agrégats et regroupements sont exemptés de limite automatique pour préserver les totaux et groupes. Utilisez le mode par lot lorsque plusieurs requêtes sont nécessaires dans un tour pour réduire les allers-retours.

describe_object

Renvoie le schéma d’un ou plusieurs objets : noms API des champs, libellés, types, références aux listes de sélection et relations. Le résultat est mis en cache pendant la transaction pour éviter de répéter la description. Les appels d’outils et leur contenu continuent à participer au coût de la conversation. Préférez le mode par lot pour plusieurs objets liés.

count_records

Renvoie le nombre d’enregistrements d’un objet, éventuellement filtré par WHERE. Plus économique que soql_query si seul un nombre est nécessaire. Le widget externe n’y a pas accès ; les autres canaux autorisés figurent dans le tableau.

get_record

Renvoie un enregistrement à partir de son identifiant. Sans fields, la plateforme renvoie jusqu’à cinquante champs lisibles. Utilisez-le lorsque l’identifiant est déjà connu et que seules les valeurs actuelles sont nécessaires.

get_picklist_values

Renvoie les valeurs actives d’une liste de sélection avec leurs libellés, valeurs API et indicateur de valeur par défaut. Utile avant d’écrire dans ce champ.

get_record_types

Renvoie les types d’enregistrement actifs d’un objet. Utilisez-le avant create_record si l’objet cible possède plusieurs types et que l’agent doit choisir le bon.

Outils d’action

Les outils d’action modifient l’état de Salesforce. Sur le canal interne, ceux soumis à confirmation affichent une carte avant exécution. Sur les canaux externe et communauté, les actions autorisées s’exécutent sans carte puis l’agent annonce le résultat. Sur API / Flow, Auto Execute Actions contrôle l’exécution automatique. Consultez Confirmation des actions pour les exceptions et le fonctionnement complet.

create_record

Crée un enregistrement avec les valeurs indiquées. Les validations, champs obligatoires et contrôles d’accès applicables s’exécutent ; un échec produit une erreur structurée pour l’agent.

update_record

Modifie un enregistrement existant à partir de son identifiant. En mode utilisateur, seuls les champs modifiables sont changés ; tenez compte du contexte d’exécution API configuré.

delete_record

Supprime un enregistrement par son identifiant. Réservé au canal interne, car l’opération est destructive, il exige une confirmation. La suppression standard place normalement l’enregistrement dans la corbeille ; les possibilités de restauration restent celles de Salesforce.

create_task

Crée une tâche Salesforce. Elle est affectée par défaut à l’utilisateur d’exécution ; utilisez assigned_to pour choisir une autre personne.

create_event

Crée un événement Salesforce avec début et fin. L’utilisateur d’exécution en est propriétaire.

send_email

Envoie un e-mail par Salesforce au nom de l’utilisateur. L’agent doit d’abord retrouver l’adresse du destinataire sur un contact ou une piste. related_to_id rattache l’e-mail à l’historique d’un enregistrement ; group_key regroupe plusieurs e-mails sortants dans une même entrée d’audit.

Choisir l’identité de l’expéditeur. Trois entrées facultatives sont pilotées par les instructions de l’agent. from_address indique une adresse e-mail de l’organisation, déjà créée et vérifiée dans Configuration. Si aucune correspondance n’est trouvée, l’e-mail part avec l’expéditeur par défaut et l’écart est consigné. sender_display_name définit le nom visible, uniquement en l’absence d’adresse de l’organisation. reply_to définit l’adresse de réponse ; une adresse raccordée au routage entrant permet de réintégrer la réponse dans la conversation. Sans ces entrées, le comportement existant est conservé. Consultez E-mails sortants.

Renseigner vos propres champs sur l’e-mail. Chaque envoi crée un EmailMessage. Si vous avez ajouté des champs personnalisés, comme une catégorie, un code de campagne ou un indicateur de service, field_values permet à l’agent de les remplir dès l’envoi, sans mise à jour ultérieure. Utilisez une correspondance de noms API vers leurs valeurs, par exemple {"Outreach_Category__c": "Renewal", "Campaign_Code__c": "Q3-RENEW"}. Trois règles évitent qu’une valeur produite par le modèle altère les données :

• Champs personnalisés uniquement. Leur nom doit se terminer par __c. Les champs standard tels que Subject, Status et FromAddress sont refusés : l’envoi les détermine, et leur modification fausserait la trace du message réellement transmis.
• Le champ doit exister et être modifiable par l’utilisateur. Son nom est vérifié dans le schéma réel de l’organisation. Un champ inconnu est ignoré, pas deviné.
• Un champ incorrect n’empêche pas l’envoi. Si une valeur ne peut pas être appliquée, l’e-mail est tout de même envoyé et l’agent reçoit la liste des champs renseignés ou ignorés pour annoncer le résultat exact.

Rien n’est automatique : l’agent fournit field_values uniquement si ses instructions le demandent. Les agents existants ne sont donc pas affectés. Pour appliquer les mêmes valeurs à tous les e-mails d’un agent, précisez les champs et valeurs attendus dans ses instructions personnalisées.

send_custom_notification

Envoie une notification dans la cloche Salesforce, pas un e-mail. Utile pour attirer l’attention d’un collègue sur un enregistrement créé ou modifié par l’agent.

link_file_to_record

Associe un fichier chargé à un enregistrement en créant un ContentDocumentLink. Si content_document_id est omis, le dernier fichier chargé dans la conversation est utilisé. C’est l’outil habituel pour rattacher les documents traités aux enregistrements concernés.

schedule_action

Reporte une action à plus tard, selon une date précise, un décalage relatif ou un déclencheur de réponse, par exemple « Envoyer lorsque le contact répond à cet e-mail ». Le travail est conservé dans une action planifiée et exécuté par une tâche planifiée. Consultez Actions planifiées.

Conditions. Les paramètres facultatifs condition_field, condition_operator et condition_value sont revérifiés au moment de l’exécution pour confirmer que la situation attendue reste valable. condition_operator accepte uniquement equals, not_equals, contains, not_contains, is_blank ou not_blank, exactement sous cette forme dans toutes les langues. Toute autre valeur est refusée à la planification. Si la condition ne peut pas être évaluée, l’action est ignorée au lieu d’être exécutée.

get_context_prompts

Récupère les instructions supplémentaires configurées pour l’objet et le type d’un enregistrement, notamment lorsque l’utilisateur mentionne un enregistrement absent du contexte initial. Une liste vide est normale si aucune instruction n’existe. L’agent est invité à ne pas répéter l’appel pour le même enregistrement.

continue_workflow

Demande un seul tour autonome supplémentaire dans une nouvelle transaction. Il convient au scénario écriture, puis appel externe, puis nouvelle écriture : l’agent vient de créer ou modifier un enregistrement et a besoin d’un outil dépendant du résultat enregistré. Le tour suivant s’exécute après validation des changements ; les nouveaux enregistrements et leurs identifiants sont donc disponibles. Ce n’est pas un bouton général pour continuer : l’agent peut déjà lire, raisonner et écrire plusieurs enregistrements dans un tour.

call_agent

Pose une question à un autre agent pendant la conversation et renvoie sa réponse. Un assistant général peut ainsi consulter un spécialiste. L’agent consulté utilise ses propres instructions, outils et accès, s’exécute pour l’utilisateur de l’assistant et ne peut pas effectuer seul de modifications : ses propositions reviennent dans la conversation d’origine pour confirmation. Chaque consultation consomme un tour supplémentaire et possède sa propre conversation.

Un administrateur doit activer Appelable par un agent et Autoriser les requêtes automatisées sur l’agent consulté. Profondeur maximale d'appel d'agents de l’agent appelant limite la profondeur des consultations successives. La disponibilité ne suffit pas : les instructions déterminent quand consulter. Consultez Délégation entre agents.

Disponibilité des canaux en un coup d’œil

Entrées par lot

Trois outils de lecture acceptent plusieurs entrées dans un même appel :

• soql_query : tableau queries, maximum 5
• describe_object : tableau object_names, maximum 5
• count_records : tableau counts, maximum 5

Le mode par lot réduit les allers-retours lorsque l’agent a besoin de plusieurs informations de même nature dans un tour : décrire trois objets liés ou compter des enregistrements selon deux filtres, par exemple. L’entrée unique reste prise en charge ; le mode par lot est facultatif.

Bonnes pratiques

Conservez uniquement les outils utiles. Une liste ciblée rend les conversations plus rapides et prévisibles. Utilisez les exclusions et plafonds pour éviter de charger des outils superflus.

Vérifiez le canal. Un outil réservé au canal interne n’apparaît pas sur un widget externe, même si les autres critères correspondent. Contrôlez la colonne des canaux lorsqu’une capacité semble manquer.

Lisez avant d’écrire. Associez describe_object et get_picklist_values à create_record pour choisir des noms de champs et valeurs valides, et réduire les échecs de validation.

Choisissez l’outil adapté. count_records est plus économique que soql_query si seul un nombre est nécessaire ; get_record convient mieux qu’une requête complète lorsque l’identifiant est déjà connu.

Actions d’e-mail, d’enregistrement et de planification

Les actions d’e-mail distinguent le destinataire Contact ou Piste de l’enregistrement métier associé, acceptent des listes À/Cc et vérifient les cas de refus d’e-mail pris en charge. Un Contact/Piste fourni comme enregistrement associé est traité comme destinataire. Les confirmations montrent les champs non appliqués. Les étapes du plan sont rapprochées une à une et les heures relatives conservent UTC. Les agents désactivés et actions imbriquées non autorisées sont vérifiés avant confirmation. La confirmation de liaison de fichiers réutilise le chemin avec contrôle d’accès. Les nouvelles actions horaires en attente ou replanifiées exigent un processeur disponible ; suivi des réponses et mises à jour normales d’historique/statut restent valides. Les travaux différés utilisent leur propriétaire de planification, sans usurper le demandeur. Les instructions réduisent les doublons via d’autres connecteurs, sans garantir le comportement de l’assistant.

Questions fréquentes

Prochaines étapes

Consultez Chargement des outils et coût pour le modèle de chargement, ou Confirmation des actions pour les règles de confirmation selon l’outil et le canal.