Paramètres de personne
Permettez à un outil de recevoir des personnes plutôt que des adresses e-mail, afin que le modèle ne détienne jamais d'adresse et ne puisse désigner que les personnes que l'appelant voit déjà.
Un outil qui envoie un e-mail ou invite des personnes à une réunion a besoin de
leurs adresses e-mail. Déclarez ses paramètres de destinataires en
person:email et le modèle n'a plus besoin d'en connaître une : il désigne une
personne par l'identifiant que renvoie List message recipients, et Scrydon
insère l'adresse de cette personne lorsque l'appel atteint votre outil.
Déclarer un paramètre de personne
Donnez au paramètre type: PERSON_PARAMETER_TYPES.EMAIL et gardez son champ
d'entrée de type chaîne. Placez PERSON_EMAIL_PARAMETER_DESCRIPTION à la fois
sur le paramètre et sur le .describe() du champ d'entrée : seule la
description du champ d'entrée parvient au modèle.
import {
defineTool,
PERSON_EMAIL_PARAMETER_DESCRIPTION,
PERSON_PARAMETER_TYPES,
} from "@scrydon/sdk-authoring/extensions/define";
import { z } from "zod";
const sendMail = defineTool({
id: "send-mail",
name: "Send mail",
description: "Sends an email.",
input: z.object({
to: z.string().describe(PERSON_EMAIL_PARAMETER_DESCRIPTION),
cc: z.string().optional().describe(PERSON_EMAIL_PARAMETER_DESCRIPTION),
subject: z.string(),
body: z.string(),
}),
params: {
to: {
type: PERSON_PARAMETER_TYPES.EMAIL,
required: true,
visibility: "user-or-llm",
description: PERSON_EMAIL_PARAMETER_DESCRIPTION,
},
cc: {
type: PERSON_PARAMETER_TYPES.EMAIL,
visibility: "user-or-llm",
description: PERSON_EMAIL_PARAMETER_DESCRIPTION,
},
},
execute: async (input) => {
// input.to vaut "grace@acme.example, bob@partner.example" : uniquement des adresses.
// ...
},
});Le code de votre outil ne change pas : il reçoit une liste d'adresses e-mail séparées par des virgules, comme sans ce type de paramètre.
Ce que le modèle peut y mettre
Une valeur person:email est une chaîne d'entrées séparées par des virgules.
Chaque entrée est :
- l'identifiant d'une personne, tel que le renvoie List message recipients, ou
- une adresse e-mail que l'on a donnée au modèle, transmise telle quelle.
Une liste peut mélanger les deux. Son ordre est conservé et les espaces autour de chaque entrée sont supprimés. Une liste contient au plus 50 entrées d'au plus 320 caractères chacune.
Ce que Scrydon en fait
Avant l'exécution de votre outil, Scrydon remplace chaque identifiant de personne par l'adresse de cette personne. Il ne le fait que pour les personnes que List message recipients montrerait à la personne appelante dans cette conversation : dans un espace de travail partagé, les personnes de sa liste de membres ; dans un espace de travail personnel, les membres actifs de l'organisation.
L'adresse ne parvient qu'à votre outil. L'entrée du modèle, celle que voient le journal d'audit, la prévention des pertes de données et la carte d'approbation, contient toujours les identifiants. Si une politique de prévention des pertes de données réécrit la valeur, c'est la valeur réécrite qui est envoyée, sans adresse insérée.
Ce que le modèle relit
La même règle s'applique dans l'autre sens. Dans une conversation Cortex, la
sortie d'un outil parvient au modèle avec chaque adresse d'une personne que
List message recipients montrerait à la personne appelante remplacée par
l'identifiant de cette personne. Une valeur telle que
Grace Hopper <grace@acme.example> garde le nom et devient Grace Hopper <id>.
Toute autre adresse reste telle que l'outil l'a renvoyée : une adresse hors de
l'organisation, celle d'une personne absente de l'effectif de l'espace de
travail partagé, ou d'un membre inactif. Seule une valeur de chaîne qui est
entièrement une adresse, ou un nom et une adresse, est modifiée. Le texte libre
et les clés d'objet ne sont jamais modifiés.
La sortie de votre outil reste inchangée partout ailleurs : une étape de workflow, les journaux de l'exécution et le journal d'audit voient ce que votre outil a renvoyé. La sortie d'un appel en échec n'est jamais modifiée. Si la recherche ne peut pas s'exécuter, ou si une sortie nomme plus de 200 adresses, le modèle reçoit la sortie telle que votre outil l'a renvoyée.
Un appelant du SDK de la plateforme demande cette vue avec
outputView: "model" sur action.tools.execute :
const result = await platform.action.tools.execute({
toolId,
input,
idempotencyKey,
outputView: TOOL_OUTPUT_VIEWS.MODEL, // depuis '@scrydon/sdk/platform'
})Sans outputView, la sortie est renvoyée inchangée. Le champ n'est pas transmis
à votre outil et ne fait pas partie de l'idempotence de l'appel.
Quand un appel est refusé
| Code | Quand | Ce qu'on demande au modèle |
|---|---|---|
PERSON_REFERENCE_REQUIRED | Une entrée n'est ni un identifiant de personne ni une adresse e-mail — un simple prénom comme Nathan — ou la liste dépasse sa limite | Rechercher la personne avec List message recipients et rappeler avec son identifiant |
PERSON_REFERENCE_UNRESOLVED | Un identifiant de personne n'est pas joignable d'ici : absent de la liste des membres de l'espace partagé, pas membre actif, dans une autre organisation, ou inconnu | Ne pas réessayer ; demander l'adresse e-mail de cette personne |
Un seul identifiant non résolu refuse tout l'appel, avant l'exécution de votre outil. Le message de refus est le même quelle que soit la raison : un refus ne révèle donc jamais si une personne existe ni où. Les deux codes figurent avec les autres dans Erreurs d'exécution des outils.
Ce qui est enregistré
Chaque paramètre résolu écrit un événement d'audit
extension.person_reference.resolved contenant l'outil, le nom du paramètre et
le nombre d'identifiants et d'adresses qu'il contenait. Un refus écrit
extension.person_reference.refused avec l'outil et le code. Aucun des deux
n'enregistre d'adresse ni d'identifiant de personne.