Outils de modèle SOQL

Qu’est-ce qu’un outil de modèle SOQL ?

Modèle SOQL est le plus léger des trois types du générateur d’outils. Utilisez-le lorsque :

• Vous souhaitez que l’agent récupère des données avec une requête que vous maîtrisez entièrement.
• Vous voulez exposer uniquement certains paramètres, sans laisser le modèle écrire librement du SOQL.
• Le résultat est en lecture seule, sans insertion, modification ni suppression.
• Vous ne souhaitez pas écrire de code Apex.

La requête est fixée à la conception. L’agent choisit l’outil à appeler et les valeurs des paramètres déclarés ; il n’édite pas la définition SOQL, l’objet ou les clauses du modèle. Choisissez des paramètres de valeur précisément définis pour conserver ce périmètre.

Fonctionnement d’un modèle SOQL

Écrire le modèle

Les paramètres sont entre accolades et suivent les règles habituelles des identifiants : une lettre ou un trait de soulignement au début, puis des caractères alphanumériques ou des traits de soulignement. Exemple :

SELECT Id, Name, AccountId, StageName, Amount, CloseDate
FROM Opportunity
WHERE StageName = '{stage}'
  AND CloseDate >= {start_date}
  AND CloseDate <= {end_date}
ORDER BY CloseDate ASC

À l’exécution, l’agent fournit stage, start_date et end_date. Les apostrophes de chaque valeur sont échappées avant substitution. Le modèle doit conserver la syntaxe adaptée : guillemets simples pour le texte, syntaxe SOQL appropriée pour les dates et nombres.

Éléments utilisables

• Toute requête SELECT valide, y compris les relations parentes et les sous-requêtes sur les relations enfants
• Requêtes d’agrégation avec COUNT(), SUM() et GROUP BY : la plateforme n’ajoute pas automatiquement de LIMIT aux agrégats ou aux regroupements, pour ne pas tronquer les totaux ou les groupes
• Plusieurs paramètres dans une requête, avec un schéma qui impose des valeurs adaptées à leur emplacement ; évitez de donner au modèle des fragments de structure SOQL libres
• Conditions fixes pour délimiter les données accessibles, par exemple WHERE OwnerId = '{user_id}'

Éléments bloqués

• Les requêtes qui ne sont pas des SELECT : les mots-clés INSERT, UPDATE, DELETE, UPSERT, MERGE et UNDELETE sont refusés à la validation
• Les paramètres attendus mais absents du schéma d’entrée ou sans valeur
• Les modèles dépassant la longueur maximale du champ Modèle SOQL

Champs de la définition de l’outil

Comportement à l’exécution

Échappement et contrôles des requêtes

Chaque valeur passe par l’échappement des apostrophes SOQL avant substitution. La requête obtenue est ensuite contrôlée : elle doit commencer par SELECT et ne contenir aucun des mots-clés DML bloqués. Ces protections n’exemptent pas de définir des paramètres typés et une structure de requête maîtrisée, notamment pour les valeurs qui ne sont pas entre guillemets.

FLS, CRUD et partage

Les requêtes s’exécutent en mode utilisateur. Les objets, champs et lignes inaccessibles à l’utilisateur ne sont pas renvoyés. Il s’agit du même modèle de sécurité que les outils intégrés.

L’exception est un agent avec Contexte d'exécution = Système sur le canal API, dont l’accès aux objets et champs est élevé. Le partage des enregistrements n’est jamais élevé : l’exécution reste with sharing. L’agent peut donc obtenir davantage de colonnes, jamais davantage de lignes grâce à cette élévation.

Limites des résultats

Si le modèle n’a pas de clause LIMIT, la plateforme en ajoute une selon le paramètre Nombre maximal de lignes de requête. Les requêtes d’agrégation et de regroupement en sont exemptées afin de préserver les totaux et groupes. Le résultat sérialisé est aussi limité par Longueur maximale des résultats de requête : les réponses trop volumineuses sont tronquées et signalées pour éviter de saturer le contexte du modèle.

Structure du résultat

L’agent reçoit un objet JSON :

{
  "totalSize": 12,
  "showing": 12,
  "records": [
    { "Id": "006...", "Name": "Acme Renewal", "Amount": 25000 },
    ...
  ]
}

Si l’affichage est limité et que l’agent voit moins de lignes que celles obtenues, un champ note indique le nombre renvoyé et le nombre affiché.

Une requête par appel

Chaque appel d’un modèle SOQL exécute exactement une requête. L’outil intégré soql_query possède un mode par lot permettant plusieurs requêtes en un aller-retour ; les modèles SOQL ne le proposent pas. Pour ce besoin, donnez accès à soql_query ou utilisez un outil de classe Apex.

Sécurité et gouvernance

• Les apostrophes des paramètres sont échappées automatiquement. Conservez dans le modèle les guillemets requis par les littéraux de texte ; la plateforme n’ajoute pas ces guillemets.
• Lecture SELECT uniquement. Les mots-clés DML sont refusés à la validation et de nouveau lors de l’exécution.
• Exécution en mode utilisateur. Les autorisations CRUD, FLS et les règles de partage s’appliquent, sous réserve de l’exception de contexte système sur API expliquée ci-dessus.
• Définition fixée à la conception. L’agent ne peut modifier ni la définition SOQL ni le schéma des paramètres. Un administrateur doit mettre à jour la définition de l’outil.
• Piste d’audit. L’appel et son résultat sont enregistrés dans la conversation et ses messages, avec l’outil utilisé et les paramètres transmis.

Quand choisir un modèle SOQL

Bonnes pratiques

Fixez les limites dans la requête. Intégrez les restrictions de types d’enregistrement, de propriétaire ou de statut dans le modèle plutôt que de compter sur l’agent pour les ajouter.

Donnez des noms explicites aux paramètres. {stage} et {close_date_after} sont plus clairs pour le modèle que {p1} et {p2}. Ces noms figurent dans le schéma qu’il lit.

Incluez les champs nécessaires à la réponse. L’agent ne voit que ce que renvoie SELECT. Si une question probable est « Qui en est propriétaire ? », ajoutez Owner.Name dès maintenant.

Ajoutez un LIMIT explicite pour les résultats ciblés. La limite automatique est un filet de sécurité. Si dix lignes suffisent, indiquez-le dans le modèle.

Testez avant de rendre l’outil disponible. Le générateur permet d’exécuter le modèle avec des valeurs d’exemple et d’examiner la requête substituée, les résultats et les avertissements de validation.

Questions fréquentes

Prochaines étapes

Consultez la Référence des outils intégrés pour les outils fournis par la plateforme, ou Comprendre les champs de contexte pour choisir les données ajoutées automatiquement aux conversations.