Événements et sortie enrichie

Une réponse, c’est plus que la phrase que prononce le hub. À côté du texte, il peut y avoir des éléments d’affichage pour un écran, les événements bruts que le runtime a émis pendant son travail, et une décision de politique quand l’accès a été refusé. Lisez d’abord les champs normalisés : ils suffisent à la plupart des applications. Tournez-vous vers les champs plus riches quand vous en avez besoin, pas avant.

Ce que contient une réponse

Sortie	À utiliser pour
text	Le texte de réponse rassemblé, qui peut contenir du SSML.
display_text	Le texte de réponse sans balisage, pour l’affichage visuel.
display_items()	Le texte, les choix, les tableaux, les images et les pièces jointes.
events	Les événements rassemblés, avec leurs name, data et context.
handled, ok et failure_event	Si la requête s’est terminée, et tout échec du runtime consigné.

Ce sont les noms en Python; Node les écrit displayText, displayItems() et failureEvent, et son tableau events porte les mêmes événements. Rien qui s’appelle speech, raw_event ou policy_denied n’existe sur une réponse, dans aucun SDK, quoi qu’en laissent croire d’anciens exemples. La page du SDK de votre langage donne l’API exacte.

Noms d’événements

Quand un langage expose des constantes pour ces noms, utilisez-les. Les noms sous-jacents ne changent pas d’un SDK à l’autre.

Événement	Signification
recognizer_loop:utterance	Un client envoie un énoncé de l’utilisateur.
speak	Le hub renvoie de la parole ou un texte de réponse.
ovos.intent.unmatched	Une requête ne correspond à aucune compétence (nom OVOS actuel).
complete_intent_failure	Une requête ne correspond à aucune compétence (ancien nom Mycroft, encore émis par des runtimes plus anciens).
hive.policy.denied	La politique d’accès a bloqué la requête.
mycroft.skill.handler.start	Un gestionnaire de compétence a démarré.
mycroft.skill.handler.complete	Un gestionnaire de compétence a terminé.

Éléments d’affichage

Les éléments d’affichage existent pour qu’une application dotée d’un écran n’ait jamais à analyser la phrase prononcée pour y trouver le tableau qu’elle contient.

Texte

Un paragraphe, un titre, un sous-titre ou un message d’état.

Choix

Une option sélectionnable qui peut renvoyer à send_action.

Tableau

Des lignes et des colonnes pour une sortie de type comparaison, état ou inventaire.

Image

Une URL ou une référence de pièce jointe que le client peut afficher.

Exemple en Python

from thalovant import ThalovantClient

with ThalovantClient.from_identity_file("_identity.json") as client:
    reply = client.ask("Show the next maintenance steps.")

print(reply.display_text)

for item in reply.display_items():
    print(item.kind, item.text, item.data, item.url)

Un élément choices garde ses choix dans item.data; chacun peut porter un title et un payload de type chaîne, et c’est cette charge utile que l’application passe à send_action quand la personne fait ce choix. Affichez les types que votre application comprend et ignorez les autres.

Comportement du client

Cas	Traitement recommandé
Un texte de réponse est présent	Affichez display_text dans un client visuel; traitez text ou utterances selon la prise en charge du SSML par votre moteur de rendu vocal.
display_items() renvoie des éléments	Affichez les éléments que le client comprend et ignorez les types inconnus.
Un événement hive.policy.denied arrive	Affichez un message de refus sans risque et gardez l’ID de la requête pour le dépannage.
Une requête lève une erreur du runtime	Traitez-la comme une requête échouée; certains échecs sont levés avant qu’un objet de réponse existe. L’inventaire des intentions a aussi une erreur de politique typée.
Une réponse n’a aucune sortie utile	Vérifiez handled, failure_event et les noms d’événements avant de la présenter comme une réponse. Caviardez les données d’événement avant de journaliser des diagnostics.

Astuce

Les types d’éléments d’affichage inconnus doivent être ignorés, et non traités comme des erreurs fatales. Cela garde les anciens clients compatibles avec les nouvelles compétences.