Invicta - Message Router Agent

Overview

Invicta is the Message Router agent in the TKM AI Agency Platform, responsible for orchestrating message flow and routing between different components of the CRM system. It analyzes incoming messages, determines the appropriate target agents based on intent analysis, and manages conversation context to ensure efficient message handling.

Directory Structure

Backend/CRM/Invicta/
├── data/                  # Routing logs and data storage
├── invicta.py            # Main agent implementation
├── tools.py              # Routing and analysis utilities
├── tools_schema.py       # Data models and schemas
└── tools_definitions.py  # Constants and routing definitions

Main Components

InvictaAgent Class

The core component that handles message routing and orchestration:

• Initializes with mediator, event bus, and OpenAI client
• Manages user and organization identifiers
• Handles conversation context and caching
• Processes incoming messages and determines routing

Processing Pipeline

1. Message Reception

   • Receives incoming messages through the process_request method
   • Validates request format and action type

2. Context Management

   • Retrieves conversation history and user preferences
   • Maintains context cache for efficient processing
   • Updates context based on new interactions

3. Intent Analysis

   • Analyzes message content to determine intent
   • Maps intent to appropriate target agent
   • Updates routing decisions in routing registry

4. Message Routing

   • Delegates messages to target agents
   • Handles routing errors and fallbacks
   • Maintains routing history

API Operations

Process Request

• Endpoint: /process_request
• Method: POST
• Purpose: Entry point for message processing and routing
• Request Format:

  {
    "action": "process_message",
    "message": "User message content",
    "user_id": "user_identifier",
    "org_id": "organization_identifier"
  }
• Response Format:

  {
    "status": "success",
    "target_agent": "agent_identifier",
    "context": {
      "conversation_id": "conversation_identifier",
      "history": []
    }
  }

Key Features

1. Dynamic Routing

   • Intent-based message routing
   • Adaptive routing based on conversation context
   • Fallback mechanisms for unrecognized intents

2. Context Management

   • Efficient context caching
   • Conversation history tracking
   • User preference integration

3. Routing Registry

   • Persistent routing decisions
   • Historical routing patterns
   • Analytics support

Integration

Agent Communication

• Interfaces with other CRM agents through mediator pattern
• Maintains routing tables for agent selection
• Handles inter-agent message formatting

Event System

• Integrates with event bus for asynchronous operations
• Publishes routing events for monitoring
• Subscribes to system events for routing updates

Error Handling

1. Request Validation

   • Input format verification
   • Required field checking
   • Action type validation

2. Routing Errors

   • Target agent unavailability handling
   • Fallback routing mechanisms
   • Error logging and reporting

Performance Features

1. Caching

   • Context caching for improved response times
   • Routing decision caching
   • User preference caching

2. Optimization

   • Efficient message processing
   • Minimized context lookups
   • Optimized routing decisions

Data Models

Message Format

{
    "message_id": str,
    "content": str,
    "user_id": str,
    "org_id": str,
    "timestamp": datetime,
    "metadata": dict
}

Routing Configuration

{
    "target_agent": str,
    "routing_rules": list,
    "fallback_agent": str,
    "priority": int
}