@bluefly/openstandardagents 0.1.9 → 0.2.5-RC

package/website/content/docs/integrations/aiflow.md

@@ -0,0 +1,104 @@
+# AIFlow Framework Integration with OSSA
+
+## Overview
+
+AIFlow is a Python-based social agent framework that enables personality-driven, emotionally intelligent AI agents for autonomous social media content generation. This integration demonstrates how AIFlow agents are wrapped in OSSA 1.0 manifests for Kubernetes orchestration and deployment through agent-buildkit.
+
+For complete integration analysis, see: [agent-buildkit AIFlow Integration Guide](https://github.com/blueflyio/openstandardagents/wiki/AIFlow-Integration-with-OSSA-BuildKit-and-K-Agent)
+
+## Core Components
+
+### OSSA Manifest
+
+**Location**: [agent-buildkit/examples/aiflow-integration/social-agent-aiflow.ossa.yaml](https://github.com/blueflyio/openstandardagents/blob/development/examples/aiflow-integration/social-agent-aiflow.ossa.yaml)
+
+The manifest defines the agent's identity, runtime configuration, capabilities, and deployment requirements. It conforms to OSSA 1.0 specification.
+
+**Key Manifest Sections**:
+
+- **Agent Identity**: `social-agent-aiflow`, version 1.0.0, role: chat
+- **Runtime**: Docker image `aiflow/agent:1.0.0`, Python 3.12+, resource requirements
+- **Capabilities**: `generate_post`, `generate_response` with defined schemas
+- **Dependencies**: Required integration with `agent-brain` for cognitive functions
+- **Environment**: Required secrets for Anthropic API, Twitter API, Telegram Bot, PostgreSQL
+
+### OpenAPI Specification
+
+**Location**: [agent-buildkit/openapi/aiflow-agent.openapi.yml](https://github.com/blueflyio/openstandardagents/blob/development/openapi/aiflow-agent.openapi.yml)
+
+The OpenAPI 3.1 specification defines the REST API interface for the AIFlow agent, including:
+- FastAPI bridge endpoints for AIFlow Sia runtime
+- Request/response schemas for all capabilities
+- Kubernetes metadata extensions (x-k-agent) for orchestration
+- Health check endpoints and observability metrics
+
+### OSSA Schema
+
+**Location**: [OSSA/spec/v0.2.5-RC/ossa-0.2.5-RC.schema.json](https://github.com/blueflyio/openstandardagents/blob/development/spec/v0.2.5-RC/ossa-0.2.5-RC.schema.json)
+
+JSON Schema definition for OSSA 1.0 manifest validation. All agent manifests must conform to this schema.
+
+## Validation
+
+### OSSA Manifest Validation
+
+Validate the manifest against OSSA 1.0 schema:
+
+```yaml
+ossa validate examples/aiflow-integration/social-agent-aiflow.ossa.yaml
+```
+
+This checks:
+- Schema compliance against OSSA 1.0 specification
+- Required fields and type correctness
+- Capability schema definitions
+- Dependency declarations
+- Environment variable definitions
+
+### OpenAPI Specification Validation
+
+Validate OpenAPI spec with strict mode and K-Agent metadata checks:
+
+```yaml
+buildkit openapi validate --spec openapi/aiflow-agent.openapi.yml --strict
+```
+
+This validates:
+- OpenAPI 3.1 syntax and semantics
+- x-k-agent extension metadata for Kubernetes
+- Endpoint schemas match OSSA capability definitions
+- Health check endpoint compliance
+
+## Deployment
+
+Deploy via agent-buildkit orchestration:
+
+```yaml
+buildkit orchestrate deploy --manifest examples/aiflow-integration/social-agent-aiflow.ossa.yaml
+```
+
+This generates Kubernetes manifests and deploys the agent with:
+- Rolling deployment strategy
+- Horizontal Pod Autoscaling (HPA)
+- Health checks and readiness probes
+- Service account and RBAC configuration
+- ConfigMap for character definitions
+- Persistent volume for memory database
+
+## Integration Architecture
+
+1. **OSSA Manifest** → Defines agent structure and requirements
+2. **OpenAPI Spec** → REST API contract with K8s metadata
+3. **FastAPI Bridge** → Wraps AIFlow Sia runtime in REST API
+4. **BuildKit Deployment** → Generates and applies K8s manifests
+5. **Runtime Orchestration** → Kubernetes manages agent lifecycle
+
+## Resources
+
+- **AIFlow Repository**: https://github.com/AIFlow-agent/AIFlow-Agent
+- **OSSA Project**: [openapi-ai-agents-standard](https://github.com/blueflyio/openstandardagents)
+- **Integration Guide**: [agent-buildkit Wiki](https://github.com/blueflyio/openstandardagents/wiki/AIFlow-Integration-with-OSSA-BuildKit-and-K-Agent)
+- **OSSA Specification Schema**: [OSSA 1.0 Schema](https://github.com/blueflyio/openstandardagents/blob/development/spec/v0.2.5-RC/ossa-0.2.5-RC.schema.json)
+- **Example Manifest**: [social-agent-aiflow.ossa.yaml](https://github.com/blueflyio/openstandardagents/blob/development/examples/aiflow-integration/social-agent-aiflow.ossa.yaml)
+- **OpenAPI Spec**: [aiflow-agent.openapi.yml](https://github.com/blueflyio/openstandardagents/blob/development/openapi/aiflow-agent.openapi.yml)
+

package/website/content/docs/integrations/drupal.md

@@ -0,0 +1,105 @@
+---
+title: "Drupal Integration"
+---
+
+# Drupal Integration
+
+Integrate OSSA agents with Drupal's LLM Platform.
+
+## Overview
+
+The OSSA Drupal modules provide:
+- Agent management UI
+- Workflow orchestration
+- CrewAI integration
+- Marketplace for agents
+
+## Available Modules
+
+| Module | Description |
+|--------|-------------|
+| ai_agents_ossa | Core OSSA integration |
+| ai_agents_orchestra | Workflow orchestration |
+| ai_agents_crewai | CrewAI framework bridge |
+| ai_agents_marketplace | Agent marketplace |
+| ai_agents_huggingface | HuggingFace models |
+
+## Installation
+
+### Via Composer
+
+```bash
+composer require drupal/ai_agents_ossa
+drush en ai_agents_ossa
+```
+
+### Configuration
+
+1. Go to `/admin/config/ai/agents`
+2. Configure LLM provider credentials
+3. Import OSSA manifests
+
+## Creating Agents in Drupal
+
+### Using the UI
+
+1. Navigate to `/admin/content/agents`
+2. Click "Add Agent"
+3. Upload OSSA manifest or configure inline
+
+### Using Drush
+
+```bash
+# Import agent from manifest
+drush ai:agent:import path/to/agent.ossa.yaml
+
+# List agents
+drush ai:agent:list
+
+# Run agent
+drush ai:agent:run my-agent "Hello"
+```
+
+## Workflow Orchestration
+
+The `ai_agents_orchestra` module enables multi-agent workflows:
+
+```yaml
+# workflow.ossa.yaml
+apiVersion: ossa/v0.2.x
+kind: AgentGraph
+
+metadata:
+  name: support-workflow
+
+spec:
+  agents:
+    - ref: triage-agent
+    - ref: resolver-agent
+  edges:
+    - from: triage-agent
+      to: resolver-agent
+  process: sequential
+```
+
+## ECA Integration
+
+OSSA agents work with Drupal's ECA (Event-Condition-Action):
+
+- Trigger agents on content events
+- Use agent responses in conditions
+- Chain multiple agents
+
+## API Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/agents` | GET | List agents |
+| `/api/agents/{id}/run` | POST | Run agent |
+| `/api/agents/{id}/status` | GET | Agent status |
+
+## Next Steps
+
+- [OSSA Manifest Reference](/docs/schema-reference)
+- [Orchestra Module Docs](https://github.com/blueflyio/drupal/ai_agents_orchestra)
+- [CrewAI Integration](/docs/migration-guides/crewai-to-ossa)

package/website/content/docs/migration-guides/00-INDEX.md

@@ -0,0 +1,76 @@
+---
+title: Migration Guides
+description: Migrate from existing AI frameworks to OSSA
+weight: 1
+---
+
+# Migration Guides
+
+Comprehensive guides for migrating from popular AI agent frameworks to OSSA (Open Standard for Scalable Agents).
+
+## Available Guides
+
+### 🤖 Framework Migrations
+
+- **[Anthropic MCP to OSSA](./anthropic-mcp-to-ossa.md)** - Extend MCP servers with OSSA for production features
+- **[CrewAI to OSSA](./crewai-to-ossa.md)** - Migrate CrewAI crews to OSSA orchestration
+- **[LangChain to OSSA](./langchain-to-ossa.md)** - Convert LangChain agents to OSSA agents
+- **[Langflow to OSSA](./langflow-to-ossa.md)** - Transform visual flows into OSSA manifests
+- **[OpenAI to OSSA](./openai-to-ossa.md)** - Migrate OpenAI Assistants API to OSSA
+
+### 🔧 Platform Migrations
+
+- **[Drupal ECA to OSSA](./drupal-eca-to-ossa.md)** - Convert Drupal automation rules to OSSA agents
+
+## Migration Overview
+
+All OSSA migrations share common patterns:
+
+### 1. Assessment Phase
+- Inventory existing agents/workflows
+- Map components to OSSA equivalents
+- Identify production requirements
+
+### 2. Design Phase
+- Create OSSA agent manifests
+- Define capability schemas
+- Plan workflow execution
+
+### 3. Implementation Phase
+- Implement agent logic
+- Add monitoring and policies
+- Configure deployment
+
+### 4. Testing Phase
+- Unit test capabilities
+- Integration test workflows
+- Validate performance
+
+### 5. Deployment Phase
+- Deploy to target environment
+- Configure monitoring
+- Run smoke tests
+
+## Why Migrate to OSSA?
+
+### Production Features
+- ✅ **Multi-Protocol Support** - HTTP, gRPC, WebSocket, MCP, A2A
+- ✅ **Enterprise Monitoring** - Traces, metrics, logs, health checks
+- ✅ **Kubernetes Native** - Deploy and scale on K8s
+- ✅ **OpenAPI Integration** - REST APIs for all agents
+- ✅ **Compliance Ready** - ISO42001, SOC2, GDPR support
+
+### Framework Advantages
+- 🔓 **No Vendor Lock-in** - Use any LLM provider
+- 🌐 **Multi-Runtime** - Local, Docker, K8s, serverless
+- 🔌 **Interoperable** - Works with existing frameworks
+- 📊 **Observable** - Built-in monitoring and tracing
+- 🔒 **Secure** - Enterprise security and policies
+
+## Getting Help
+
+- **Documentation**: [OSSA Wiki](https://github.com/blueflyio/openstandardagents/wiki/home)
+- **Issues**: [GitHub Issues](https://github.com/blueflyio/openstandardagents/issues)
+- **Discord**: [OSSA Community](https://github.com/blueflyio/openstandardagents/discussions)
+
+Ready to migrate? Choose your framework above and get started!

package/website/content/docs/migration-guides/README.md

@@ -0,0 +1,133 @@
+---
+title: "README"
+---
+
+# Migration Guides
+
+Comprehensive guides for migrating to or extending with OSSA (Open Standards for Scalable Agents).
+
+## Available Guides
+
+### 1. [Anthropic MCP to OSSA](./Anthropic-MCP-to-OSSA.md)
+**Extend Anthropic Model Context Protocol servers with OSSA**
+
+- **Target Audience:** MCP server developers, Claude Desktop users
+- **Complexity:** Intermediate
+- **Time to Complete:** 2-4 hours
+- **Key Benefits:**
+  - Keep MCP compatibility
+  - Add HTTP/REST API support
+  - Enable production monitoring
+  - Deploy to Kubernetes
+  - Multi-protocol access (MCP + OpenAPI + A2A)
+
+**Topics Covered:**
+- MCP servers → OSSA agents
+- MCP tools → OSSA capabilities
+- MCP resources → OSSA data sources
+- Dual-mode implementation (stdio + HTTP)
+- Integration patterns
+- 3 complete before/after examples
+
+---
+
+### 2. [LangChain to OSSA](./LangChain-to-OSSA.md)
+**Migrate Python LangChain agents to OSSA specification**
+
+- **Target Audience:** LangChain developers, Python AI engineers
+- **Complexity:** Intermediate to Advanced
+- **Time to Complete:** 4-8 hours
+- **Key Benefits:**
+  - Language-agnostic deployment
+  - Better orchestration
+  - Production-ready infrastructure
+  - Multi-framework support
+
+---
+
+## Quick Decision Guide
+
+**Choose the right guide based on your current stack:**
+
+```
+Have MCP servers? → Use "Anthropic MCP to OSSA"
+├─ Already working in Claude Desktop?
+│  └─ Keep MCP, add OSSA for production features
+│
+Have LangChain agents? → Use "LangChain to OSSA"
+├─ Python-based AI workflows?
+│  └─ Migrate to OSSA for better orchestration
+│
+Starting fresh? → Check Getting Started guide
+└─ Use OSSA from day one
+```
+
+## Common Scenarios
+
+### Scenario 1: "I have MCP servers for Claude Desktop"
+→ **Use:** [Anthropic MCP to OSSA](./Anthropic-MCP-to-OSSA.md)
+- Extend with HTTP API
+- Add monitoring/metrics
+- Deploy to production
+
+### Scenario 2: "I have LangChain Python agents"
+→ **Use:** [LangChain to OSSA](./LangChain-to-OSSA.md)
+- Migrate to TypeScript/Node.js
+- Add multi-protocol support
+- Enable agent orchestration
+
+### Scenario 3: "I want to expose my agent via multiple protocols"
+→ **Use:** [Anthropic MCP to OSSA](./Anthropic-MCP-to-OSSA.md)
+- MCP for Claude Desktop
+- OpenAPI for REST clients
+- A2A for agent-to-agent communication
+
+## Migration Roadmap
+
+```
+1. Assessment (1-2 hours)
+   ├─ Inventory existing agents/servers
+   ├─ Identify required features
+   └─ Choose migration guide
+
+2. Planning (2-4 hours)
+   ├─ Map existing functionality to OSSA
+   ├─ Design agent manifest
+   └─ Plan deployment strategy
+
+3. Implementation (4-8 hours)
+   ├─ Create OSSA agent structure
+   ├─ Migrate business logic
+   ├─ Configure bridges (MCP, OpenAPI, etc.)
+   └─ Add monitoring
+
+4. Testing (2-4 hours)
+   ├─ Test all protocols
+   ├─ Verify backward compatibility
+   └─ Load testing
+
+5. Deployment (2-4 hours)
+   ├─ Deploy to target environment
+   ├─ Configure monitoring
+   └─ Update client configurations
+```
+
+## Support
+
+- **Documentation:** `/Users/flux423/Sites/LLM/agent-buildkit/docs/`
+- **Examples:** `/Users/flux423/Sites/LLM/agent-buildkit/.agents/`
+- **OSSA Spec:** [OSSA Complete Reference](../OSSA-COMPLETE-AGENT-REFERENCE.md)
+- **BuildKit CLI:** `buildkit agents --help`
+
+## Contributing
+
+Found an issue or want to add a migration guide?
+
+1. Create an issue: [GitLab Issues](https://github.com/blueflyio/documentation/-/issues)
+2. Submit a merge request with your guide
+3. Follow the existing structure and format
+
+---
+
+**Last Updated:** 2025-11-10
+**Maintained By:** Agent BuildKit Team

package/website/content/docs/migration-guides/agent-schema-comparison.md

@@ -0,0 +1,232 @@
+# Agent Schema Comparison: GitLab Duo Agent vs General Agent
+
+## Overview
+
+This document compares the GitLab Duo Agent API schema with a generalized agent schema to highlight the differences, similarities, and architectural approaches.
+
+## 1. Core Agent Entity Comparison
+
+### GitLab Duo Agent (CLIAgent)
+```yaml
+CLIAgent:
+  type: object
+  properties:
+    id: string (uuid)
+    project_id: integer
+    service_account_id: string
+    service_account_username: string
+    flow_id: string (uuid)
+    status: [active, inactive, error]
+    last_invocation: string (date-time, nullable)
+    total_invocations: integer (default: 0)
+    created_at: string (date-time)
+```
+
+### General Agent
+```yaml
+Agent:
+  type: object
+  properties:
+    id: string (uuid)
+    name: string
+    description: string
+    agent_type: [cli, web, chat, workflow, autonomous]
+    status: [active, inactive, paused, error, training]
+    capabilities: array of strings
+    configuration: object (model, provider, temperature, max_tokens)
+    permissions: array of strings
+    created_at: string (date-time)
+    updated_at: string (date-time)
+    last_activity: string (date-time)
+    metadata: object
+```
+
+## 2. Key Differences
+
+### A. Scope and Purpose
+- **GitLab Duo Agent**: Highly specialized for GitLab integration, focused on CLI agents that work within GitLab projects
+- **General Agent**: Universal design for various agent types (CLI, web, chat, workflow, autonomous)
+
+### B. Integration Context
+- **GitLab Duo Agent**: 
+  - Tightly coupled with GitLab projects (`project_id`)
+  - Uses GitLab service accounts for authentication
+  - Linked to specific AI flows (`flow_id`)
+  - Designed for GitLab-specific triggers (issue comments, MR comments, epic comments)
+
+- **General Agent**:
+  - Platform-agnostic design
+  - Generic permission system
+  - Self-contained configuration
+  - Supports various trigger types (manual, scheduled, event-based, API calls, webhooks)
+
+### C. Status Management
+- **GitLab Duo Agent**: Simple 3-state system (`active`, `inactive`, `error`)
+- **General Agent**: More comprehensive 5-state system (`active`, `inactive`, `paused`, `error`, `training`)
+
+### D. Capabilities Model
+- **GitLab Duo Agent**: Implicit capabilities through flow types (code_generation, code_review, etc.)
+- **General Agent**: Explicit capabilities array with predefined skill types
+
+## 3. Execution Model Comparison
+
+### GitLab Duo Agent Execution
+```yaml
+InvokeCLIAgentRequest:
+  required:
+    - task_description
+    - trigger_context
+  properties:
+    task_description: string
+    trigger_context:
+      trigger_type: [issue_comment, merge_request_comment, epic_comment]
+      issue_iid: integer
+      merge_request_iid: integer
+      epic_id: integer
+      comment_id: integer
+      mentioned_by_user: string
+
+AgentInvocationResult:
+  properties:
+    invocation_id: string (uuid)
+    status: [accepted, running, completed, failed]
+    pipeline_id: integer (nullable)
+    response_comment_id: integer (nullable)
+    error_message: string (nullable)
+```
+
+### General Agent Execution
+```yaml
+AgentExecution:
+  properties:
+    execution_id: string (uuid)
+    agent_id: string (uuid)
+    task:
+      description: string
+      input_data: object
+      context: object
+    status: [pending, running, completed, failed, cancelled]
+    result:
+      output: string
+      artifacts: array
+      metrics: object
+    logs: array of log objects
+    started_at: string (date-time)
+    completed_at: string (date-time)
+    duration_ms: integer
+```
+
+### Key Execution Differences
+- **GitLab Duo**: Focused on GitLab-specific responses (pipeline creation, comment responses)
+- **General Agent**: Generic execution with comprehensive logging and metrics
+- **GitLab Duo**: Simpler status tracking
+- **General Agent**: More detailed execution tracking with duration and metrics
+
+## 4. Flow vs Agent Architecture
+
+### GitLab Duo: Flow-Centric Architecture
+```yaml
+AIFlow:
+  properties:
+    id: string (uuid)
+    project_id: integer
+    name: string
+    description: string
+    config_path: string
+    flow_type: [code_generation, code_review, issue_analysis, merge_request_analysis, documentation_generation, testing_assistance, custom]
+    ai_provider: [anthropic_claude, openai_codex, gitlab_managed]
+    configuration: object (model, temperature, max_tokens, use_gitlab_managed_credentials)
+    environment_variables: array
+    status: [active, inactive, error]
+    created_at: string (date-time)
+    updated_at: string (date-time)
+```
+
+### General Agent: Agent-Centric Architecture
+```yaml
+Agent:
+  # Direct agent capabilities and configuration
+  # No separate flow concept - agents contain their own capabilities
+```
+
+### Architectural Difference
+- **GitLab Duo**: Separates AI capabilities (flows) from execution agents (CLI agents)
+- **General Agent**: Combines capabilities and execution in a single agent entity
+
+## 5. Trigger System Comparison
+
+### GitLab Duo Triggers
+```yaml
+FlowTrigger:
+  properties:
+    id: string (uuid)
+    project_id: integer
+    name: string
+    service_account_id: string
+    config_path: string
+    event_types: [issue_comment_created, merge_request_comment_created, epic_comment_created]
+    status: [active, inactive]
+    created_at: string (date-time)
+```
+
+### General Agent Triggers
+```yaml
+AgentTrigger:
+  properties:
+    id: string (uuid)
+    agent_id: string (uuid)
+    name: string
+    trigger_type: [manual, scheduled, event_based, api_call, webhook]
+    event_config:
+      events: array
+      conditions: object
+    schedule:
+      cron_expression: string
+      timezone: string
+    status: [active, inactive]
+    created_at: string (date-time)
+    last_triggered: string (date-time, nullable)
+```
+
+### Trigger Differences
+- **GitLab Duo**: Limited to GitLab-specific events, project-scoped
+- **General Agent**: Universal trigger types with scheduling support
+- **GitLab Duo**: Simple event configuration
+- **General Agent**: Complex event conditions and scheduling
+
+## 6. Advanced Features
+
+### General Agent Exclusive Features
+1. **Agent Skills**: Modular capability system with input/output schemas
+2. **Agent Memory**: Memory management with different memory types and embeddings
+3. **Comprehensive Logging**: Structured logging with multiple levels
+4. **Metrics and Performance**: Execution duration and performance tracking
+5. **Metadata System**: Flexible metadata for extensibility
+
+### GitLab Duo Exclusive Features
+1. **GitLab Integration**: Deep integration with GitLab projects and service accounts
+2. **AI Gateway**: Managed AI provider credentials through GitLab
+3. **Environment Variables**: Project-specific environment variable management
+4. **Pipeline Integration**: Direct CI/CD pipeline creation and management
+
+## 7. Summary
+
+### GitLab Duo Agent Schema Strengths
+- **Specialized**: Optimized for GitLab ecosystem integration
+- **Practical**: Focused on real-world GitLab automation scenarios
+- **Integrated**: Seamless connection with GitLab authentication and authorization
+- **Production-Ready**: Designed for actual deployment in GitLab environments
+
+### General Agent Schema Strengths
+- **Universal**: Platform-agnostic design suitable for various environments
+- **Extensible**: Modular architecture with skills and memory systems
+- **Comprehensive**: Rich feature set for advanced agent capabilities
+- **Flexible**: Supports multiple agent types and execution patterns
+
+### Architectural Philosophies
+- **GitLab Duo**: "Integration-first" - designed to work seamlessly within GitLab
+- **General Agent**: "Capability-first" - designed to maximize agent functionality
+
+### Use Case Recommendations
+- **Use GitLab Duo Agent** when: Building GitLab-specific automation and AI assistants
+- **Use General Agent** when: Building universal agents that work across platforms or need advanced capabilities like memory, skills, and complex scheduling