Barbatus - Session Management Agent

Barbatus is the agent responsible for managing user sessions and API key authentication in the TKM AI Agency Platform. It serves as the gateway for user interactions and maintains session state across the system.

Overview

The Barbatus agent handles:

• User session creation and management
• API key generation and validation
• Session-conversation mapping
• Integration with Atta for conversation management

Directory Structure

Barbatus/
├── barbatus.py         # Main agent implementation
├── api_barbatus.py     # FastAPI router and endpoints
├── tools.py            # Core functionality and utilities
├── tools_schema.py     # Data models and schemas
├── tools_definitions.py # Session configurations
└── data/              # Storage directory for sessions

Core Components

Session Management

Session Metadata

class SessionMetadata(BaseModel):
    created_at: datetime
    last_activity: datetime
    status: str = "active"  # active, paused, ended
    source: str = "web"     # web, mobile, api
    organization_id: str

Session Response

class SessionResponse(BaseModel):
    success: bool
    user_id: str
    session_id: str
    metadata: Optional[SessionMetadata]
    error: Optional[str]

API Key Management

API Key Metadata

class APIKeyMetadata(BaseModel):
    created_at: datetime
    last_used: datetime
    status: str = "active"  # active, revoked
    permissions: list[str] = ["basic"]

API Endpoints

Session Management

Initialize Session

POST /api/barbatus/initialize_session

{
    "user_id": str,
    "organization_id": str  # Optional, defaults to "tkm_123456"
}

Verify Session

POST /api/barbatus/verify_session

{
    "user_id": str,
    "conversation_id": str
}

Create New Conversation

POST /api/barbatus/new_conversation

{
    "user_id": str,
    "session_id": Optional[str],
    "organization_id": Optional[str]
}

API Key Management

Generate API Key

POST /api/barbatus/generate_api_key

{
    "user_id": str,
    "permissions": Optional[List[str]]  # Defaults to ["basic"]
}

List API Keys

GET /api/barbatus/list_api_keys/{user_id}

Revoke API Key

POST /api/barbatus/revoke_api_key

{
    "user_id": str,
    "api_key": str
}

Verify API Key

POST /api/barbatus/verify_api_key

{
    "api_key": str
}

Main Features

Session Management

• Creation of new user sessions
• Session state tracking
• Session verification and validation
• Integration with conversation management

API Key Handling

• Generation of secure API keys
• Permission-based access control
• Key revocation and validation
• Key metadata tracking

Integration Features

• Automatic conversation creation with Atta
• Session-conversation mapping
• Organization context management
• Event handling for session updates

Error Handling

The agent implements comprehensive error handling for:

• Invalid session states
• API key validation failures
• Integration errors with other agents
• Session state conflicts

Security Features

Session Security

• Unique session IDs
• Activity tracking
• Organization-based isolation
• Status management

API Key Security

• Secure key generation
• Permission-based access
• Key revocation system
• Usage tracking

Performance Features

Caching

• Active session caching
• API key validation caching
• Session metadata caching

State Management

• In-memory session tracking
• Persistent storage backup
• Event-based updates
• Automatic cleanup of inactive sessions