README

Advanced multi-agent workflows extending ECA and AI Agents contrib modules with CrewAI orchestration, intelligent agent coordination, and enterprise automation patterns.

Overview

The AI Agent Orchestra module provides a comprehensive framework for orchestrating multiple AI agents in complex workflows. It extends Drupal's ECA (Event-Condition-Action) system with AI-specific capabilities, enabling sophisticated multi-agent coordination patterns for enterprise automation.

Features

Plugin-Based Agent System: Discover and manage AI agents using Drupal's plugin architecture with PHP 8 attributes
ECA Workflow Integration: Visual workflow building with AI agent actions, conditions, and events
Memory Optimization: Advanced monitoring and management to prevent out-of-memory issues
Performance Tracking: Real-time metrics collection for agent performance analysis
State Management: Persistent agent state across requests with intelligent caching
Queue Processing: Asynchronous agent task execution via Drupal's Queue API
CrewAI Patterns: Implementation of CrewAI orchestration patterns for complex workflows
Enterprise Security: Integration with Key module for secure credential management

Requirements

Drupal 10.4 or higher / Drupal 11
PHP 8.1 or higher
ECA module suite (eca, eca_base, eca_content, eca_queue, eca_workflow)
AI module (drupal/ai) ^1.0
Queue UI module (drupal/queue_ui)
Key module (drupal/key)
LLM module (bluefly/llm)

Installation

Install via Composer:

composer require bluefly/ai_agent_orchestra

Enable the module and dependencies:
```
drush en ai_agent_orchestra -y
```
Configure settings at /admin/config/ai/agent-orchestra

Usage

Creating Agent Plugins

Create custom agents using PHP 8 attributes:

<?php

namespace Drupal\my_module\Plugin\AiAgent;

use Drupal\ai_agent_orchestra\Attribute\AiAgent;
use Drupal\ai_agent_orchestra\Plugin\AiAgentPluginBase;

#[AiAgent(
  id: "content_analyzer",
  label: "Content Analysis Agent",
  description: "Analyzes content quality and provides recommendations",
  category: "content"
)]
class ContentAnalyzerAgent extends AiAgentPluginBase {
  
  public function execute(array $context): array {
    // Agent implementation
    $content = $context['content'];
    
    // Perform analysis
    $analysis = $this->analyzeContent($content);
    
    return [
      'status' => 'success',
      'analysis' => $analysis,
      'recommendations' => $this->generateRecommendations($analysis)
    ];
  }
}

Orchestrating Workflows

Use the orchestrator service to execute multi-agent workflows:

$orchestrator = \Drupal::service('ai_agent_orchestra.orchestrator');

// Define workflow
$workflow = [
  'agents' => [
    ['id' => 'research', 'task' => 'Gather information about Drupal 11'],
    ['id' => 'writer', 'task' => 'Create blog post from research'],
    ['id' => 'editor', 'task' => 'Review and polish content']
  ],
  'context' => [
    'topic' => 'Drupal 11 Features',
    'target_audience' => 'developers'
  ]
];

// Execute workflow
$result = $orchestrator->executeWorkflow('content_creation', $workflow);

ECA Integration

Create visual workflows in ECA that utilize AI agents:

Navigate to Configuration > ECA > Models
Create a new model
Add AI Agent Orchestra actions:
- Execute Agent
- Execute Agent Workflow
- Evaluate Agent Performance
Configure conditions and events

Monitoring Performance

// Get performance metrics
$monitor = \Drupal::service('ai_agent_orchestra.performance_monitor');
$metrics = $monitor->getMetrics('content_analyzer');

// Check memory usage
$memory = \Drupal::service('ai_agent_orchestra.memory_monitor');
$status = $memory->getStatus();

Drush Commands

# View agent status
drush ai-agent:status

# Monitor memory usage
drush ai-agent:memory-status

# Execute a workflow
drush ai-agent:execute-workflow [workflow_id]

# Process agent queue
drush queue:run ai_agent_tasks

# Clear agent cache
drush ai-agent:cache-clear

API Reference

Services

ai_agent_orchestra.registry - Agent plugin discovery and management
ai_agent_orchestra.orchestrator - Workflow execution engine
ai_agent_orchestra.memory_monitor - Memory usage monitoring
ai_agent_orchestra.cache_manager - Agent response caching
ai_agent_orchestra.performance_monitor - Performance metrics
ai_agent_orchestra.state_manager - Agent state persistence

Events

The module dispatches several events for workflow customization:

ai_agent_orchestra.workflow.pre_execute - Before workflow execution
ai_agent_orchestra.workflow.post_execute - After workflow execution
ai_agent_orchestra.agent.pre_execute - Before agent execution
ai_agent_orchestra.agent.post_execute - After agent execution

Configuration

Memory Limits

Configure memory thresholds in settings.php:

$settings['ai_agent_orchestra.memory_limit'] = '512M';
$settings['ai_agent_orchestra.memory_threshold'] = 0.8; // 80% warning

Cache Settings

$settings['ai_agent_orchestra.cache_ttl'] = 3600; // 1 hour
$settings['ai_agent_orchestra.cache_max_size'] = '100M';

Troubleshooting

Common Issues

Memory Limit Exceeded
- Increase PHP memory limit
- Enable memory monitoring
- Use queue processing for large tasks
Agent Not Found
- Clear plugin cache: drush cr
- Check agent plugin annotations
- Verify namespace and file location
Workflow Timeout
- Increase PHP execution time
- Use asynchronous queue processing
- Break large workflows into smaller tasks

Development

Running Tests

# Run all tests
./vendor/bin/phpunit web/modules/custom/ai_agent_orchestra

# Run specific test
./vendor/bin/phpunit web/modules/custom/ai_agent_orchestra/tests/src/Unit/AgentRegistryTest.php

Debugging

Enable debug mode:

$settings['ai_agent_orchestra.debug'] = TRUE;

Support

Issue Queue: https://github.com/bluefly/ai_agent_orchestra/issues
Documentation: https://docs.bluefly.dev/ai-agent-orchestra
Packagist: https://packagist.org/packages/bluefly/ai_agent_orchestra

License

This project is licensed under the GPL-2.0-or-later license.

bluefly / ai_agent_orchestra

Maintainers

Details