Skip to main content
retrieve_session() returns the same shape on every managed agent backend so you can write code once and switch providers freely.

​
Quick Start

1

Basic Usage

from praisonaiagents import Agent
from praisonai.integrations.managed_agents import ManagedAgent, ManagedConfig

managed = ManagedAgent(config=ManagedConfig(model="claude-sonnet-4-6"))
agent = Agent(name="assistant", backend=managed)
agent.start("Hello!")

info = managed.retrieve_session()
print(info["id"], info["status"], info["title"])
print(info["usage"]["input_tokens"], info["usage"]["output_tokens"])
2

Local Backend

from praisonai.integrations.managed_local import LocalManagedAgent

local = LocalManagedAgent()
info = local.retrieve_session()
# Same 4 keys — id, status, title, usage — every time

​
Schema

All four fields are always present with sensible defaults:
FieldTypeDefaultValues
idstr""Session ID, empty if none
statusstr"unknown"idle, running, error, unknown, none
titlestr""Session title (Anthropic only sets this)
usageDict[str, int]{"input_tokens": 0, "output_tokens": 0}Always has both keys

​
Status Values

StatusMeaning
idleSession exists and ready for input
runningSession actively processing (Anthropic)
errorSession hit an error (Anthropic)
unknownNo session / status unavailable
noneLocal backend with no session ID

​
Empty Session Defaults

Before starting any turn you still get a valid dict — no KeyError, no .get() guards: 
managed = ManagedAgent(config=ManagedConfig())
info = managed.retrieve_session()
# {"id": "", "status": "unknown", "title": "", "usage": {"input_tokens": 0, "output_tokens": 0}}

​
Building a Custom Backend

Import the protocol directly from praisonaiagents.managed: 
from praisonaiagents.managed import ManagedBackendProtocol
from typing import Dict, Any

class MyBackend:
    def retrieve_session(self) -> Dict[str, Any]:
        # Return the unified shape
        return {
            "id": "my-session",
            "status": "idle",
            "title": "My Session",
            "usage": {"input_tokens": 0, "output_tokens": 0},
        }
    # ... implement execute(), stream(), reset_session(), reset_all()

​
Common Patterns

​
Cost monitoring

info = managed.retrieve_session()
cost = info["usage"]["input_tokens"] * 3e-6 + info["usage"]["output_tokens"] * 15e-6
print(f"Session {info['id']} spent ${cost:.4f}")

​
Provider-agnostic logging

def log_session(backend):
    info = backend.retrieve_session()
    print(f"[{info['status']}] {info['title'] or info['id']}")

log_session(anthropic_backend)
log_session(local_backend)  # Same code — both return identical shape

​
Best Practices

Every key is always present. info["usage"]["input_tokens"] is always safe.
Use status == "idle" before sending a new message to avoid overlapping turns.
LocalManagedAgent always returns title="". Only AnthropicManagedAgent sets it.
from praisonaiagents.managed import ManagedBackendProtocol is the stable, recommended path.

Overview of managed agent backends

Run managed agents locally