Configuring Session & User ID

Setting the Session ID and User ID lets you group and trace LLM calls by session and user. There are two configuration methods, and when more than one applies at the same time, only one takes effect according to precedence.

Code (API) method

When you call set_session_id() and set_user_id() in a request handler, the Session ID and User ID apply to every LLM call that occurs within that request context.

from whatap.llm import set_user_id, set_session_id

@app.post("/chat")
async def chat(req):
    set_user_id(req.user.id)                 # who
    set_session_id(req.conversation_id)      # which conversation
    ...

Both functions record the values in the active transaction context. You must therefore call them inside a request handler or inside an instrumented workflow; calling them outside a transaction (at module load time, before a worker starts, and so on) does nothing. The return value (bool) tells you whether they were applied.

Specifying a scope

To mark a block outside a request handler — in a background job or a batch, for example — use the context managers. On leaving the block, the previous values are restored.

from whatap.llm import session, user

with user(user_id):
    with session(conversation_id):
        client.chat.completions.create(...)

HTTP header method

When the Session ID and User ID are passed in HTTP request headers, you can apply them with whatap.conf settings alone, without modifying any code.

whatap.conf

llm_session_header=X-Conversation-Id
llm_user_header=X-User-Id

In the example above, the X-Conversation-Id header value is used as the Session ID and the X-User-Id header value as the User ID.

Frameworks with automatic instrumentation

For the following frameworks, the Session ID and User ID are collected automatically without any configuration.

Framework	How it is collected
hermes-agent	Collected automatically from the event information at the gateway inbound (GatewayRunner._handle_message). The User ID is the user identifier of the messenger platform (the value filled in by the telegram, slack, or whatsapp adapter), and the Session ID uses the session key by which hermes groups conversation history.