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.

The Four Fields

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.

These are application fields. A conversation’s session_id does not replace the client identity or the SDK’s saved keys. Reconnecting starts a new encrypted session; keep the same application session ID for related turns, and keep the SDK’s saved keys across reconnects and restarts.

Session and user labels do not grant authorization or guarantee durable memory. Skills decide how they use context, and durable memory has its own API and access controls. A request_id correlates replies; it is not an idempotency guarantee for a repeated action.

The hub may replace a client-supplied session ID with its own. Ask requires its matching request ID, so a changed session ID does not discard the reply. Lower-level event filters preserve their documented handling of events without IDs. Use the SDK’s correlation helpers instead of requiring the echoed session ID to equal the one sent.

Generate a fresh request ID for each logical Ask and a fresh query ID for each logical Query. High-level SDKs reject a duplicate active collector on the same client. Ask and Query use independent namespaces. A later call still needs a new ID, including after cancellation, because delayed remote replies can outlive the earlier collector.

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 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,
    )

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.