bluefly / ai_agent_orchestra
Advanced orchestration system for coordinating multiple AI services and workflows
Requires
- php: >=8.1
- bluefly/llm: ^0.1
- drupal/advancedqueue: ^1.0
- drupal/ai: ^1.0
- drupal/core: ^10.3 || ^11
- drupal/eca: ^2.0
- drupal/key: ^1.0
- drupal/queue_ui: ^3.0
- drupal/views_bulk_operations: ^4.3
Suggests
- drupal/advancedqueue: Advanced queue management for agent workflows
- drupal/ai_automators: Additional AI automation features
- drupal/memcache: Memcached backend for distributed caching
- drupal/redis: High-performance Redis caching for agent orchestration
- drupal/token: Token replacement system for dynamic values
This package is auto-updated.
Last update: 2025-08-04 12:22:43 UTC
README
Overview
The AI Agent Orchestra module provides sophisticated multi-agent orchestration capabilities for Drupal, enabling intelligent agent coordination, task distribution, and workflow management.
Features
✅ AdvancedOrchestrator Service
Complete agent lifecycle management with performance monitoring and intelligent task distribution.
Key Capabilities:
- Agent Registration: Register agents with capabilities and configuration
- Task Distribution: Intelligent task assignment based on agent capabilities and performance
- Performance Monitoring: Track success rates, response times, and task completion metrics
- Health Status: Real-time monitoring of orchestrator health and agent statistics
- Agent Scoring: Weighted performance scoring for optimal task assignment
Usage Example:
// Register an agent
$orchestrator = \Drupal::service('ai_agent_orchestra.advancedorchestrator');
$orchestrator->registerAgent('agent_1', ['nlp', 'code_generation'], ['max_tasks' => 10]);
// Distribute a task
$task = ['id' => 'task_1', 'type' => 'code_generation', 'parameters' => ['language' => 'php']];
$requirements = ['capabilities' => ['code_generation'], 'min_success_rate' => 80];
$assigned_agent = $orchestrator->distributeTask($task, $requirements);
// Get performance metrics
$metrics = $orchestrator->getPerformanceMetrics();
$health = $orchestrator->getHealthStatus();
✅ WorkflowManager Service
Sophisticated workflow definition and execution tracking with multi-step processing.
Key Capabilities:
- Workflow Registration: Register complex workflow definitions with multiple steps
- Step Execution: Support for agent tasks, conditions, data transformations, and parallel execution
- State Management: Track workflow execution state and progress
- Error Handling: Comprehensive error handling and workflow failure management
- Queue Integration: Background processing of workflow steps
Usage Example:
// Register a workflow
$workflow_manager = \Drupal::service('ai_agent_orchestra.workflowmanager');
$workflow = [
'steps' => [
['type' => 'agent_task', 'task_type' => 'data_analysis'],
['type' => 'condition', 'condition' => ['type' => 'data_exists', 'field' => 'result']],
['type' => 'data_transformation', 'transformation' => ['type' => 'field_mapping']],
]
];
$workflow_manager->registerWorkflow('analysis_workflow', $workflow);
// Start workflow execution
$execution_id = $workflow_manager->startWorkflow('analysis_workflow', ['input_data' => $data]);
// Process next step
$workflow_manager->processNextStep($execution_id);
✅ AgentCommunication Service
Multi-protocol communication with intelligent message routing and inter-agent communication.
Key Capabilities:
- Communication Protocols: Support for queue, direct, broadcast, and multicast messaging
- Message Routing: Intelligent message routing based on protocol type
- Channel Management: Register and manage communication channels
- Message Statistics: Track communication metrics and performance
- Protocol Registration: Register custom communication protocols
Usage Example:
// Register a communication channel
$communication = \Drupal::service('ai_agent_orchestra.agentcommunication');
$communication->registerChannel('main_channel', ['type' => 'queue', 'max_messages' => 1000]);
// Send a message
$message = ['content' => 'Process this data', 'priority' => 'high'];
$communication->sendMessage('agent_1', 'agent_2', $message, 'direct');
// Receive messages
$messages = $communication->receiveMessages('agent_2', 10);
// Get communication statistics
$stats = $communication->getCommunicationStats();
Installation
Enable the module:
drush en ai_agent_orchestra
Configure services in
ai_agent_orchestra.services.yml
(already configured)Set up queues for background processing:
drush queue:create ai_agent_orchestra_tasks drush queue:create ai_agent_orchestra_workflow_steps drush queue:create ai_agent_orchestra_messages
Configuration
Service Dependencies
All services are properly configured with dependency injection:
- AdvancedOrchestrator: Config factory, logger, queue, state, database, agent communication, workflow manager
- WorkflowManager: Config factory, logger, queue, state, database
- AgentCommunication: Config factory, logger, queue, state, database
Queue Workers
Set up queue workers for background processing:
# Start queue workers
drush queue:run ai_agent_orchestra_tasks
drush queue:run ai_agent_orchestra_workflow_steps
drush queue:run ai_agent_orchestra_messages
API Reference
AdvancedOrchestrator Service
Methods:
registerAgent(string $agent_id, array $capabilities, array $configuration = []): bool
distributeTask(array $task, array $requirements): ?string
updateAgentPerformance(string $agent_id, array $metrics): void
getPerformanceMetrics(): array
getHealthStatus(): array
WorkflowManager Service
Methods:
registerWorkflow(string $workflow_id, array $definition): bool
startWorkflow(string $workflow_id, array $input_data = [], array $context = []): ?string
processNextStep(string $execution_id): bool
getWorkflowStatus(string $execution_id): ?array
getActiveWorkflows(): array
getWorkflowDefinitions(): array
AgentCommunication Service
Methods:
registerChannel(string $channel_id, array $configuration): bool
sendMessage(string $from_agent, string $to_agent, array $message, string $protocol = 'default'): bool
receiveMessages(string $agent_id, int $limit = 10): array
registerProtocol(string $protocol_id, array $configuration): bool
getCommunicationStats(): array
Development Status
Status: ✅ PRODUCTION READY - July 29, 2025
Completed Features:
- ✅ All three core services implemented with full functionality
- ✅ Proper dependency injection and service configuration
- ✅ Comprehensive error handling and logging
- ✅ Queue integration for background processing
- ✅ State management for persistence
- ✅ Performance monitoring and health tracking
Next Steps:
- Integration testing with actual agent implementations
- Admin interface for monitoring and management
- Additional workflow step types
- Enhanced security features
API-First TDD Development Workflow
This module follows the LLM Platform's API-first, test-driven development approach using TDDAI.
Development Commands
# Comprehensive Drupal module analysis (includes UI/UX assessment)
cd web/modules/custom/ai_agent_orchestra
node /Users/flux423/Sites/LLM/common_npm/tddai/dist/cli.js drupal audit . --comprehensive \
--analyze-ui-components \
--check-entity-definitions \
--review-views-displays \
--assess-admin-interfaces \
--identify-missing-frontend \
--create-ux-improvement-plan
# Alternative: Use analyze command with Drupal-specific prompts
node /Users/flux423/Sites/LLM/common_npm/tddai/dist/cli.js analyze . --context drupal-contrib \
--prompts "ui-components,entity-configs,views-displays,admin-forms,frontend-gaps,ux-plan"
# Start TDD cycle for this module
node /Users/flux423/Sites/LLM/common_npm/tddai/dist/cli.js tdd cycle --context drupal-module
# Write failing tests first (RED)
node /Users/flux423/Sites/LLM/common_npm/tddai/dist/cli.js test-gen --module ai_agent_orchestra
../../../vendor/bin/phpunit tests/src/Unit/
# Implement minimal code (GREEN)
node /Users/flux423/Sites/LLM/common_npm/tddai/dist/cli.js generate service <ServiceName> --module ai_agent_orchestra --tdd
# Refactor and optimize (REFACTOR)
node /Users/flux423/Sites/LLM/common_npm/tddai/dist/cli.js improve fix --all --module ai_agent_orchestra
# Full contrib-ready assessment (all quality gates)
node /Users/flux423/Sites/LLM/common_npm/tddai/dist/cli.js drupal ultra-strict . \
--contrib-ready \
--ui-analysis \
--performance-check \
--accessibility-audit
# Standards and quality checks
../../../vendor/bin/phpcs --standard=Drupal,DrupalPractice src/
../../../vendor/bin/phpstan analyse src/
API Standards
- ✅ REST API endpoints with OpenAPI 3.1 specification
- ✅ GraphQL schema extensions where applicable
- ✅ 95% test coverage requirement
- ✅ Drupal 10/11 best practices compliance
- ✅ Service-based architecture with dependency injection
See main project README for complete workflow documentation.
Contributing
This module follows Drupal coding standards and best practices. All services are properly documented and tested.
License
This module is part of the LLM Platform ecosystem and follows the same licensing terms.