Skip to content

IAV-241/Add sub-agent creation with comprehensive helper architecture and enhanced validation

salaheddine zidani a demandé de fusionner feature/IAV-241 vers develop

🎯 Overview

This MR introduces sub-agent creation capabilities with a complete helper architecture that significantly improves code maintainability, validation, and error handling for agent operations.

✨ Key Features

1. Sub-Agent Creation

  • ✅ Full support for creating sub-agents linked to main agents
  • ✅ Automatic parent-child relationship management
  • ✅ Permission validation for admin and collaborator access
  • ✅ Collaborator linking when sub-agent is created by collaborator

2. Helper Architecture (4 New Classes)

AgentCreationHelper

  • Language creation with automatic default selection
  • Knowledge document upload management
  • N8n workflow template retrieval and configuration
  • Reusable agent entity building

AgentValidationHelper

  • Agent family validation (CUSTOMER_CARE only)
  • Webhook presence validation in workflow JSON
  • Main agent uniqueness enforcement (1 per admin per family)
  • Sub-agent creation rules (active parent, matching family, correct type)
  • Sub-agent name uniqueness within same parent
  • Request data validation (display name, system prompt, languages, blocked keywords)

UserHelper

  • Admin UID resolution for main agent creation (admin only)
  • Admin UID resolution for sub-agent creation (admin or collaborator)
  • Permission validation for sub-agent creation
  • Role checking (ADMIN, COLLABORATOR, SUPER_ADMIN)
  • Super admin restriction (cannot create agents)

WebhookHelper

  • Webhook URL construction from N8n instance and workflow JSON
  • Webhook path extraction using Jackson JSON parsing
  • Support for multiple webhook nodes
  • URL normalization and validation

3. Enhanced Validation Rules

Main Agent Creation:

  • Only ADMIN role can create main agents
  • One main agent per admin per family (uniqueness constraint)
  • Webhook node required in workflow

Sub-Agent Creation:

  • ADMIN or COLLABORATOR can create (with proper permissions)
  • Parent main agent must exist, be active, and have matching family
  • Sub-agent names must be unique within same parent
  • Collaborator must be linked to parent agent's owner admin

4. Improved Resource Management

  • Automatic cleanup on failure:
    • Uploaded knowledge documents deletion
    • N8n workflow deletion
    • Collaborator-agent link removal
  • Comprehensive transaction rollback support

🔧 Technical Implementation

Architecture

AgentServiceImpl
    ├── UserHelper (user validation & resolution)
    ├── AgentValidationHelper (business rules)
    ├── AgentCreationHelper (creation operations)
    └── WebhookHelper (N8n webhook operations)

Transaction Safety

  • @Transactional(rollbackFor = {FunctionalException.class, TechnicalException.class})
  • Cleanup method for created resources on failure
  • Separate tracking of uploadedFileUids, workflowId, linkedCollaboratorUid

Key Methods Added

  • AgentServiceImpl.createSubAgent() - Main sub-agent creation endpoint
  • AgentValidationHelper.validateSubAgentCreationRules() - Business logic validation
  • AgentValidationHelper.validateSubAgentNameUniqueness() - Name uniqueness check
  • UserHelper.validateUserPermissionForSubAgent() - Permission checking
  • WebhookHelper.extractWebhookPaths() - JSON parsing for webhook validation

📋 Testing Checklist

Unit Tests

  • AgentCreationHelper - language creation, file upload, workflow template
  • AgentValidationHelper - all validation rules
  • UserHelper - admin resolution, permission validation, role checking
  • WebhookHelper - URL construction, path extraction, JSON parsing

Integration Tests

  • Main agent creation (happy path)
  • Sub-agent creation by admin (happy path)
  • Sub-agent creation by collaborator (happy path)
  • Validation failures (uniqueness, permissions, family mismatch)
  • Resource cleanup on failure
  • Transaction rollback scenarios

Edge Cases

  • Multiple languages with no default specified
  • Empty knowledge documents list
  • Invalid webhook JSON structure
  • Inactive main agent parent
  • Collaborator without admin link
  • Super admin attempting creation

🔐 Security & Permissions

Action Allowed Roles Validation
Create Main Agent ADMIN only UserHelper.resolveAdminUidForMainAgent()
Create Sub-Agent ADMIN, COLLABORATOR UserHelper.validateUserPermissionForSubAgent()
Super Admin ❌ Blocked Explicit check in UserHelper

📊 Business Rules Enforced

  1. One main agent per admin per family - Prevents duplicate main agents
  2. Sub-agent name uniqueness - Within same parent agent only
  3. Active parent requirement - Sub-agents can only be created under active main agents
  4. Family matching - Sub-agent must have same family as parent
  5. Webhook requirement - All agents must have at least one webhook node
  6. Collaborator permissions - Can only create sub-agents under their admin's main agent

🐛 Error Handling

  • Detailed FunctionalException messages with context
  • Automatic resource cleanup on any failure
  • Comprehensive logging at INFO, DEBUG, and ERROR levels

📝 Code Quality

  • ✅ Separation of concerns with dedicated helper classes
  • ✅ Single Responsibility Principle
  • ✅ DRY - No code duplication between main and sub-agent creation
  • ✅ Comprehensive JavaDoc documentation
  • ✅ Consistent logging patterns
  • ✅ Transaction safety with rollback support

🔗 Dependencies

  • FileManagerService - Knowledge document upload
  • N8nService - Workflow creation and deletion
  • UserService - User validation and collaborator linking
  • Jackson ObjectMapper - JSON parsing for webhook extraction

Closes IAV-241

Rapports de requête de fusion