Actions et entrées exactes

Certains clients doivent envoyer une entrée exacte plutôt qu’une phrase en langage naturel.

Utilisez les fonctions d’action et de code des SDK pour les sélections, les appuis sur des boutons, les lectures optiques, les numéros de série, les codes de confirmation et les autres valeurs exactes.

Quelle fonction utiliser

Fonction	Idéale pour
send_action	Les charges utiles texte pour les actions d’interface, les choix de menu et les commandes d’outils.
send_code	Les codes-barres, les valeurs QR, les numéros de série, les NIP et les valeurs exactes saisies.
ask	Les requêtes en langage naturel qui doivent renvoyer une réponse normalisée.
send_utterance	Les événements d’énoncé de plus bas niveau, quand l’application gère déjà les réponses elle-même.

Charges utiles d’action

Utilisez les actions quand le client sait déjà ce qui s’est passé. send_action prend une seule charge utile de type chaîne, plus un titre et un contexte facultatifs. Utilisez la charge utile exacte renvoyée par un choix ou attendue par la compétence destinataire; la fonction n’accepte pas un nom d’action et un dictionnaire séparés.

client.send_action(
    '/choose{"id":"42"}',
    title="Choose saved address",
    session_id="checkout-session",
)

Cet exemple suppose que la compétence comprend /choose suivi de JSON. Le SDK envoie cette chaîne comme un énoncé et consigne les métadonnées de l’action dans le contexte de la requête. Utilisez plutôt emit pour une compétence qui attend un événement nommé avec une charge utile objet.

Charges utiles de code

Utilisez les codes pour éviter que la transcription de la parole modifie une valeur lue ou saisie. send_code retire les espaces au début et à la fin, puis envoie la chaîne restante avec input.exact: true; la fonction n’analyse pas les nombres et ne retire pas les zéros de tête. Ne transformez pas la valeur en phrase, sauf si la compétence s’y attend.

client.send_code(
    "SN-001-XYZ",
    kind="barcode",
    label="device serial",
    session_id="maintenance-session",
)

Les deux fonctions envoient un événement sans attendre la réponse de la compétence. Connectez le client et installez tout écouteur de réponse avant l’envoi quand votre application a besoin d’une réponse. Utilisez ask pour le flux intégré de requête et réponse. MCP expose les mêmes entrées texte sous thalovant_send_action.payload et thalovant_send_code.value.

Règles de conception

1. Utilisez les énoncés pour la langue. Les entrées en langage naturel doivent passer par ask ou send_utterance.
2. Utilisez les actions pour les commandes connues. Les boutons et les choix doivent envoyer des noms d’action stables.
3. Utilisez les codes pour les valeurs lues ou saisies. Préservez les zéros de tête et tenez compte du retrait des espaces par la fonction.
4. Incluez le contexte de session. Les actions et les codes appartiennent souvent à un parcours visible.
5. Journalisez les ID de requête. Les entrées exactes sont plus faciles à déboguer quand chaque envoi a une clé de traçage.

Entrées courantes

Bouton

Envoyez un nom d’action comme /next, /cancel ou /choose.

Sélection

Envoyez l’ID choisi, son libellé et la liste d’origine comme charge utile d’action structurée.

Code-barres

Envoyez la valeur brute lue par send_code avec kind="barcode".

NIP

Envoyez la valeur exacte saisie par send_code avec un ID de requête.

Attention

N’envoyez pas de numéros de carte de paiement, de mots de passe ni d’autres secrets sensibles comme entrées exactes.