Skip to main content
Session management allows you to handle multiple concurrent conversations by using the sessionId parameter in memory operations. This is an application-level pattern built on top of AG-Kit’s memory APIs.

Core Concept

A session is simply a unique identifier (string) that isolates conversation contexts. All memory operations accept an optional sessionId parameter to separate data between different users or conversations.

Quick Start

Basic Session Management

from agkit.agents import InMemoryMemory

# Create memory instance
memory = InMemoryMemory()

# Create session for user A
session_a = 'user-alice-session-1'
await memory.add(
    {
        'message': {
            'id': 'msg-1',
            'role': 'user',
            'content': 'Hello, I\'m Alice',
            'timestamp': datetime.now()
        },
        'state': {'user_id': 'alice'}
    },
    session_id=session_a
)

# Create session for user B
session_b = 'user-bob-session-1'
await memory.add(
    {
        'message': {
            'id': 'msg-1',
            'role': 'user',
            'content': 'Hi, I\'m Bob',
            'timestamp': datetime.now()
        },
        'state': {'user_id': 'bob'}
    },
    session_id=session_b
)

# Retrieve session-specific history
alice_history = await memory.list(session_id=session_a)
bob_history = await memory.list(session_id=session_b)

print('Alice:', alice_history[0]['message']['content'])  # "Hello, I'm Alice"
print('Bob:', bob_history[0]['message']['content'])  # "Hi, I'm Bob"

Common Session ID Patterns

You can design session IDs based on your application needs:
# User-based: one session per user
session_id = f'user-{user_id}'

# Conversation-based: multiple sessions per user
session_id = f'user-{user_id}-conv-{conversation_id}'

# Time-based: sessions with timestamps
session_id = f'user-{user_id}-{int(time.time() * 1000)}'

# Hierarchical: complex organization structure
session_id = f'org-{org_id}/team-{team_id}/user-{user_id}'

Using Sessions with Agents

Sessions enable isolated conversations for different users or contexts.
from agkit.agents import InMemoryMemory
import uuid

memory = InMemoryMemory()

# Agent handles request with session isolation
async def handle_user_message(user_id: str, message: str):
    session_id = f'user-{user_id}'
    
    # Add user message to session
    await memory.add(
        {
            'message': {
                'id': str(uuid.uuid4()),
                'role': 'user',
                'content': message,
                'timestamp': datetime.now()
            }
        },
        session_id=session_id
    )
    
    # Get session history for agent
    history = await memory.list(session_id=session_id)
    
    # Process with agent...
    response = await agent.run(
        messages=[m['message'] for m in history],
        session_id=session_id
    )
    
    return response
Learn more: Complete Agent Integration Guide

Best Practices

  1. Use meaningful session IDs - Include user/conversation identifiers for debugging
  2. Implement session cleanup - Remove old sessions to prevent memory leaks
  3. Handle session expiration - Implement timeout logic in your application
  4. Store session metadata separately - Track creation time, last activity, etc.
  5. Consider privacy - Clear sensitive session data when no longer needed

Next Steps