Sessions et contexte

Les champs de session et de contexte permettent à votre produit de garder les requêtes au hub rattachées au bon parcours utilisateur.

Utilisez-les quand un client a besoin de mémoire, de traçage, de journaux d’audit, de personnalisation ou d’appels d’outils autour d’une requête.

Les quatre champs

Champ	Portée	Pourquoi c’est important
session_id	Plusieurs requêtes	Garde regroupés les éléments d’une conversation ou d’un parcours.
request_id	Une requête	Donne aux journaux et aux dossiers de soutien une clé de traçage stable.
context	Une requête ou une session	Transporte des métadonnées du produit sans modifier l’énoncé.
site_id	Identité du client	Nomme le client ou le runtime déployé.

Ce sont des champs d’application. Le session_id d’une conversation ne remplace ni l’identité du client ni les clés enregistrées par le SDK. Une reconnexion ouvre une nouvelle session chiffrée; gardez le même ID de session d’application pour les tours liés, et conservez les clés enregistrées par le SDK d’une reconnexion et d’un redémarrage à l’autre.

Les libellés de session et d’utilisateur n’accordent aucune autorisation et ne garantissent pas une mémoire durable. Les compétences décident de la façon dont elles utilisent le contexte, et la mémoire durable a sa propre API et ses propres contrôles d’accès. Un request_id sert à associer les réponses; il ne garantit pas l’idempotence d’une action répétée.

Le hub peut remplacer par le sien un ID de session fourni par le client. Ask exige l’ID de requête correspondant : un ID de session modifié ne fait donc pas perdre la réponse. Les filtres d’événements de plus bas niveau conservent leur traitement documenté des événements sans ID. Utilisez les fonctions de corrélation du SDK au lieu d’exiger que l’ID de session renvoyé soit identique à celui envoyé.

Générez un nouvel ID de requête pour chaque Ask logique et un nouvel ID Query pour chaque Query logique. Les SDK de haut niveau refusent un collecteur actif en double sur le même client. Ask et Query utilisent des espaces de noms indépendants. Un appel ultérieur a quand même besoin d’un nouvel ID, y compris après une annulation, parce que des réponses distantes en retard peuvent survivre au collecteur précédent.

Contexte recommandé

Commencez par des champs qui vous aident à déboguer et à personnaliser sans risque :

Clé de contexte	Exemple	Utilisation
user_id	user-42	Rattacher la requête à un utilisateur de l’application sans envoyer de données de profil privées.
user_name	Ada	Permettre aux compétences de s’adresser à l’utilisateur quand c’est utile.
source	kiosk-checkout	Identifier l’application, l’appareil ou le parcours d’entrée.
platform	web	Distinguer le comportement navigateur, mobile, service et embarqué.
locale	en-US	Privilégier une langue de réponse ou un style de mise en forme.
trace_id	req-2026-06-05-001	Relier les journaux du SDK, du service et du hub.

Exemple en Python

from uuid import uuid4

from thalovant import ThalovantClient, build_client_context

request_id = str(uuid4())
context = build_client_context(
    user_id="user-42",
    user_name="Ada",
    source="checkout-kiosk",
    platform="kiosk",
    locale="en-US",
    metadata={"trace_id": request_id},
)

with ThalovantClient.from_identity_file("_identity.json") as client:
    reply = client.ask(
        "What should happen next?",
        session_id="checkout-session",
        request_id=request_id,
        context=context,
    )

Règles de conception

1. Gardez les identifiants stables. Réutilisez session_id pour toute la conversation ou tout le parcours.
2. Gardez les ID de requête uniques. Générez un nouveau request_id pour chaque envoi.
3. Gardez le contexte léger. Envoyez des libellés, des ID et des indications de routage plutôt que de grosses charges utiles.
4. Laissez les secrets de côté. Ne passez pas de jetons, de mots de passe ni de matériel d’identité brut dans le contexte.
5. Gardez des noms génériques. Modélisez les rôles et les parcours du produit dans votre application, puis passez des métadonnées neutres au SDK.

Astuce

Le contexte est le plus utile quand il permet d’expliquer une requête après coup sans exposer de matériel de configuration privé.

Formes de session courantes

Session de clavardage

Un session_id par conversation visible, avec un request_id par tour.

Session de parcours

Un session_id par tâche, passage à la caisse, formulaire ou processus guidé.

Session d'appareil

Un session_id par fenêtre d’interaction avec l’appareil, associé à un site_id stable.

Trace de service

Un ID de trace de service copié dans le contexte de la requête et dans les journaux.