# Sessions and Context

> Pass stable session, user, device, and trace context through Thalovant SDK requests.

Source: https://docs.thalovant.com/developers/sessions-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](/workspace/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

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

## 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.

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

## Common Session Shapes

  
    One `session_id` per visible conversation, with one `request_id` per turn.
  
  
    One `session_id` per task, checkout, form, or guided process.
  
  
    One `session_id` per device interaction window, paired with a stable `site_id`.
  
  
    One service trace ID copied into request context and logs.