Mediator - Communication Handler

Overview

The Mediator is a core component in the TKM AI Agency Platform that manages and coordinates communication between different agents. It handles message routing, agent registration, conversation state management, and ensures proper interaction between backoffice and CRM agents.

Directory Structure

Backend/Core_Components/
├── mediator.py                    # Main mediator implementation
├── mediator_tools.py              # Mediator utility functions
├── mediator_tools_definitions.py  # Constants and route definitions
└── types.py                       # Type definitions

Main Components

AgentMediator Class

The core component that handles inter-agent communication:

• Agent registration and management
• Message routing
• Conversation state tracking
• Permission handling

Processing Pipeline

1. Request Reception

   • Agent validation
   • Permission checking
   • Conversation state verification
   • Route validation

2. Message Routing

   • Route determination
   • Agent availability check
   • State management
   • Response handling

3. State Management

   • Conversation locking
   • Blocking agent handling
   • History tracking
   • Cleanup operations

Key Features

1. Agent Management

   • Agent registration
   • Type categorization (Backoffice/CRM)
   • Instance tracking
   • State monitoring

2. Routing System

   • Dynamic routing
   • Permission validation
   • Blocking agent support
   • History tracking

3. Conversation Control

   • State locking
   • Timeout handling
   • Blocking operations
   • Cleanup mechanisms

API Operations

Route Request

• Method: route_request
• Purpose: Routes messages between agents
• Parameters:

  {
    "from_agent": str,
    "to_agent": str,
    "data": Dict[str, Any],
    "agent_type": str
  }
• Response:

  {
    "success": bool,
    "data": Dict[str, Any],
    "error": Optional[str]
  }

Register Agent

• Method: register_agent
• Purpose: Registers new agents in the system
• Parameters:

  {
    "agent_name": str,
    "agent_instance": Any,
    "agent_type": str
  }

Integration

Agent Types

• Backoffice Agents

  • System management
  • Core operations
  • Data handling

• CRM Agents

  • User interaction
  • Service provision
  • Business logic

Special Handlers

• Blocking agent management
• Conversation state control
• Route permissions
• History tracking

Error Handling

1. Routing Errors

   • Agent not found
   • Invalid permissions
   • Timeout handling
   • State conflicts

2. State Errors

   • Lock conflicts
   • Invalid states
   • Cleanup failures
   • History errors

Performance Features

1. Optimization

   • Efficient routing
   • State caching
   • History management
   • Resource control

2. Monitoring

   • Route tracking
   • State monitoring
   • Error logging
   • Performance metrics

Data Models

Routing History

{
    "from_agent": str,
    "to_agent": str,
    "data": Dict[str, Any],
    "agent_type": str,
    "timestamp": str
}

Agent Registration

{
    "agent_name": str,
    "agent_type": str,
    "instance": Any,
    "state": Dict[str, Any]
}