Drupal-OSSA Integration Guide

Complete guide for integrating OSSA (Open Standard for Swarm Architecture) with Drupal modules.

Overview
OSSA Specification
Manifest Structure
Drupal Integration
Agent Types
Validation
Deployment
Examples

Overview

OSSA (Open Standard for Swarm Architecture) provides a standardized way to define, deploy, and orchestrate AI agents. The LLM Platform integrates OSSA deeply into Drupal modules for enterprise-grade agent management.

Key Benefits

Standardization: Consistent agent definitions across platforms
Portability: Deploy agents to multiple orchestrators (Kagent, LibreChat, etc.)
Validation: Automated compliance checking
Security: Isolation and permission controls
Interoperability: Cross-framework agent coordination

OSSA Specification

OSSA defines:

Manifest Format: JSON structure for agent definition
Agent Types: Worker, Coordinator, Observer, etc.
Tool System: Standardized tool definitions
Security Model: Isolation levels and permissions
Communication Protocol: Inter-agent messaging

Core Concepts

Agent: An autonomous AI entity with defined capabilities
Tool: A function the agent can execute
Capability: A high-level skill the agent possesses
Manifest: The JSON definition of an agent
Registry: Central repository of agent definitions

Manifest Structure

Complete Manifest Example

{
  "name": "content-analyzer",
  "version": "1.0.0",
  "type": "worker",
  "description": "Analyzes content for quality, sentiment, and compliance",
  "author": "LLM Platform Team",
  "license": "GPL-2.0-or-later",

  "runtime": {
    "type": "docker",
    "image": "drupal:latest",
    "entrypoint": "php",
    "workdir": "/var/www/html"
  },

  "capabilities": [
    "content_analysis",
    "sentiment_detection",
    "quality_scoring",
    "compliance_checking"
  ],

  "tools": [
    {
      "name": "analyze_content",
      "type": "function",
      "description": "Analyzes content for quality and compliance",
      "parameters": {
        "type": "object",
        "properties": {
          "content": {
            "type": "string",
            "description": "Content to analyze"
          },
          "analysis_type": {
            "type": "string",
            "enum": ["quality", "sentiment", "compliance"],
            "description": "Type of analysis to perform"
          }
        },
        "required": ["content", "analysis_type"]
      },
      "returns": {
        "type": "object",
        "properties": {
          "score": {
            "type": "number",
            "description": "Analysis score (0-1)"
          },
          "details": {
            "type": "object",
            "description": "Detailed analysis results"
          }
        }
      }
    }
  ],

  "dependencies": [
    {
      "name": "ai",
      "version": ">=1.0.0",
      "type": "drupal-module"
    },
    {
      "name": "ai_agents",
      "version": ">=1.0.0",
      "type": "drupal-module"
    }
  ],

  "security": {
    "isolation_level": "container",
    "permissions": [
      "read:content",
      "execute:ai_analysis"
    ],
    "resource_limits": {
      "memory": "512M",
      "cpu": "1.0",
      "timeout": 300
    }
  },

  "configuration": {
    "ai_provider": {
      "type": "string",
      "default": "openai",
      "description": "AI provider to use"
    },
    "temperature": {
      "type": "number",
      "default": 0.7,
      "description": "AI temperature setting"
    }
  },

  "metadata": {
    "tags": ["content", "analysis", "ai"],
    "category": "content-management",
    "support_url": "https://gitlab.bluefly.io/llm/agents/content-analyzer",
    "documentation_url": "https://gitlab.bluefly.io/llm/agents/content-analyzer/-/wikis/home"
  }
}

Drupal Integration

Module Structure for OSSA

module_name/
├── .agents/
│   ├── agent-1/
│   │   ├── manifest.json          # OSSA manifest
│   │   ├── README.md              # Agent documentation
│   │   └── tools/
│   │       ├── tool1.php
│   │       └── tool2.php
│   └── agent-2/
│       └── manifest.json
├── src/
│   ├── Agent/                     # Agent implementations
│   │   ├── ContentAnalyzer.php
│   │   └── WorkflowOrchestrator.php
│   ├── Plugin/
│   │   └── OssaTool/             # OSSA tool plugins
│   │       ├── AnalyzeContent.php
│   │       └── ProcessWorkflow.php
│   └── Service/
│       ├── OssaRegistryService.php
│       └── AgentDeploymentService.php
└── module_name.info.yml

Agent Implementation

<?php

namespace Drupal\module_name\Agent;

use Drupal\ai_agents_ossa\OssaAgentInterface;
use Drupal\ai_agents_ossa\OssaAgentBase;

/**
 * Content Analyzer OSSA Agent.
 *
 * @OssaAgent(
 *   id = "content_analyzer",
 *   label = @Translation("Content Analyzer"),
 *   manifest_path = ".agents/content-analyzer/manifest.json"
 * )
 */
class ContentAnalyzer extends OssaAgentBase implements OssaAgentInterface {

  /**
   * {@inheritdoc}
   */
  public function execute(array $context): array {
    $content = $context['content'] ?? '';
    $analysis_type = $context['analysis_type'] ?? 'quality';

    // Load AI provider
    $ai_provider = $this->getAiProvider();

    // Perform analysis
    $result = match ($analysis_type) {
      'quality' => $this->analyzeQuality($content, $ai_provider),
      'sentiment' => $this->analyzeSentiment($content, $ai_provider),
      'compliance' => $this->checkCompliance($content, $ai_provider),
      default => throw new \InvalidArgumentException('Invalid analysis type'),
    };

    return [
      'success' => TRUE,
      'score' => $result['score'],
      'details' => $result['details'],
    ];
  }

  /**
   * Analyzes content quality.
   */
  protected function analyzeQuality(string $content, $provider): array {
    $prompt = "Analyze the quality of this content:\n\n{$content}";
    $response = $provider->chat($prompt);

    return [
      'score' => $this->extractScore($response),
      'details' => $this->extractDetails($response),
    ];
  }

}

OSSA Tool Plugin

<?php

namespace Drupal\module_name\Plugin\OssaTool;

use Drupal\ai_agents_ossa\Plugin\OssaToolBase;

/**
 * Analyze Content OSSA Tool.
 *
 * @OssaTool(
 *   id = "analyze_content",
 *   label = @Translation("Analyze Content"),
 *   description = @Translation("Analyzes content for quality and compliance"),
 *   agent = "content_analyzer"
 * )
 */
class AnalyzeContent extends OssaToolBase {

  /**
   * {@inheritdoc}
   */
  public function execute(array $parameters): array {
    $content = $parameters['content'] ?? '';
    $analysis_type = $parameters['analysis_type'] ?? 'quality';

    // Validate input
    $this->validateParameters($parameters);

    // Execute analysis
    $agent = $this->getAgent('content_analyzer');
    $result = $agent->execute([
      'content' => $content,
      'analysis_type' => $analysis_type,
    ]);

    return $result;
  }

  /**
   * {@inheritdoc}
   */
  public function getParameterSchema(): array {
    return [
      'type' => 'object',
      'properties' => [
        'content' => [
          'type' => 'string',
          'description' => 'Content to analyze',
        ],
        'analysis_type' => [
          'type' => 'string',
          'enum' => ['quality', 'sentiment', 'compliance'],
          'description' => 'Type of analysis to perform',
        ],
      ],
      'required' => ['content', 'analysis_type'],
    ];
  }

}

Service Definition

# module_name.services.yml
services:
  module_name.ossa_registry:
    class: Drupal\module_name\Service\OssaRegistryService
    arguments:
      - '@entity_type.manager'
      - '@config.factory'
      - '@logger.factory'
      - '@file_system'
    tags:
      - { name: ossa_registry }

  module_name.agent_deployment:
    class: Drupal\module_name\Service\AgentDeploymentService
    arguments:
      - '@module_name.ossa_registry'
      - '@http_client'
      - '@config.factory'
    tags:
      - { name: agent_deployment }

Agent Types

1. Worker Agent

Executes specific tasks:

{
  "name": "task-executor",
  "type": "worker",
  "capabilities": ["execute_task"],
  "tools": [
    {
      "name": "execute",
      "type": "function"
    }
  ]
}

2. Coordinator Agent

Orchestrates multiple workers:

{
  "name": "workflow-coordinator",
  "type": "coordinator",
  "capabilities": ["orchestrate_workflow", "manage_tasks"],
  "tools": [
    {
      "name": "dispatch_task",
      "type": "function"
    },
    {
      "name": "aggregate_results",
      "type": "function"
    }
  ]
}

3. Observer Agent

Monitors and reports:

{
  "name": "system-monitor",
  "type": "observer",
  "capabilities": ["monitor_system", "report_metrics"],
  "tools": [
    {
      "name": "collect_metrics",
      "type": "function"
    }
  ]
}

4. Specialist Agent

Domain-specific expertise:

{
  "name": "compliance-specialist",
  "type": "specialist",
  "capabilities": ["compliance_checking", "regulation_analysis"],
  "tools": [
    {
      "name": "check_compliance",
      "type": "function"
    }
  ]
}

Validation

OSSA CLI Validation

# Validate manifest
ossa validate .agents/agent-name/manifest.json

# Validate all agents in module
find .agents -name "manifest.json" -exec ossa validate {} \;

# Strict validation with warnings
ossa validate .agents/agent-name/manifest.json --strict

Drupal Validation

<?php

use Drupal\ai_agents_ossa\OssaValidator;

// Validate manifest
$validator = \Drupal::service('ai_agents_ossa.validator');
$result = $validator->validate('/path/to/manifest.json');

if (!$result->isValid()) {
  foreach ($result->getErrors() as $error) {
    \Drupal::logger('ossa')->error($error);
  }
}

Validation Checks

Schema Compliance: Manifest matches OSSA schema
Required Fields: All required fields present
Type Safety: Field types match schema
Tool Definitions: Tools properly defined
Dependencies: Dependencies exist and versions compatible
Security: Security configuration valid

Deployment

Deploy to Kagent (Kubernetes)

<?php

use Drupal\ai_agents_kagent\Service\KagentDeploymentService;

// Deploy agent to Kagent
$kagent = \Drupal::service('ai_agents_kagent.deployment');
$result = $kagent->deployAgent('content_analyzer', [
  'namespace' => 'production',
  'replicas' => 3,
  'resources' => [
    'memory' => '512M',
    'cpu' => '1.0',
  ],
]);

Deploy to LibreChat

<?php

// Register agent with LibreChat
$librechat = \Drupal::service('code_executor.librechat');
$librechat->registerAgent('content_analyzer', [
  'endpoint' => '/api/agents/content-analyzer',
  'auth_required' => TRUE,
]);

Multi-Platform Deployment

<?php

// Deploy to multiple platforms
$deployment = \Drupal::service('ai_agents_ossa.multi_deployment');
$deployment->deployToAll('content_analyzer', [
  'platforms' => ['kagent', 'librechat', 'langflow'],
  'config' => [
    'memory' => '512M',
    'timeout' => 300,
  ],
]);

Examples

Content Moderation Agent

{
  "name": "content-moderator",
  "version": "1.0.0",
  "type": "specialist",
  "description": "Moderates content for toxicity, spam, and policy violations",

  "capabilities": [
    "toxicity_detection",
    "spam_detection",
    "policy_enforcement"
  ],

  "tools": [
    {
      "name": "moderate_content",
      "type": "function",
      "description": "Moderates content and returns moderation decision",
      "parameters": {
        "type": "object",
        "properties": {
          "content": {
            "type": "string"
          },
          "threshold": {
            "type": "number",
            "default": 0.7
          }
        },
        "required": ["content"]
      }
    }
  ],

  "security": {
    "isolation_level": "container",
    "permissions": ["read:content", "write:moderation"]
  }
}

Workflow Orchestrator Agent

{
  "name": "workflow-orchestrator",
  "version": "1.0.0",
  "type": "coordinator",
  "description": "Orchestrates multi-step AI workflows",

  "capabilities": [
    "workflow_management",
    "task_distribution",
    "result_aggregation"
  ],

  "tools": [
    {
      "name": "create_workflow",
      "type": "function",
      "parameters": {
        "type": "object",
        "properties": {
          "steps": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        }
      }
    },
    {
      "name": "execute_workflow",
      "type": "function",
      "parameters": {
        "type": "object",
        "properties": {
          "workflow_id": {
            "type": "string"
          },
          "context": {
            "type": "object"
          }
        }
      }
    }
  ]
}

Best Practices

1. Manifest Organization

Keep manifests in .agents/ directory:

module_name/
├── .agents/
│   ├── content-analyzer/
│   │   ├── manifest.json
│   │   ├── README.md
│   │   └── tools/
│   ├── workflow-orchestrator/
│   │   └── manifest.json
│   └── data-processor/
│       └── manifest.json

2. Version Control

Use semantic versioning:

{
  "version": "1.2.3",
  "changelog": {
    "1.2.3": "Added compliance checking tool",
    "1.2.0": "Added sentiment analysis",
    "1.1.0": "Improved quality scoring",
    "1.0.0": "Initial release"
  }
}

3. Security

Define appropriate isolation:

{
  "security": {
    "isolation_level": "container",
    "permissions": [
      "read:content",
      "write:analysis_results"
    ],
    "resource_limits": {
      "memory": "512M",
      "cpu": "1.0",
      "timeout": 300
    },
    "network_access": false
  }
}

4. Documentation

Include comprehensive README:

# Content Analyzer Agent

OSSA-compliant agent for content analysis.

## Capabilities
- Quality scoring
- Sentiment analysis
- Compliance checking

## Tools
- analyze_content: Main analysis function

## Configuration
- ai_provider: AI provider to use
- temperature: Analysis temperature

## Usage
See manifest.json for complete API

Troubleshooting

Validation Errors

# Error: Invalid manifest schema
ossa validate .agents/agent/manifest.json --verbose

# Error: Missing required field
# Fix: Add required field to manifest
{
  "name": "agent-name",  # Required
  "version": "1.0.0",    # Required
  "type": "worker"       # Required
}

Deployment Issues

// Check agent status
$status = \Drupal::service('ai_agents_ossa.registry')
  ->getAgentStatus('agent-name');

// Redeploy agent
$deployment = \Drupal::service('ai_agents_kagent.deployment');
$deployment->deployAgent('agent-name', ['force' => TRUE]);