Session scope
A Session spans one conversation — all turns with the same user until you decide it ends. History, memory summaries, user preferences all live here. Persist it if you want to resume tomorrow.
Session session = runtime.newSession(userId);
// ... multiple turns using the same session ...
sessionStore.save(session); // persist to Redis/PostgresAdvertisement
Invocation scope
An Invocation is one user turn. It holds the current message, the tool-call chain within it, and any per-turn locals you attach. It dies at the end of the loop.
Advertisement
Per-tool scope
Each tool call gets a fresh ToolContext. Anything you stash on it lives for microseconds and is gone. Good for correlation IDs.