README

⚡ Multi-Agent AI Coordination Engine

What This Does (No Bullshit)

Coordinates multiple AI agents to handle complex tasks that single agents can't solve alone.

Core Functions:

Multi-Agent Orchestration: Run 3-10 AI agents simultaneously on different parts of a problem
Provider Management: Switch between Ollama, Anthropic, OpenAI, LibreChat automatically
Circuit Breaker Protection: Disable failing agents, prevent cascading failures
Semantic Content Analysis: AI-powered understanding of text, entities, sentiment, topics
ECA Workflow Integration: AI decision-making in Event-Condition-Action workflows

Real Examples:

// Content analysis with 3 agents running in parallel
$result = $orchestra->orchestrateAgents([
  'sentiment_analyzer' => ['provider' => 'anthropic', 'model' => 'claude-3-sonnet'],
  'entity_extractor' => ['provider' => 'ollama', 'model' => 'llama2'],  
  'topic_classifier' => ['provider' => 'openai', 'model' => 'gpt-4']
], $content, ['timeout' => 60]);

// Complex document processing pipeline
$pipeline = $orchestra->createPipeline([
  'analyze_structure' => ['agent' => 'document_analyzer'],
  'extract_entities' => ['agent' => 'ner_processor', 'depends_on' => 'analyze_structure'],
  'generate_summary' => ['agent' => 'summarizer', 'depends_on' => ['analyze_structure', 'extract_entities']],
  'fact_check' => ['agent' => 'fact_checker', 'depends_on' => 'generate_summary']
]);

Why You Need This

Single AI agents hit limits fast:

Can't handle multiple perspectives simultaneously
No automatic retry/failover when providers are down
No coordination between different AI capabilities
Limited context sharing between operations

This module solves that by:

Running multiple agents concurrently (5x faster complex analysis)
Automatic provider failover (99.9% uptime even when OpenAI is down)
Intelligent workload distribution (right agent for each task)
Circuit breaker protection (one bad agent doesn't kill everything)

Installation

# Install AI providers first
composer require drupal/ai drupal/ai_provider_anthropic drupal/ai_provider_ollama drupal/ai_provider_openai

# Enable modules
drush en ai ai_provider_anthropic ai_provider_ollama ai_provider_openai ai_agent_orchestra

# Configure at /admin/config/llm-platform/ai-agent-orchestra

Configuration

Provider Setup

# Configure at least one provider
providers:
  ollama:
    enabled: true
    endpoint: "http://localhost:11434"
    model: "llama2"
  anthropic:
    enabled: true
    api_key: "sk-ant-..."
    model: "claude-3-sonnet-20240229"
  openai:
    enabled: true  
    api_key: "sk-..."
    model: "gpt-4"

Agent Coordination

coordination:
  max_concurrent_agents: 5      # How many agents run at once
  timeout_seconds: 120          # Max time per agent
  retry_attempts: 3             # Retry failed operations
  circuit_breaker:
    failure_threshold: 5        # Failures before disabling agent
    recovery_timeout: 300       # Time before re-enabling

Usage Examples

Multi-Agent Content Analysis

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

// Analyze content with multiple AI perspectives
$analysis = $orchestra->orchestrateAgents([
  'sentiment' => [
    'provider' => 'anthropic',
    'prompt' => 'Analyze the sentiment of this content: {content}',
    'parameters' => ['temperature' => 0.3]
  ],
  'entities' => [
    'provider' => 'ollama', 
    'prompt' => 'Extract all person, organization, and location entities: {content}',
    'parameters' => ['temperature' => 0.1]
  ],
  'keywords' => [
    'provider' => 'openai',
    'prompt' => 'Extract the 10 most important keywords: {content}',
    'parameters' => ['temperature' => 0.2]
  ]
], $content);

// Results: ['sentiment' => {...}, 'entities' => {...}, 'keywords' => {...}]

Semantic Analysis Service

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

// AI-powered content understanding
$analysis = $semantic->analyzeContent($text, [
  'enable_sentiment' => TRUE,
  'enable_entities' => TRUE, 
  'enable_topics' => TRUE,
  'confidence_threshold' => 0.8
]);

/* Returns:
{
  "sentiment": {"score": 0.8, "label": "positive"},
  "entities": [{"text": "Apple Inc", "type": "organization", "confidence": 0.95}],
  "topics": [{"topic": "technology", "confidence": 0.87}]
}
*/

ECA Workflow Integration

# In ECA model configuration - trigger AI analysis on content save
events:
  - type: "entity_insert"
    bundle: "article"
conditions:
  - type: "ai_agent_orchestra_confidence"
    threshold: 0.8
actions:
  - type: "ai_agent_orchestra_analyze"
    agents: ["sentiment_analyzer", "entity_extractor"]
    context: 
      content: "[entity:field_body]"
      title: "[entity:title]"

DITA Integration Example

// Enhanced DITA content analysis
$dita_service = \Drupal::service('ai_agent_orchestra.integration.dita');

$analysis = $dita_service->analyzeDitaContent($dita_node, [
  'check_structure' => TRUE,
  'validate_links' => TRUE,
  'assess_quality' => TRUE,
  'generate_metadata' => TRUE
]);

// Auto-generates DITA metadata, validates cross-references, checks compliance

API Endpoints

REST API

# Execute multi-agent analysis
curl -X POST "/api/ai-agent-orchestra/orchestrate" \
  -H "Content-Type: application/json" \
  -d '{
    "agents": {
      "analyzer": {"provider": "anthropic", "prompt": "Analyze: {content}"},
      "summarizer": {"provider": "openai", "prompt": "Summarize: {content}"}
    },
    "content": "Your content here",
    "options": {"parallel": true, "timeout": 60}
  }'

# Check agent status
curl "/api/ai-agent-orchestra/status"

Monitoring

Performance Metrics

Agent execution times and success rates
Provider availability and response times
Circuit breaker status and failure counts
Resource usage (memory, CPU, API calls)
Cost tracking per provider

Health Checks

# Check system status
drush ai-orchestra:status

# Test agent coordination  
drush ai-orchestra:test-agents

# View performance metrics
drush ai-orchestra:metrics

Module Integrations

Automatic Detection

The module automatically detects and integrates with:

DITA CCMS: AI-powered content analysis for DITA topics
MCP Registry: Extended AI capabilities via MCP servers
Government Compliance: AI compliance checking
AI Agentic Workflows: Provides agents for complex workflow steps
Code Executor: AI agents can request code execution for analysis

Integration Configuration

// In settings form - auto-detects available modules
'integrations' => [
  'dita_ccms_enabled' => TRUE,          // Auto-detected if module exists
  'mcp_registry_enabled' => TRUE,       // Auto-detected if module exists  
  'gov_compliance_enabled' => FALSE,    // User configurable
  'ai_agentic_workflows_enabled' => TRUE,
  'code_executor_enabled' => TRUE,
]

Development

Adding Custom Agents

// Custom agent definition
class CustomAnalysisAgent implements AgentInterface {
  public function execute(array $context): array {
    // Custom AI processing logic
    return ['analysis_result' => $result];
  }
}

Service Extension

// Extend orchestration service
class CustomOrchestrator extends AgentOrchestratorService {
  public function customWorkflow(array $agents, $data): array {
    // Custom multi-agent coordination
    return $this->orchestrateAgents($agents, $data, ['strategy' => 'custom']);
  }
}

Performance

Benchmarks

Single agent: 5-10 seconds for complex analysis
Multi-agent (3-5 agents): 8-15 seconds for comprehensive analysis
Circuit breaker: Sub-second failover when agent fails
Provider switching: 2-3 second fallback to alternative provider

Resource Usage

Memory: 50-200MB per active agent
CPU: Scales with number of concurrent agents
API Costs: Distributed across multiple providers for cost optimization

Security

API Key Protection: All provider keys encrypted at rest
Rate Limiting: Prevents API abuse and cost overruns
Request Validation: Input sanitization and content filtering
Audit Logging: Complete execution trails for compliance
Circuit Breaker: Automatic protection against failing providers

License

GPL-2.0+

bluefly / ai_agent_orchestra

Maintainers

Details