A Session is the immutable container for an agent’s lifecycle. It guarantees sequential integrity of state transitions.
The Session Object
StateBase treats every session as a cryptographically verifiable ledger.
{
"id": "sess_01H1V2...",
"agent_id": "finance_research_v1",
"user_id": "usr_8923",
"created_at": "2026-01-27T10:00:00Z",
"current_turn_id": "turn_01H1V3...",
"metadata": {
"environment": "production",
"region": "us-east-1"
}
}
Creating a Session
from statebase import StateBase
sb = StateBase(api_key="sb_live_...")
session = sb.sessions.create(
agent_id="coding_agent",
user_id="user_123",
metadata={"model": "gpt-4-turbo"}
)
print(f"Session started: {session.id}")
State Retrieval
You can fetch the entire state history or just the latest snapshot.
Method 1: Full History
Ideal for audit logs or post-mortem debugging.
history = sb.sessions.get_history(session.id)
for turn in history:
print(f"Turn {turn.index}: {turn.input} -> {turn.output}")
Method 2: Current Context
Optimized for injecting into your LLM’s prompt window.
# Returns the last N turns + relevant long-term memories
context = sb.sessions.get_context(
session_id=session.id,
limit=10,
include_memory=True
)
prompt = f"""
System: You are a helpful assistant.
Context: {context.to_string()}
User: {user_input}
"""
Latency Tip: get_context is served from our Edge Cache (avg < 50ms). Do not query the main database directly in your hot path.
