Session Runtime State

Mirror per-turn runtime execution artefacts onto sessions for replay and cross-runtime handoff

Runtime state mirroring lets sessions remember lightweight per-turn execution artefacts (tool call IDs, transcript slices) so the native runtime and plugin harnesses can hand off, replay, or debug each other’s turns.

from praisonaiagents import Agent

agent = Agent(
    name="Assistant",
    memory={"session_id": "my-session"},
)
agent.start("Run a tool turn — enable mirror_runtime_state on your gateway SessionConfig")

The user hands off between native and plugin runtimes; mirrored state preserves tool IDs and transcript slices each turn.

Quick Start

1. Enable mirroring

   from praisonaiagents import GatewayConfig, SessionConfig
   
   config = GatewayConfig(
       session_config=SessionConfig(
           persist=True,
           mirror_runtime_state=True,
       )
   )

2. Read what was mirrored

   from praisonaiagents.session import DefaultSessionStore
   
   store = DefaultSessionStore()
   turns = store.get_runtime_state(session_id="my-session", runtime_id="native")
   for turn_id, state in turns.items():
       print(turn_id, state.get("tool_calls", []))

How It Works

Configuration

Set on SessionConfig — typically via GatewayConfig(session_config=...).

Store API

On-disk shape

{
  "session_id": "my-session",
  "messages": [],
  "runtime_state": {
    "native": { "turn-1": { "tool_calls": ["call-1"] } },
    "plugin_harness": { "turn-1": { "transcript": "..." } }
  }
}

Shape: {runtime_id: {turn_id: state}}.

Common patterns

state = store.get_runtime_state("my-session", "native", "turn-1")
tool_calls = state.get("tool_calls", [])
# Feed IDs into a follow-up run or debugger

native = store.get_runtime_state("my-session", "native", "turn-1")
store.set_runtime_state(
    "my-session", "plugin_harness", "turn-2",
    {"prior_tool_calls": native.get("tool_calls", [])},
    mirror_enabled=True,
)

from praisonaiagents.hooks import add_hook
from praisonaiagents.session import DefaultSessionStore

@add_hook("after_agent")
def export_runtime_state(event):
    store = DefaultSessionStore()
    session_id = getattr(event, "session_id", None)
    if session_id:
        turns = store.get_runtime_state(session_id, "native")
        # Push lightweight slices to your observability backend
    return event

Best Practices

Related