@bluefly/openstandardagents 0.3.3 → 0.3.5

package/examples/a2a/agent-handoff.ossa.yaml

@@ -0,0 +1,202 @@
+apiVersion: ossa/v0.3.5
+kind: Agent
+metadata:
+  name: support-agent
+  version: 1.0.0
+  description: "Customer support agent with escalation and handoff capabilities"
+  labels:
+    framework: a2a
+    capability: support
+    tier: tier-1
+
+spec:
+  model:
+    provider: anthropic
+    model: claude-sonnet-4-20250514
+    parameters:
+      temperature: 0.8
+      maxTokens: 4096
+
+  instructions: |
+    You are a Tier 1 customer support agent. Handle customer inquiries and
+    escalate complex issues to specialized agents.
+
+    Escalation Rules:
+    - Technical issues → @technical-support
+    - Billing questions → @billing-support
+    - Complex product issues → @product-specialist
+    - Critical issues → @senior-support
+
+    When escalating:
+    1. Summarize the customer's issue
+    2. Include relevant context and conversation history
+    3. Set appropriate priority
+    4. Use handoff to preserve context
+
+  tools:
+    - type: function
+      name: escalate_to_agent
+      description: "Escalate issue to another agent"
+      input_schema:
+        type: object
+        required: [agentId, reason, summary]
+        properties:
+          agentId:
+            type: string
+            description: "Target agent ID"
+          reason:
+            type: string
+            description: "Escalation reason"
+          summary:
+            type: string
+            description: "Issue summary"
+          priority:
+            type: string
+            enum: [low, medium, high, critical]
+            default: medium
+
+    - type: function
+      name: handoff_conversation
+      description: "Hand off entire conversation to another agent"
+      input_schema:
+        type: object
+        required: [agentId]
+        properties:
+          agentId:
+            type: string
+            description: "Target agent ID"
+          note:
+            type: string
+            description: "Handoff note for receiving agent"
+
+  extensions:
+    a2a:
+      enabled: true
+
+      protocol:
+        type: json-rpc
+        version: "2.0"
+        messageFormat: json
+        timeout: 60
+
+      endpoints:
+        - agentId: "@technical-support"
+          url: "http://technical-support:8080/a2a"
+          capabilities: ["technical-support", "troubleshooting", "debugging"]
+          priority: 10
+
+        - agentId: "@billing-support"
+          url: "http://billing-support:8080/a2a"
+          capabilities: ["billing", "payments", "subscriptions"]
+          priority: 8
+
+        - agentId: "@product-specialist"
+          url: "http://product-specialist:8080/a2a"
+          capabilities: ["product-expertise", "features", "roadmap"]
+          priority: 7
+
+        - agentId: "@senior-support"
+          url: "http://senior-support:8080/a2a"
+          capabilities: ["escalation-handler", "complex-issues", "vip-support"]
+          priority: 15
+
+      routing:
+        strategy: direct
+        routingRules:
+          - name: "technical-escalation"
+            condition: "message.category == 'technical' && message.complexity > 3"
+            target: "@technical-support"
+            priority: 10
+
+          - name: "billing-escalation"
+            condition: "message.category == 'billing'"
+            target: "@billing-support"
+            priority: 8
+
+          - name: "critical-escalation"
+            condition: "message.priority == 'critical'"
+            target: "@senior-support"
+            priority: 15
+
+      delegation:
+        enabled: true
+        maxDepth: 2
+        timeout: 600
+        handoff:
+          enabled: true
+          preserveContext: true
+          handoffRules:
+            - name: "complexity-handoff"
+              condition: "confidence < 0.5"
+              target: "@senior-support"
+              message: "Issue complexity exceeds Tier 1 capability"
+
+            - name: "technical-handoff"
+              condition: "category == 'technical' && attempts > 2"
+              target: "@technical-support"
+              message: "Technical issue requires specialist"
+
+            - name: "vip-handoff"
+              condition: "customer.tier == 'vip'"
+              target: "@senior-support"
+              message: "VIP customer requiring priority handling"
+
+      completionSignals:
+        enabled: true
+        signals: ["continue", "complete", "blocked", "escalate"]
+        handlers:
+          - signal: escalate
+            action: handoff
+            target: "@senior-support"
+            config:
+              preserveContext: true
+              notifyCustomer: true
+              notificationMessage: "Your inquiry has been escalated to a senior specialist."
+
+          - signal: blocked
+            action: handoff
+            target: "@technical-support"
+            config:
+              preserveContext: true
+              reason: "Unable to resolve issue at current tier"
+
+          - signal: complete
+            action: notify
+            config:
+              channels: ["customer", "metrics"]
+              logResolution: true
+
+      authentication:
+        type: jwt
+        jwt:
+          secret: "${A2A_JWT_SECRET}"
+          algorithm: HS256
+          expiresIn: 3600
+
+      retryPolicy:
+        enabled: true
+        maxRetries: 2
+        backoff: exponential
+        initialDelay: 2
+        maxDelay: 30
+        retryableErrors:
+          - "UNAVAILABLE"
+          - "TIMEOUT"
+
+      circuitBreaker:
+        enabled: true
+        failureThreshold: 3
+        successThreshold: 2
+        timeout: 120
+
+      observability:
+        tracing:
+          enabled: true
+          provider: opentelemetry
+          samplingRate: 1.0
+        metrics:
+          enabled: true
+          endpoint: "/metrics"
+        logging:
+          level: info
+          format: json

package/examples/a2a/service-discovery.ossa.yaml

@@ -0,0 +1,194 @@
+apiVersion: ossa/v0.3.5
+kind: Agent
+metadata:
+  name: distributed-coordinator
+  version: 1.0.0
+  description: "Distributed agent coordinator with service discovery"
+  labels:
+    framework: a2a
+    capability: orchestration
+    environment: production
+
+spec:
+  model:
+    provider: anthropic
+    model: claude-sonnet-4-20250514
+    parameters:
+      temperature: 0.7
+      maxTokens: 8192
+
+  instructions: |
+    You are a distributed agent coordinator that orchestrates tasks across
+    multiple specialized agents using A2A communication.
+
+    Responsibilities:
+    - Discover available agents via service registry
+    - Route tasks to appropriate agents based on capabilities
+    - Monitor task progress and handle completion signals
+    - Manage agent handoffs and escalations
+
+    Use service discovery to find agents dynamically and route tasks efficiently.
+
+  tools:
+    - type: function
+      name: discover_agents
+      description: "Discover available agents with specific capabilities"
+      input_schema:
+        type: object
+        properties:
+          capabilities:
+            type: array
+            items:
+              type: string
+            description: "Required agent capabilities"
+
+    - type: function
+      name: delegate_task
+      description: "Delegate task to another agent"
+      input_schema:
+        type: object
+        required: [agentId, task]
+        properties:
+          agentId:
+            type: string
+            description: "Target agent ID"
+          task:
+            type: object
+            description: "Task details"
+
+  extensions:
+    a2a:
+      enabled: true
+
+      protocol:
+        type: json-rpc
+        version: "2.0"
+        messageFormat: json
+        compression: true
+        timeout: 30
+
+      discovery:
+        enabled: true
+        mechanism: registry
+        registryUrl: "https://registry.example.com/agents"
+        refreshInterval: 60
+        healthCheck:
+          enabled: true
+          interval: 30
+          timeout: 5
+          endpoint: "/health"
+
+      endpoints:
+        - agentId: "@security-scanner"
+          url: "http://security-scanner:8080/a2a"
+          capabilities: ["security-scan", "vulnerability-check", "sast", "dast"]
+          priority: 10
+          weight: 100
+
+        - agentId: "@performance-analyzer"
+          url: "http://performance-analyzer:8080/a2a"
+          capabilities: ["performance-analysis", "profiling", "load-testing"]
+          priority: 5
+          weight: 80
+
+        - agentId: "@documentation-agent"
+          url: "http://documentation-agent:8080/a2a"
+          capabilities: ["documentation", "api-docs", "readme-generation"]
+          priority: 3
+          weight: 60
+
+      routing:
+        strategy: capability-based
+        defaultAgent: "@fallback-agent"
+        routingRules:
+          - name: "security-routing"
+            condition: "message.type == 'security-scan'"
+            target: "@security-scanner"
+            priority: 10
+
+          - name: "performance-routing"
+            condition: "message.type == 'performance-analysis'"
+            target: "@performance-analyzer"
+            priority: 5
+
+          - name: "documentation-routing"
+            condition: "message.type == 'documentation'"
+            target: "@documentation-agent"
+            priority: 3
+
+      delegation:
+        enabled: true
+        maxDepth: 3
+        timeout: 300
+        handoff:
+          enabled: true
+          preserveContext: true
+          handoffRules:
+            - name: "security-escalation"
+              condition: "signal == 'escalate' && capability == 'security'"
+              target: "@senior-security-expert"
+              message: "Escalating security issue to senior expert"
+
+      completionSignals:
+        enabled: true
+        signals: ["continue", "complete", "blocked", "escalate", "checkpoint"]
+        handlers:
+          - signal: escalate
+            action: handoff
+            target: "@senior-coordinator"
+            config:
+              notifyUser: true
+
+          - signal: blocked
+            action: notify
+            config:
+              channels: ["slack", "email"]
+
+          - signal: checkpoint
+            action: checkpoint
+            config:
+              storage: agent-brain
+              compression: true
+
+      checkpointSync:
+        enabled: true
+        storage: agent-brain
+        syncInterval: 60
+        compression: true
+
+      authentication:
+        type: mtls
+        mtls:
+          certPath: "/certs/agent-coordinator.crt"
+          keyPath: "/certs/agent-coordinator.key"
+          caPath: "/certs/ca.crt"
+          verifyPeer: true
+
+      retryPolicy:
+        enabled: true
+        maxRetries: 3
+        backoff: exponential
+        initialDelay: 1
+        maxDelay: 60
+        retryableErrors:
+          - "UNAVAILABLE"
+          - "TIMEOUT"
+          - "CONNECTION_ERROR"
+
+      circuitBreaker:
+        enabled: true
+        failureThreshold: 5
+        successThreshold: 2
+        timeout: 60
+
+      observability:
+        tracing:
+          enabled: true
+          provider: opentelemetry
+          samplingRate: 0.1
+        metrics:
+          enabled: true
+          endpoint: "/metrics"
+        logging:
+          level: info
+          format: json

package/examples/adapters/anthropic-quickstart.ts

@@ -0,0 +1,66 @@
+/**
+ * Anthropic Quick Start - Use OSSA with Anthropic SDK
+ *
+ * This example shows how to load an OSSA manifest and execute it
+ * directly with the Anthropic Claude API using the runtime adapter.
+ */
+
+import { AnthropicAdapter } from '@bluefly/openstandardagents';
+import { parse } from 'yaml';
+import { readFileSync } from 'fs';
+
+async function main() {
+  // Load OSSA manifest from file
+  const manifestPath = './examples/getting-started/02-agent-with-tools.ossa.yaml';
+  const manifestYaml = readFileSync(manifestPath, 'utf-8');
+  const ossaManifest = parse(manifestYaml);
+
+  // Create Anthropic adapter with configuration
+  const adapter = new AnthropicAdapter(ossaManifest, {
+    apiKey: process.env.ANTHROPIC_API_KEY || '',
+    model: 'claude-3-5-sonnet-20241022',
+    temperature: 0.7,
+    maxTokens: 4096,
+  });
+
+  // Get agent information
+  const agentInfo = adapter.getAgentInfo();
+  console.log('Agent Info:');
+  console.log(JSON.stringify(agentInfo, null, 2));
+
+  // Chat with the agent using simple text interface
+  const userMessage = 'Hello! Can you help me understand what you can do?';
+  console.log(`\nUser: ${userMessage}`);
+
+  const response = await adapter.chat(userMessage, {
+    verbose: true,
+    maxTurns: 5,
+  });
+
+  console.log(`\nAssistant: ${response}`);
+
+  // Get usage statistics
+  const history = adapter.getConversationHistory();
+  console.log(`\nConversation turns: ${history.length}`);
+}
+
+main().catch(console.error);
+
+/**
+ * Usage:
+ *
+ * 1. Install dependencies:
+ *    npm install @bluefly/openstandardagents yaml
+ *
+ * 2. Set your API key:
+ *    export ANTHROPIC_API_KEY='your-api-key-here'
+ *
+ * 3. Run this example:
+ *    npx tsx examples/adapters/anthropic-quickstart.ts
+ *
+ * Features:
+ * - Automatic tool mapping from OSSA manifest
+ * - Multi-turn conversation support
+ * - Token usage tracking
+ * - Simple chat interface
+ */

package/examples/adapters/crewai-quickstart.py

@@ -0,0 +1,86 @@
+#!/usr/bin/env python3
+"""
+CrewAI Quick Start - Convert OSSA to CrewAI
+
+This example shows how to load an OSSA manifest and convert it
+to CrewAI agent format for use in CrewAI applications.
+"""
+
+import yaml
+import json
+from pathlib import Path
+
+def parse_role_text(role_text: str, description: str = "") -> dict:
+    """Parse OSSA role text into CrewAI components"""
+    lines = [l.strip() for l in role_text.split('\n') if l.strip()]
+
+    role = lines[0] if lines else "AI Assistant"
+    goal = description or "Assist users with their queries"
+    backstory = "An AI agent designed to help users effectively"
+
+    # Look for specific patterns
+    for line in lines:
+        if line.lower().startswith('goal:'):
+            goal = line.split(':', 1)[1].strip()
+        elif line.lower().startswith('backstory:'):
+            backstory = line.split(':', 1)[1].strip()
+        elif line.lower().startswith('role:'):
+            role = line.split(':', 1)[1].strip()
+
+    return {"role": role, "goal": goal, "backstory": backstory}
+
+def ossa_to_crewai(manifest: dict) -> dict:
+    """Convert OSSA manifest to CrewAI agent format"""
+    spec = manifest.get('spec', {})
+    metadata = manifest.get('metadata', {})
+    tools = spec.get('tools', [])
+
+    # Parse role components
+    role_text = spec.get('role', '')
+    role_info = parse_role_text(role_text, metadata.get('description', ''))
+
+    # Convert tools
+    tool_names = [tool.get('name', 'unknown_tool') for tool in tools]
+
+    return {
+        "role": role_info['role'],
+        "goal": role_info['goal'],
+        "backstory": role_info['backstory'],
+        "tools": tool_names,
+        "verbose": True,
+        "allow_delegation": False,
+        "llm_model": spec.get('llm', {}).get('model', 'gpt-4')
+    }
+
+# Load OSSA manifest
+manifest_path = Path('./examples/getting-started/02-agent-with-tools.ossa.yaml')
+with open(manifest_path, 'r') as f:
+    ossa_manifest = yaml.safe_load(f)
+
+# Convert to CrewAI format
+crewai_agent = ossa_to_crewai(ossa_manifest)
+
+print('CrewAI Agent Configuration:')
+print(json.dumps(crewai_agent, indent=2))
+
+"""
+Usage:
+
+1. Install dependencies:
+   pip install pyyaml crewai
+
+2. Run this example:
+   python examples/adapters/crewai-quickstart.py
+
+3. Use the configuration in your CrewAI application:
+
+   from crewai import Agent
+
+   agent = Agent(
+       role=crewai_agent['role'],
+       goal=crewai_agent['goal'],
+       backstory=crewai_agent['backstory'],
+       tools=crewai_agent['tools'],
+       verbose=True
+   )
+"""

package/examples/adapters/drupal-eca-mapping.yaml

@@ -1,6 +1,6 @@
 # Example: ECA (Event-Condition-Action) to OSSA Task Mapping
 # Demonstrates how Drupal ECA rules map to OSSA Task/Workflow manifests
-apiVersion: ossa/v0.3.3
+apiVersion: ossa/v0.3.5
 kind: Task
 metadata:
   name: eca-content-published-notify

package/examples/adapters/drupal-eca-task.yaml

@@ -1,4 +1,4 @@
-apiVersion: ossa/v0.3.3
+apiVersion: ossa/v0.3.5
 kind: Task
 metadata:
   name: drupal-content-moderation

package/examples/adapters/drupal-flowdrop-mapping.yaml

@@ -1,6 +1,6 @@
 # Example: FlowDrop Visual Workflow to OSSA Workflow Mapping
 # Demonstrates how Drupal FlowDrop diagrams map to OSSA Workflows
-apiVersion: ossa/v0.3.3
+apiVersion: ossa/v0.3.5
 kind: Workflow
 metadata:
   name: flowdrop-user-registration

package/examples/adapters/drupal-maestro-mapping.yaml

@@ -1,6 +1,6 @@
 # Example: Maestro Business Process to OSSA Workflow Mapping
 # Demonstrates how Drupal Maestro templates map to OSSA Workflows
-apiVersion: ossa/v0.3.3
+apiVersion: ossa/v0.3.5
 kind: Workflow
 metadata:
   name: maestro-content-approval

package/examples/adapters/langchain-quickstart.ts

@@ -0,0 +1,40 @@
+/**
+ * LangChain Quick Start - Convert OSSA to LangChain
+ *
+ * This example shows how to load an OSSA manifest and convert it
+ * to LangChain agent format for use in LangChain applications.
+ */
+
+import { LangChainAdapter } from '@bluefly/openstandardagents';
+import { parse } from 'yaml';
+import { readFileSync } from 'fs';
+
+// Load OSSA manifest from file
+const manifestPath = './examples/getting-started/02-agent-with-tools.ossa.yaml';
+const manifestYaml = readFileSync(manifestPath, 'utf-8');
+const ossaManifest = parse(manifestYaml);
+
+// Convert OSSA manifest to LangChain format
+const langchainAgent = LangChainAdapter.toLangChain(ossaManifest);
+
+console.log('LangChain Agent Configuration:');
+console.log(JSON.stringify(langchainAgent, null, 2));
+
+// Generate Python code for LangChain
+const pythonCode = LangChainAdapter.toPythonCode(ossaManifest);
+
+console.log('\nGenerated LangChain Python Code:');
+console.log(pythonCode);
+
+/**
+ * Usage:
+ *
+ * 1. Install dependencies:
+ *    npm install @bluefly/openstandardagents yaml
+ *
+ * 2. Run this example:
+ *    npx tsx examples/adapters/langchain-quickstart.ts
+ *
+ * 3. Save generated Python code to a file and run with LangChain:
+ *    python langchain_agent.py
+ */

package/examples/adapters/mistral-agent.yaml

@@ -1,4 +1,4 @@
-apiVersion: ossa/v0.3.3
+apiVersion: ossa/v0.3.5
 kind: Agent
 metadata:
   name: mistral-code-assistant

package/examples/adapters/symfony-messenger-task.yaml

@@ -1,6 +1,6 @@
 # Example: OSSA Task executed via Symfony Messenger
 # Demonstrates async task execution with queue-based processing
-apiVersion: ossa/v0.3.3
+apiVersion: ossa/v0.3.5
 kind: Task
 metadata:
   name: send-email-symfony

package/examples/adapters/symfony-messenger-workflow.yaml

@@ -1,6 +1,6 @@
 # Example: OSSA Workflow executed via Symfony Messenger
 # Demonstrates multi-step workflow with async Task orchestration
-apiVersion: ossa/v0.3.3
+apiVersion: ossa/v0.3.5
 kind: Workflow
 metadata:
   name: user-onboarding-symfony

package/examples/adk-integration/code-review-workflow.yml

@@ -1,7 +1,7 @@
 # Example: ADK Code Review Workflow with OSSA Agents
 # This demonstrates how OSSA agents work with ADK orchestration patterns
 
-apiVersion: ossa/v0.3.3
+apiVersion: ossa/v0.3.5
 kind: Workflow
 metadata:
   name: code-review-workflow

package/examples/adk-integration/customer-support.yml

@@ -1,7 +1,7 @@
 # Example: ADK Customer Support System with OSSA Agents
 # Demonstrates Coordinator and Dispatcher patterns
 
-apiVersion: ossa/v0.3.3
+apiVersion: ossa/v0.3.5
 kind: Workflow
 metadata:
   name: customer-support-system

package/examples/adk-integration/data-pipeline.yml

@@ -1,7 +1,7 @@
 # Example: ADK Data Processing Pipeline with OSSA Agents
 # Demonstrates LoopAgent and ConditionalAgent patterns
 
-apiVersion: ossa/v0.3.3
+apiVersion: ossa/v0.3.5
 kind: Workflow
 metadata:
   name: data-processing-pipeline

package/examples/advanced/reasoning-agent.yaml

@@ -1,6 +1,6 @@
 # OSSA v0.2.9 - Reasoning Agent Example
 # Demonstrates: reasoning strategies, prompt templates, knowledge graph
-apiVersion: ossa/v0.3.3
+apiVersion: ossa/v0.3.5
 kind: Agent
 metadata:
   name: research-analyst