bluefly/ai_agentic_workflows

Production-ready Agentic Flow Management system for Drupal with ECA integration, AI provider support, and visual workflow builder

Maintainers

Details

gitlab.bluefly.io/llm/drupal/ai_agentic_workflows

Homepage

Issues

Documentation

Installs: 15

Dependents: 0

Suggesters: 0

Security: 0

Type:drupal-module

0.1.0 2025-07-19 04:16 UTC

Requires

  • php: >=8.1
  • bluefly/ai_provider_apple: ^0.1
  • bluefly/ai_provider_langchain: ^0.1
  • drupal/ai: ^1.0
  • drupal/ai_automators: ^1.0
  • drupal/ai_provider_anthropic: ^1.0
  • drupal/ai_provider_huggingface: ^1.0
  • drupal/ai_provider_litellm: ^1.0
  • drupal/ai_provider_ollama: ^1.0
  • drupal/ai_provider_openai: ^1.0
  • drupal/core: ^10.3 || ^11
  • drupal/eca: ^2.1
  • drupal/eca_base: ^2.0
  • drupal/eca_content: ^2.0
  • drupal/eca_ui: ^2.0
  • drupal/eca_workflow: ^2.0
  • drupal/encrypt: ^3.0
  • drupal/key: ^1.0
  • drupal/pathauto: ^1.0
  • drupal/queue_ui: ^3.0

Requires (Dev)

  • drupal/core_dev: ^10.3 || ^11
  • drupal/hal: ^1.0
  • drupal/migrate: ^1.0

Suggests

  • drupal/facets: Faceted search for workflow filtering
  • drupal/memcache: Memcached backend for distributed caching
  • drupal/metatag: SEO and metadata management
  • drupal/monitoring: Workflow performance monitoring
  • drupal/redis: High-performance Redis caching for workflows
  • drupal/search_api: Advanced search capabilities for workflow content
  • drupal/webform: Form-based workflow inputs

GPL-2.0-or-later 0165051c174ab1fb1aa1fed9bd675adbbfdee2c1

drupalautomationaiworkflowsecaagenticai-providersworkflow-builder

This package is auto-updated.

Last update: 2025-07-19 04:17:16 UTC

README

An Agentic Flow Management system for Drupal 10+ with ECA integration, AI provider support, and visual workflow builder. This module provides a configurable, exportable, and scalable framework for building AI-powered automation workflows.

🚀 Features

  • Config Entity Based: Exportable, importable, and shareable agentic flows
  • ECA Integration: Uses Event-Condition-Action automation engine for triggers
  • AI Provider Support: Integrates with real AI providers (OpenAI, Anthropic, Ollama, etc.)
  • Admin UI: Complete admin interface at /admin/agentic/flows
  • Cron Integration: Scheduled execution of flows
  • Drush Commands: CLI management and testing
  • Plugin Discovery: Dynamic discovery of ECA and AI provider plugins
  • Advanced Orchestration: Chaining, parallel execution, conditional flows
  • Comprehensive Logging: Detailed execution logs and monitoring
  • API Hooks: Extensible integration points for custom logic

📋 Requirements

  • Drupal: 10.4+ or 11.0+
  • PHP: 8.1+ (8.2+ recommended for Drupal 11)
  • Core Dependencies:
    • ECA module 2.0+
    • AI module 1.0+
    • AI Provider modules (OpenAI, Anthropic, Ollama, etc.)
  • Additional Dependencies:
    • Key module (drupal/key) for secure credential storage
    • Encrypt module (drupal/encrypt) for data encryption
    • Token module (drupal/token) for dynamic content replacement

🛠 Installation

Via Composer (Recommended)

composer require drupal/ai_agentic_workflows
drush en ai_agentic_workflows -y

Manual Installation

  1. Download the module to web/modules/custom/ai_agentic_workflows
  2. Enable via Drush: drush en ai_agentic_workflows -y
  3. Configure permissions for users who need to manage flows

🔧 Configuration

Permissions

Configure user permissions at /admin/people/permissions:

  • Administer agentic workflows: Full access to create, edit, delete flows
  • Execute agentic workflows: Ability to run flows manually
  • View agentic workflows: Read-only access to flow configurations

Initial Setup

  1. Navigate to /admin/agentic/flows
  2. Click "Add Agentic Flow"
  3. Configure your first workflow

📖 Usage

Admin Interface

The main admin interface is available at /admin/agentic/flows and provides:

  • Flow List: View all configured flows with status indicators
  • Flow Builder: Visual interface for creating and editing flows
  • Execution History: Monitor flow execution results
  • Import/Export: Share flows between environments

Creating Your First Flow

  1. Navigate to /admin/agentic/flows
  2. Click "Add Agentic Flow"
  3. Fill in the basic information:
    • Label: "Content Review Workflow"
    • Description: "Automatically review and categorize new content"
  4. Configure the trigger:
    • Event: "Node: After saving a new node"
    • Condition: "Node type is Article" (optional)
  5. Set up the AI action:
    • AI Provider: "OpenAI"
    • AI Action: "Analyze content and suggest categories"
  6. Configure scheduling (optional):
    • Schedule: "0 /6 * *" (every 6 hours)
  7. Save and enable the flow

Drush Commands

List All Flows

drush ai-agentic-workflows:list

Execute a Specific Flow

drush ai-agentic-workflows:execute my_flow_id

Execute All Enabled Flows

drush ai-agentic-workflows:execute-all

Test Flow Configuration

drush ai-agentic-workflows:test my_flow_id

Export Flow Configuration

drush ai-agentic-workflows:export my_flow_id

API Usage

Basic Flow Execution

// Get the flow executor service
$flow_executor = \Drupal::service('ai_agentic_workflows.flow_executor');

// Load a specific flow
$flow = \Drupal::entityTypeManager()
  ->getStorage('agentic_flow')
  ->load('my_flow_id');

// Execute the flow with context
$result = $flow_executor->executeFlow($flow, [
  'node' => $node,
  'user' => $user,
  'custom_data' => $some_data,
]);

Execute All Enabled Flows

$flow_executor = \Drupal::service('ai_agentic_workflows.flow_executor');
$results = $flow_executor->executeAllFlows();

Custom Flow Creation

// Create a new flow programmatically
$flow_storage = \Drupal::entityTypeManager()
  ->getStorage('agentic_flow');

$flow = $flow_storage->create([
  'id' => 'custom_workflow',
  'label' => 'Custom Workflow',
  'description' => 'A custom workflow created programmatically',
  'status' => TRUE,
  'event' => 'node:insert',
  'condition' => 'node:type:article',
  'ai_provider' => 'openai',
  'ai_action' => 'content_analysis',
  'schedule' => '0 2 * * *', // Daily at 2 AM
]);

$flow->save();

🏗 Architecture

Core Components

Config Entity (AgenticFlow)

Stores flow configuration including:

  • Basic metadata (label, description, status)
  • ECA configuration (event, condition)
  • AI configuration (provider, action, parameters)
  • Schedule information (cron expression)
  • Advanced settings (retry logic, timeout, etc.)

Services

  • FlowExecutorService: Core execution engine
  • PluginDiscoveryService: Discovers available ECA and AI provider plugins
  • FlowOrchestrationService: Handles complex flow orchestration

ECA Integration

The module provides ECA plugins:

  • Action: ExecuteAgenticFlow - Executes a flow from ECA
  • Condition: FlowExecutionSuccessful - Checks if a flow executed successfully

Integration Points

ECA Events

  • Node events (insert, update, delete)
  • User events (login, logout, registration)
  • Custom events (hook_eca_event_info_alter)

AI Providers

  • OpenAI (GPT-3.5, GPT-4)
  • Anthropic (Claude)
  • Ollama (local models)
  • Hugging Face
  • Custom providers

Scheduling

  • Drupal cron integration
  • ECA time events
  • Custom scheduling via hooks

🔌 Extending the Module

Adding Custom AI Actions

  1. Create a plugin that implements the AI action interface
  2. Register it with the AI provider system
  3. The action will automatically appear in the form selectors

Example:

namespace Drupal\my_module\Plugin\AI\Action;

use Drupal\ai\Plugin\AIActionBase;

/**
 * @AIAction(
 *   id = "my_custom_action",
 *   label = @Translation("My Custom Action"),
 *   description = @Translation("Performs a custom AI action")
 * )
 */
class MyCustomAction extends AIActionBase {
  // Implementation...
}

Adding Custom ECA Events

  1. Create ECA plugins following ECA module guidelines
  2. The plugins will automatically appear in the form selectors

Custom Flow Types

Extend the base flow entity to create specialized flow types:

namespace Drupal\my_module\Entity;

use Drupal\ai_agentic_workflows\Entity\AgenticFlow;

/**
 * @ConfigEntityType(
 *   id = "my_specialized_flow",
 *   label = @Translation("My Specialized Flow"),
 *   config_prefix = "my_specialized_flow",
 *   entity_keys = {
 *     "id" = "id",
 *     "label" = "label",
 *   },
 *   config_export = {
 *     "id",
 *     "label",
 *     "description",
 *     "status",
 *     "custom_field",
 *   }
 * )
 */
class MySpecializedFlow extends AgenticFlow {
  // Custom implementation...
}

🧪 Testing

Running Tests

# Run all tests
phpunit web/modules/custom/ai_agentic_workflows/tests

# Run specific test class
phpunit web/modules/custom/ai_agentic_workflows/tests/src/Unit/FlowExecutorServiceTest.php

# Run with coverage
phpunit --coverage-html coverage web/modules/custom/ai_agentic_workflows/tests

Test Flow Execution

# Test a specific flow
drush ai-agentic-workflows:execute test_flow

# Test with debug output
drush ai-agentic-workflows:execute test_flow --debug

Writing Tests

See the tests/ directory for examples of:

  • Unit tests for services
  • Kernel tests for entities
  • Functional tests for admin interface
  • Integration tests for ECA plugins

📦 Configuration Management

Export/Import Flows

# Export a specific flow
drush config:export:single ai_agentic_workflows.agentic_flow.my_flow

# Export all flows
drush config:export:single ai_agentic_workflows.agentic_flow.*

# Import flows
drush config:import:single ai_agentic_workflows.agentic_flow.my_flow

Deployment

  1. Export flows from development environment
  2. Commit configuration to version control
  3. Import flows in production environment
  4. Verify flow status and permissions

🔍 Monitoring & Debugging

Logging

The module provides comprehensive logging:

// In settings.php - Enable debug logging
$config['system.logging']['error_level'] = 'verbose';

// Check flow execution logs
drush watchdog:show --type=ai_agentic_workflows

Performance Monitoring

  • Monitor flow execution times
  • Track AI provider response times
  • Monitor resource usage
  • Set up alerts for failed flows

Common Issues

  1. No AI providers available: Ensure AI provider modules are installed and configured
  2. ECA plugins not found: Verify ECA module is properly installed
  3. Flow execution fails: Check logs at /admin/reports/dblog
  4. Permission denied: Verify user has appropriate permissions

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Make your changes following Drupal coding standards
  4. Add tests for new functionality
  5. Update documentation
  6. Submit a pull request

Development Setup

# Clone the repository
git clone https://github.com/your-org/ai_agentic_workflows.git

# Install dependencies
composer install

# Run tests
phpunit tests/

# Check coding standards
phpcs --standard=Drupal web/modules/custom/ai_agentic_workflows/

📄 License

This project is licensed under the GPL-2.0-or-later License - see the LICENSE file for details.

🆘 Support

  • Documentation: See the docs/ directory for detailed guides
  • Issues: Report bugs and feature requests on the issue tracker
  • Community: Join the Drupal community discussions
  • Security: Report security issues privately to the maintainers

🔗 Related Modules

  • ECA - Event-Condition-Action automation engine
  • AI - Drupal AI framework
  • AI Providers - Various AI provider modules
  • Queue UI - Monitor flow execution queues

Version: 0.1.0
Drupal Compatibility: 10.4+ / 11.0+
PHP Compatibility: 8.1+ (8.2+ recommended for Drupal 11)
Maintainers: Bluefly.io