Session Management

Sessions are the state containers for multi-turn conversations and multi-agent workflows. They are created automatically, stored in Redis, and provide conversation continuity across agent interactions.

Automatic Session Management

Sessions are created on first use and reused automatically:

# First call creates the session
result = await leafmesh.mesh_call(
    "solver",
    input_data={"message": "What is 2 + 2?"},
    session_id="user_123"
)

# Second call reuses the session — agent has conversation history
result2 = await leafmesh.mesh_call(
    "solver",
    input_data={"message": "Now multiply that by 3"},
    session_id="user_123"
)

Conversation history is injected into agent prompts automatically as user/assistant pairs.

What Gets Stored

The platform automatically persists per-session state including:

Session metadata — created/updated timestamps, state, configuration snapshot
Conversation history — every message exchanged in the session
Agent yields — declared outputs from each agent, available to downstream agents
Mesh communications — inter-agent call records
Coordination decisions — actions taken by automatic coordination

Data	TTL
Session metadata + conversation history	`REDIS_SESSION_TTL` (default 604800s / 7 days, configurable)
Agent yields, mesh communications, coordination decisions	`REDIS_DEFAULT_TTL` (default 3600s, configurable)

All storage is automatic. No explicit save calls are needed.

Conversation History Structure

Each entry is a structured record:

{
    "role": "user|assistant|system",
    "content": "The message content",
    "timestamp": "2026-02-26T10:30:00Z",
    "agent_name": "solver",
    "type": "user_message|agent_response|mesh_call|tool_result"
}

The type field distinguishes between direct user messages, agent LLM responses, inter-agent mesh communications, and tool execution results.

Inspecting Sessions

Browse session state in Studio's Sessions tab for a visual view of conversation history, agent yields, and mesh communications per session.

Using Session Context in Intelligence Functions

The context parameter in intelligence functions provides session information:

async def context_aware(llm_response, input_data, context):
    session_id = context.get("session_id", "default")

    # Access yields from upstream agents via input_data
    previous_answer = input_data.get("answer")

    return {
        "response": llm_response.get("response", ""),
        "has_history": previous_answer is not None
    }

Session Threading

For complex workflows where multiple agents work on different aspects simultaneously, the system creates session "threads" that inherit context from parent sessions while maintaining independent execution paths. Thread results are merged back into the parent session on completion.

Redis Configuration

# .env
LEAFMESH_STORE=redis
REDIS_HOST=localhost
REDIS_PORT=6379
# 1 hour for general data
REDIS_DEFAULT_TTL=3600
# 7 days for sessions (the default)
REDIS_SESSION_TTL=604800

From 2.4.482 the store is set only in .env, never in the YAML.

Next Steps

Session & State — Detailed Redis persistence patterns
Architecture — How sessions fit in the control plane
Configuration — Redis configuration options

LeafMesh — Automatic session management