Événements, contexte et diagnostics

Fait partie de Fonctions des SDK. Chaque appel ci-dessous est montré dans chaque langage qui l’offre.

Attendre un événement

Utilisez cet appel quand un seul événement prouve que la requête est terminée.

Python

from thalovant import EVENT_UTTERANCE_HANDLED

event = client.wait_for_event(EVENT_UTTERANCE_HANDLED, timeout=12)
print(event.text)

Node.js

const event = await client.waitForEvent(EVENT_UTTERANCE_HANDLED, {
  timeoutMs: 12_000,
});
console.log(event.text);

Go

event, err := client.WaitForEvent(ctx, thalovant.EventUtteranceHandled, thalovant.EventOptions{
    Timeout: 12 * time.Second,
})
if err != nil { return err }
fmt.Println(event.Name, event.Text())

Rust

use thalovant::{ListenOptions, EVENT_UTTERANCE_HANDLED};

let event = client.wait_for_event(EVENT_UTTERANCE_HANDLED, ListenOptions::default()).await?;
println!("{} {}", event.name, event.text());

Écouter un flux d’événements

Utilisez les flux d’événements pour les clients de longue durée, l’état en direct, la sortie vocale et les mises à jour de l’interface.

Python

from thalovant import EVENT_SPEAK

for event in client.listen(EVENT_SPEAK, timeout=30, max_events=3):
    print(event.text)

Node.js

const subscription = client.on(EVENT_SPEAK, event => {
  console.log(event.text);
});

// Later, when the listener is no longer needed:
subscription.close();

Go

events, err := client.Listen(ctx, thalovant.EventSpeak, thalovant.ListenOptions{MaxEvents: 3})
if err != nil { return err }
defer events.Close()
for event := range events.C {
    fmt.Println(event.Name, event.Text())
}
if err := events.Err(); err != nil { return err }

Rust

use thalovant::{ListenOptions, EVENT_SPEAK};

let mut events = client.listen(EVENT_SPEAK, ListenOptions {
    max_events: Some(3), ..ListenOptions::default()
}).await?;
while let Some(event) = events.recv().await? {
    println!("{} {}", event.name, event.text());
}

Construire le contexte d’une requête

Le contexte transporte des métadonnées stables sur l’utilisateur, la source, les paramètres régionaux et le traçage, sans modifier l’énoncé.

Python

from thalovant import build_client_context

context = build_client_context(
    user_id="user-42",
    user_name="Ada",
    source="checkout-kiosk",
    platform="kiosk",
    locale="en-US",
    metadata={"trace_id": "req-2026-06-10-001"},
)

reply = client.ask("Show the next instruction.", context=context)
print(reply.text)

Node.js

const context = buildClientContext({}, {
  userId: "user-42",
  userName: "Ada",
  source: "checkout-kiosk",
  platform: "kiosk",
  locale: "en-US",
  channel: "chat",
  metadata: { traceId: "req-2026-06-10-001" },
});

const reply = await client.ask("Show the next instruction.", { context });
console.log(reply.text);

Go

requestContext := thalovant.BuildClientContext(nil, thalovant.ClientContextOptions{
  UserID:   "user-42",
  UserName: "Ada",
  Source:   "checkout-kiosk",
  Platform: "kiosk",
  Locale:   "en-US",
  Channel:  "chat",
  Metadata: map[string]any{"trace_id": "req-2026-06-10-001"},
})

reply, err := client.Ask(ctx, "Show the next instruction.", thalovant.RequestOptions{
  Context: requestContext,
})

Rust

use serde_json::json;

let mut metadata = serde_json::Map::new();
metadata.insert("trace_id".into(), json!("req-2026-06-10-001"));

let context = build_client_context(None, ClientContextOptions {
    user_id: Some("user-42".into()),
    user_name: Some("Ada".into()),
    source: Some("checkout-kiosk".into()),
    platform: Some("kiosk".into()),
    locale: Some("en-US".into()),
    channel: Some("chat".into()),
    metadata: Some(metadata),
    ..Default::default()
});

let reply = client
    .ask(
        "Show the next instruction.",
        RequestOptions {
            context: Some(context),
            ..Default::default()
        },
    )
    .await?;

Astuce

Le contexte doit permettre de comprendre la requête après coup. N’y mettez pas de mots de passe, de jetons d’API, de fichiers d’identité complets ni de profils d’utilisateurs privés.

Lancer des diagnostics

Utilisez les diagnostics quand un client ne peut pas se connecter, qu’un protocole manque ou qu’un événement n’arrive jamais.

Python

print(client.doctor())

Node.js

console.log(await client.healthcheck());

Go

fmt.Println(client.Healthcheck())

Rust

println!("{:?}", client.healthcheck().await);

Valeurs de protocole

Utilisez l’énumération ou la chaîne de protocole du SDK qui correspond à votre langage.

Protocole	Python	Node.js	Go	Rust
WSS	"wss"	"wss"	thalovant.ProtocolWSS	HubProtocol::Wss
HTTPS	"https"	"https"	thalovant.ProtocolHTTPS	HubProtocol::Https
MQTT	"mqtt"	"mqtt"	thalovant.ProtocolMQTT	HubProtocol::Mqtt

Les sélecteurs automatiques de protocole préfèrent WSS, puis HTTPS, puis MQTT quand l’identité contient des identifiants de courtier (broker). Les anciens constructeurs NewClient(identity) de Go et Client::new(identity) de Rust choisissent directement HTTPS; utilisez NewClientWithOptions ou Client::auto pour une sélection automatique.

Modèles de construction courants

1. Découvrez un hub. Utilisez list_public_hubs, get_public_hub, list_hubs ou get_hub.
2. Créez ou chargez les éléments d’identité. Utilisez create_client_identity pour les nouveaux clients, ou chargez une identité existante depuis la configuration, un fichier ou l’environnement.
3. Choisissez un protocole. Commencez par WSS, à moins que votre déploiement n’exige HTTPS ou MQTT.
4. Envoyez une requête. Commencez par ask, parce qu’il donne une réponse claire.
5. Ajoutez les événements et le contexte. Ajoutez listen, wait_for_event et build_client_context une fois que la requête de base fonctionne.
6. Montrez ce qu’on peut demander. Utilisez intents quand le client doit lister les intentions et les phrases du hub, par langue.