Sessions and Context

Session and context fields let your product keep hub requests tied to the right user journey.

Use them when a client needs memory, tracing, audit records, personalization, or tool calls around a request.

At a Glance

Field	Scope	Why it matters
session_id	Many requests	Keeps a conversation or workflow grouped.
request_id	One request	Gives logs and support records a stable trace key.
context	One request or session	Carries product metadata without changing the utterance.
site_id	Client identity	Names the deployed client or runtime.

Recommended Context

Start with fields that help you debug and personalize safely:

Context key	Example	Use
user_id	user-42	Tie the request to an app user without sending private profile data.
user_name	Ada	Let skills address the user when that is useful.
source	kiosk-checkout	Identify the app, device, or entry flow.
platform	web	Separate browser, mobile, service, and embedded behavior.
locale	en-US	Prefer a response language or formatting style.
trace_id	req-2026-06-05-001	Join SDK, service, and hub logs.

Python Example

from thalovant import ThalovantClient, 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-05-001"},
)

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

Design Rules

1. Keep identifiers stable. Reuse session_id for the whole conversation or workflow.
2. Keep request IDs unique. Generate a new request_id for each send.
3. Keep context small. Send labels, IDs, and routing hints instead of large payloads.
4. Keep secrets out. Do not pass tokens, passwords, or raw identity material as context.
5. Keep names generic. Model product roles and flows in your app, then pass neutral metadata to the SDK.

Tip

Context is most useful when it can explain a request later without exposing private setup material.

Common Session Shapes

Chat session

One session_id per visible conversation, with one request_id per turn.

Workflow session

One session_id per task, checkout, form, or guided process.

Device session

One session_id per device interaction window, paired with a stable site_id.

Service trace

One service trace ID copied into request context and logs.