Sessions

Conversation containers with scoped state and multi-agent coordination

Sessions are conversation containers built on the Entity primitive. They manage multi-turn interactions between users and AI agents, providing structured state management, message history, and audit trails.

Key Characteristics

Built on Entity - Inherits durability and consistency from Entity
Scoped State - Organize state with session/user/app/temp scopes
Message History - Automatic conversation tracking with metadata
Multi-Agent Ready - Share context across multiple agents
Audit Trail - Complete history of interactions for compliance
Flexible Retention - Configurable data retention policies

Basic Usage

Creating a Session

from agnt5 import Session

# Create session with user context
session = Session(
    id="conv-2024-001",
    app_name="research_assistant",
    user_id="user-123",
    metadata={"project": "ai-safety-research"}
)

Managing Messages

Scoped State Management

Session state uses four scopes for different persistence levels:

# Session scope - conversation-specific (default)
session.set_state("shopping_cart", ["item1", "item2"])
session.set_state("current_step", "checkout")

# User scope - persists across all user sessions
session.set_state("language", "English", scope="user")
session.set_state("timezone", "America/Los_Angeles", scope="user")

# App scope - application-wide global state
session.set_state("api_version", "v2", scope="app")
session.set_state("feature_flags", {"new_ui": True}, scope="app")

# Temp scope - temporary invocation-specific
session.set_state("processing_step", "validation", scope="temp")

Integration with Agents

from agnt5 import Agent, Session, LanguageModel

# Create session
session = Session(
    id="support-ticket-456",
    user_id="customer-789",
    metadata={"ticket_type": "billing"}
)

# Create agent with session
lm = LanguageModel()
agent = Agent(
    name="support_agent",
    model=lm,
    instructions="You are a helpful customer support agent.",
    tools=[search_kb_tool, create_ticket_tool],
    session=session
)

# Agent automatically uses session for context
result = await agent.run("I need help with my recent charge")

# Session maintains full conversation history
history = await session.history()

Common Patterns

Multi-Agent Coordination

Share context across multiple specialized agents:

# Create shared session
session = Session(
    id="research-workflow-001",
    user_id="researcher-123",
    metadata={"project": "quantum-computing-review"}
)

# Set shared context
session.set_state("research_topic", "quantum error correction")
session.set_state("target_depth", "comprehensive")

# Multiple specialized agents work together
literature_agent = Agent(
    name="literature_reviewer",
    session=session,
    tools=[paper_search]
)

code_agent = Agent(
    name="code_analyzer",
    session=session,
    tools=[github_search]
)

synthesis_agent = Agent(
    name="synthesizer",
    session=session,
    tools=[document_tool]
)

# Execute research pipeline
papers = await literature_agent.run("Find recent papers")
implementations = await code_agent.run("Find implementations")
report = await synthesis_agent.run("Synthesize findings")

# All agents see shared context and each other's work
full_history = await session.history()

Agent Handoff Pattern

Seamlessly transfer conversations between specialized agents:

session = Session(id="customer-inquiry-789", user_id="customer-456")

# Coordinator routes to appropriate specialist
coordinator = Agent(
    name="router",
    session=session,
    tools=[classification_tool]
)
routing = await coordinator.run("How do I upgrade my subscription?")

if routing.category == "billing":
    # Billing agent gets full conversation context
    billing_agent = Agent(
        name="billing_specialist",
        session=session,
        tools=[billing_tools]
    )
    result = await billing_agent.run("Continue from coordinator's analysis")
    # billing_agent sees all previous messages

elif routing.category == "technical":
    tech_agent = Agent(
        name="tech_support",
        session=session,
        tools=[tech_tools]
    )
    result = await tech_agent.run("Handle technical inquiry")

Session State vs Memory

Aspect	Session State	Memory
Scope	Conversation-specific	Cross-conversation
Lifetime	Cleared after session	Persists indefinitely
Use Case	Current context	Long-term knowledge
Example	Current task, cart items	User preferences, history

Session Export and Audit

# Create session with audit metadata
session = Session(
    id="compliance-audit-001",
    user_id="analyst-789",
    metadata={
        "regulation": "SOC2",
        "audit_period": "Q4-2024",
        "auditor": "external-firm"
    },
    retention={"ttl_days": 730}  # 2 years
)

# Conduct conversation with full tracking
agent = Agent(name="data_analyst", session=session)
await agent.run("Analyze user access patterns")

# Export session for compliance review
jsonl_export = await session.export(format="jsonl")
# Each line contains: timestamp, role, message, metadata, tool_calls

# Query specific events
recent_events = await session.events(since="2024-01-01", limit=100)

# Prune old messages while keeping metadata
await session.prune(strategy="keep_last_50")

Long-Running Sessions with Pruning

# Create session with automatic pruning
session = Session(
    id="long-conversation-456",
    user_id="user-123",
    metadata={"type": "ongoing_project"}
)

# After many interactions, prune intelligently
await session.prune(strategy="keep_important")  # Uses LLM
await session.prune(strategy="sliding_window", window_size=100)
await session.prune(strategy="summarize_old", threshold=50)

# Session remains performant even with thousands of messages

Configuration

Session Parameters

Parameter	Type	Description
`id`	`str`	Unique session identifier
`app_name`	`str \| None`	Application name
`user_id`	`str \| None`	User identifier
`metadata`	`dict \| None`	Session metadata
`retention`	`dict \| None`	Retention policy configuration

Retention Policies

Configure data retention:

Best Practices

1. Use Appropriate State Scopes

Match state scope to persistence requirements:

# ✓ Session scope - conversation-specific
session.set_state("current_page", 3)
session.set_state("draft_document", content)

# ✓ User scope - user preferences
session.set_state("theme", "dark", scope="user")
session.set_state("notification_preference", "email", scope="user")

# ✓ App scope - global configuration
session.set_state("rate_limit", 1000, scope="app")
session.set_state("feature_flags", flags, scope="app")

# ✓ Temp scope - transient data
session.set_state("validation_step", "in_progress", scope="temp")

2. Design for Multi-Agent Coordination

Structure session state for agent collaboration:

# Good - Clear coordination structure
session.set_state("workflow_stage", "research")
session.set_state("agent_outputs", {
    "researcher": {"status": "completed", "findings": [...]},
    "analyzer": {"status": "in_progress"},
    "writer": {"status": "pending"}
})

# Agents can check dependencies
current_stage = session.get_state("workflow_stage")
researcher_output = session.get_state("agent_outputs")["researcher"]

3. Implement Retention Strategies

Manage session lifecycle appropriately:

# For regulated industries
session = Session(
    id="medical-consultation",
    retention={
        "ttl_days": 2555,  # Legal requirement
        "immutable": True
    }
)

# For ephemeral conversations
session = Session(
    id="temp-chat",
    retention={
        "ttl_days": 1,  # Delete after 1 day
        "auto_prune": True
    }
)

Entity vs Session

Aspect	Entity	Session
Purpose	General stateful primitive	Conversation-specific
State Structure	Flexible key-value	Opinionated message + state
API	Low-level (get/set/delete)	High-level (send_message/history)
Scoping	Manual	Built-in (session/user/app/temp)
Audit	Manual event tracking	Automatic conversation log
Use Case	Custom stateful components	AI agent conversations

When to use Entity:

Building custom stateful patterns
Need complete control over state structure
Non-conversation workloads

When to use Session:

AI agent conversations
Multi-agent coordination needed
Audit trails required
Standard conversation patterns

Next Steps

Entity - Underlying primitive for Session
Agent - Agents use Sessions for context
Memory - Long-term storage vs Session state
Context API - Session context operations