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

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

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.