@bluefly/openstandardagents 0.1.9 → 0.2.5-RC

package/examples/kagent/security-scanner.ossa.yaml

@@ -0,0 +1,140 @@
+# ============================================================================
+# OSSA kAgent Reference Implementation #2
+# Security Scanner Agent - Comprehensive Annotation
+# Domain: security.vulnerability.scanning
+# Purpose: Continuous vulnerability scanning, CVE detection, compliance validation
+# Last Updated: 2025-11-10
+# ============================================================================
+
+apiVersion: ossa/v1
+kind: Agent
+metadata:
+  # Core identity metadata for the security scanning agent
+  name: security-scanner
+  version: 1.0.0
+  description: "Continuous security vulnerability scanning and compliance validation agent"
+
+spec:
+  # Taxonomy defines the agent's operational domain and classification
+  # Used for service discovery, capability matching, and policy routing
+  taxonomy:
+    domain: security          # Primary domain for security operations
+    subdomain: vulnerability  # Specialization: vulnerability management
+    capability: scanning      # Core capability: security scanning
+
+  # Role definition: Defines agent's purpose, boundaries, and security responsibilities
+  # This instructs the LLM on its operational context within the security ecosystem
+  role: |
+    You are a security scanning agent that continuously monitors Kubernetes clusters
+    for vulnerabilities, misconfigurations, and compliance violations. You integrate
+    with CVE databases, security benchmarks (CIS, NIST), and provide actionable remediation.
+
+  # LLM Configuration: Controls AI model behavior for security scanning operations
+  # Low temperature (0.1) ensures deterministic, consistent security analysis
+  llm:
+    provider: anthropic
+    model: claude-3-sonnet-20240229
+    temperature: 0.1           # Low temperature for consistent vulnerability assessment
+    maxTokens: 8000            # Token limit for detailed security reports
+
+  # Tools: Defines integrations with security scanning and compliance validation systems
+  # Each tool maps to specific security capabilities: image scanning, RBAC validation, config auditing
+  tools:
+    # Kubernetes-based security operations via MCP server
+    # Provides cluster-level visibility into security posture
+    - type: mcp
+      server: kubernetes-mcp
+      capabilities:
+        - scan_images          # CVE scanning for container images (registry vulnerability detection)
+        - check_rbac           # Role-based access control validation (IAM security)
+        - audit_configs        # Configuration audit against security benchmarks (CIS, NIST)
+
+    # Compliance validation and security policy enforcement via buildkit engine
+    # Enables continuous compliance checking against organizational policies
+    - type: mcp
+      server: buildkit-compliance-engine
+      capabilities:
+        - validate_compliance  # Verify compliance against frameworks (SOC2, FedRAMP, etc.)
+        - check_policies       # Enforce organization-specific security policies
+        - generate_reports     # Create compliance and vulnerability reports
+
+    # Trivy vulnerability scanner: External HTTP service for container/image scanning
+    # Integrates with CVE databases for real-time vulnerability detection
+    - type: http
+      name: trivy-scanner
+      endpoint: http://trivy:8080
+      auth:
+        type: bearer           # Bearer token authentication for API access
+
+  # Autonomy Level: Determines agent decision-making authority and approval workflows
+  # Security agents typically operate autonomously for scanning but require approval for remediation
+  autonomy:
+    level: autonomous          # Can execute scan operations without human intervention
+    approval_required: false   # Scans execute automatically per schedule
+    allowed_actions:
+      - scan_all_namespaces    # Permission: scan all Kubernetes namespaces for vulnerabilities
+      - generate_reports       # Permission: create vulnerability and compliance reports
+      - send_alerts            # Permission: notify security teams of findings
+    blocked_actions:
+      - remediate_automatically  # BLOCKED: Prevent autonomous remediation (human oversight required)
+      - modify_resources         # BLOCKED: Prevent direct cluster modifications
+
+  # Constraints: Operational boundaries for cost, performance, and scanning frequency
+  # Prevents resource exhaustion and maintains predictable operational costs
+  constraints:
+    cost:
+      maxTokensPerDay: 100000   # Daily LLM token budget for security analysis
+      maxCostPerDay: 25.0       # Daily cost cap in USD for AI operations
+    performance:
+      maxLatencySeconds: 60     # Maximum acceptable latency for vulnerability scan results
+      scanInterval: 3600        # Scan frequency: 1 hour (3600 seconds) between full scans
+
+  # Extensions: Kubernetes-specific configurations for agent deployment and runtime governance
+  # Contains kAgent-specific settings for the Kubernetes environment
+  extensions:
+    kagent:
+      # Kubernetes deployment configuration: Where and how agent runs in cluster
+      kubernetes:
+        namespace: security     # Dedicated security namespace for agent isolation
+        labels:
+          app: security-scanner        # Application identifier
+          team: security               # Team ownership
+          environment: production      # Environment classification
+          compliance: soc2-fedramp     # Compliance frameworks: SOC2, FedRAMP
+
+        # Resource limits: Prevents runaway resource consumption during intensive scans
+        resourceLimits:
+          cpu: "1000m"                 # 1 CPU core limit
+          memory: "1Gi"                # 1GB memory limit for scan operations
+
+      # Guardrails: Security controls and oversight mechanisms for agent operations
+      # Ensures compliance, auditability, and cost control
+      guardrails:
+        requireApproval: false         # Scans don't require approval (scheduled automation)
+        costLimits:
+          maxTokensPerDay: 100000      # Daily token budget enforcement
+        auditLog:
+          destination: compliance-engine  # Send all operations to compliance system
+          retention: 10years              # 10-year retention for regulatory compliance
+
+      # Agent-to-Agent (A2A) Configuration: Inter-agent communication and coordination
+      # Enables security agent to collaborate with other agents (troubleshooter, validator)
+      a2aConfig:
+        enabled: true                  # Enable inter-agent communication
+        protocol: json-rpc             # Communication protocol: JSON-RPC over HTTP
+        endpoints:
+          - http://k8s-troubleshooter:8080/a2a      # Endpoint: Kubernetes troubleshooting agent
+          - http://compliance-validator:8080/a2a    # Endpoint: Compliance validation agent
+
+# ============================================================================
+# SECURITY FEATURES SUMMARY:
+# - CVE Detection: Trivy integration for container image vulnerability scanning
+# - Compliance Checking: Validates against SOC2, FedRAMP, CIS, NIST standards
+# - RBAC Validation: Ensures Kubernetes access controls are properly configured
+# - Config Auditing: Scans cluster configurations against security baselines
+# - Vulnerability Reporting: Generates detailed security and compliance reports
+# - Alert Management: Autonomous notification of security findings
+# - Audit Trail: 10-year retention of all operations via compliance engine
+# - Cost Controls: Daily token and monetary budgets prevent resource exhaustion
+# - Approval Workflows: Blocks autonomous remediation; requires human oversight
+# ============================================================================

package/examples/langchain/chain-agent.ossa.json

@@ -0,0 +1,42 @@
+{
+  "apiVersion": "ossa/v0.2",
+  "kind": "Agent",
+  "metadata": {
+    "name": "langchain-agent",
+    "version": "1.0.0",
+    "description": "LangChain agent with tool chain"
+  },
+  "spec": {
+    "role": "You are a LangChain agent that uses tools to accomplish tasks.",
+    "llm": {
+      "provider": "openai",
+      "model": "gpt-4",
+      "temperature": 0.5
+    },
+    "tools": [
+      {
+        "type": "function",
+        "name": "calculator",
+        "capabilities": ["add", "subtract", "multiply", "divide"]
+      },
+      {
+        "type": "http",
+        "name": "web_search",
+        "endpoint": "https://api.search.example.com",
+        "capabilities": ["search"]
+      }
+    ]
+  },
+  "extensions": {
+    "langchain": {
+      "enabled": true,
+      "chain_type": "agent",
+      "tool_class": "LangChainTool",
+      "memory": {
+        "type": "buffer",
+        "max_tokens": 1000
+      }
+    }
+  }
+}
+

package/examples/langflow/workflow-agent.ossa.json

@@ -0,0 +1,39 @@
+{
+  "apiVersion": "ossa/v0.2",
+  "kind": "Agent",
+  "metadata": {
+    "name": "workflow-orchestrator",
+    "version": "1.0.0",
+    "description": "Langflow workflow orchestration agent"
+  },
+  "spec": {
+    "role": "You orchestrate complex workflows by coordinating multiple AI agents and tools.",
+    "llm": {
+      "provider": "openai",
+      "model": "gpt-4",
+      "temperature": 0.5
+    },
+    "tools": []
+  },
+  "extensions": {
+    "langflow": {
+      "enabled": true,
+      "flow_id": "workflow-orchestrator-v1",
+      "flow_name": "Multi-Agent Workflow Orchestrator",
+      "endpoint": "https://api.langflow.example.com",
+      "components": [
+        {
+          "id": "llm-1",
+          "type": "OpenAI",
+          "name": "Primary LLM"
+        },
+        {
+          "id": "agent-1",
+          "type": "Agent",
+          "name": "Workflow Coordinator"
+        }
+      ]
+    }
+  }
+}
+

package/examples/langgraph/state-machine-agent.ossa.json

@@ -0,0 +1,59 @@
+{
+  "apiVersion": "ossa/v0.2",
+  "kind": "Agent",
+  "metadata": {
+    "name": "state-machine-agent",
+    "version": "1.0.0",
+    "description": "LangGraph state machine agent"
+  },
+  "spec": {
+    "role": "You are a state machine agent that processes requests through defined states.",
+    "llm": {
+      "provider": "openai",
+      "model": "gpt-4",
+      "temperature": 0.3
+    },
+    "tools": []
+  },
+  "extensions": {
+    "langgraph": {
+      "enabled": true,
+      "graph_name": "request-processor",
+      "state_schema": {
+        "messages": "list",
+        "current_state": "str",
+        "data": "dict"
+      },
+      "nodes": [
+        {
+          "name": "start",
+          "function": "initialize"
+        },
+        {
+          "name": "process",
+          "function": "process_request"
+        },
+        {
+          "name": "validate",
+          "function": "validate_response"
+        }
+      ],
+      "edges": [
+        {
+          "from": "start",
+          "to": "process"
+        },
+        {
+          "from": "process",
+          "to": "validate",
+          "condition": "should_validate"
+        }
+      ],
+      "checkpoint": {
+        "enabled": true,
+        "type": "memory"
+      }
+    }
+  }
+}
+

package/examples/llamaindex/rag-agent.ossa.json

@@ -0,0 +1,41 @@
+{
+  "apiVersion": "ossa/v0.2",
+  "kind": "Agent",
+  "metadata": {
+    "name": "rag-query-agent",
+    "version": "1.0.0",
+    "description": "LlamaIndex RAG query engine agent"
+  },
+  "spec": {
+    "role": "You answer questions by retrieving and synthesizing information from a knowledge base.",
+    "llm": {
+      "provider": "openai",
+      "model": "gpt-4",
+      "temperature": 0.1
+    },
+    "tools": []
+  },
+  "extensions": {
+    "llamaindex": {
+      "enabled": true,
+      "agent_type": "query_engine",
+      "llm": {
+        "provider": "openai",
+        "model": "gpt-4",
+        "temperature": 0.1
+      },
+      "vector_store": {
+        "type": "pinecone",
+        "config": {
+          "index_name": "knowledge-base",
+          "environment": "us-east-1"
+        }
+      },
+      "retrieval": {
+        "top_k": 5,
+        "similarity_top_k": 10
+      }
+    }
+  }
+}
+

package/examples/migration-guides/from-langchain-to-ossa.yaml

@@ -0,0 +1,309 @@
+# ============================================================================
+# Migration Guide: LangChain Agents → OSSA
+# ============================================================================
+#
+# PURPOSE:
+#   This guide demonstrates how to migrate a LangChain agent to OSSA format.
+#   LangChain uses Python-based agent definitions with tools and chains.
+#   OSSA uses declarative YAML manifests that are framework-agnostic.
+#
+# KEY DIFFERENCES:
+#   1. LangChain: Code-based (Python), OSSA: Declarative (YAML)
+#   2. LangChain: Framework-specific, OSSA: Framework-agnostic
+#   3. LangChain: Runtime-coupled, OSSA: Runtime-independent
+#   4. LangChain: Tool execution in code, OSSA: Tool declaration in manifest
+#
+# MIGRATION BENEFITS:
+#   - Deploy to any runtime (not just Python/LangChain)
+#   - Standardized agent definitions across teams
+#   - Better observability and compliance
+#   - Easier testing and validation
+#   - Framework independence
+#
+# ============================================================================
+
+# ----------------------------------------------------------------------------
+# EXAMPLE 1: Simple LangChain Agent → OSSA
+# ----------------------------------------------------------------------------
+#
+# LANGCHAIN CODE (Before):
+# ```python
+# from langchain.agents import initialize_agent, Tool
+# from langchain.llms import OpenAI
+#
+# llm = OpenAI(temperature=0)
+# tools = [
+#     Tool(
+#         name="Search",
+#         func=search_function,
+#         description="Search the web for current information"
+#     ),
+#     Tool(
+#         name="Calculator",
+#         func=calculator_function,
+#         description="Perform mathematical calculations"
+#     )
+# ]
+# agent = initialize_agent(tools, llm, agent="zero-shot-react-description")
+# ```
+#
+# OSSA MANIFEST (After):
+# ----------------------------------------------------------------------------
+
+apiVersion: ossa/v0.2.2
+kind: Agent
+
+metadata:
+  name: langchain-migrated-agent
+  version: 1.0.0
+  description: |
+    Migrated from LangChain zero-shot-react-description agent.
+    Provides web search and calculator capabilities.
+
+spec:
+  role: |
+    You are a helpful assistant that can search the web and perform calculations.
+    Use the available tools to answer user questions accurately.
+    When searching, provide sources. When calculating, show your work.
+  
+  llm:
+    provider: openai
+    model: gpt-3.5-turbo
+    temperature: 0  # Matches LangChain's temperature=0
+  
+  tools:
+    # LangChain Tool: Search → OSSA Tool
+    - type: http
+      name: Search
+      description: Search the web for current information
+      endpoint: https://api.search-service.com/search
+      config:
+        method: POST
+        timeout: 10
+      auth:
+        type: apikey
+        credentials: SEARCH_API_KEY
+    
+    # LangChain Tool: Calculator → OSSA Tool
+    - type: function
+      name: Calculator
+      description: Perform mathematical calculations
+      config:
+        handler: calculator_handler
+        language: python
+        timeout: 5
+
+# ----------------------------------------------------------------------------
+# EXAMPLE 2: LangChain Agent with Custom Tools → OSSA
+# ----------------------------------------------------------------------------
+#
+# LANGCHAIN CODE (Before):
+# ```python
+# from langchain.agents import AgentExecutor, create_react_agent
+# from langchain.prompts import PromptTemplate
+# from langchain.tools import DuckDuckGoSearchRun
+#
+# tools = [DuckDuckGoSearchRun()]
+# prompt = PromptTemplate.from_template("""
+#     Answer the following questions as best you can.
+#     Use the following tools: {tools}
+#     Question: {input}
+# """)
+# agent = create_react_agent(llm, tools, prompt)
+# agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)
+# ```
+#
+# OSSA MANIFEST (After):
+# ----------------------------------------------------------------------------
+
+---
+apiVersion: ossa/v0.2.2
+kind: Agent
+
+metadata:
+  name: react-agent-migrated
+  version: 1.0.0
+  description: |
+    Migrated LangChain ReAct agent with DuckDuckGo search.
+    Uses ReAct (Reasoning + Acting) pattern for tool use.
+
+spec:
+  # The role field replaces LangChain's prompt template
+  role: |
+    Answer the following questions as best you can.
+    Use the available tools to gather information and answer accurately.
+    Think step by step: reason about what you need, then act using tools.
+  
+  llm:
+    provider: openai
+    model: gpt-4  # ReAct works better with more capable models
+    temperature: 0.3
+  
+  tools:
+    # DuckDuckGo Search Tool
+    - type: http
+      name: DuckDuckGoSearch
+      description: Search the web using DuckDuckGo for current information
+      endpoint: https://api.duckduckgo.com/
+      config:
+        method: GET
+        timeout: 10
+      auth:
+        type: none
+  
+  # Enable verbose logging (equivalent to LangChain's verbose=True)
+  observability:
+    logging:
+      level: debug
+      format: json
+
+# ----------------------------------------------------------------------------
+# EXAMPLE 3: LangChain Multi-Agent System → OSSA Orchestration
+# ----------------------------------------------------------------------------
+#
+# LANGCHAIN CODE (Before):
+# ```python
+# from langchain.agents import AgentExecutor
+# from langchain.agents.agent_types import AgentType
+#
+# # Supervisor agent
+# supervisor = initialize_agent(
+#     tools=[],
+#     llm=llm,
+#     agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION
+# )
+#
+# # Worker agents
+# research_agent = initialize_agent(research_tools, llm, ...)
+# writing_agent = initialize_agent(writing_tools, llm, ...)
+# ```
+#
+# OSSA APPROACH (After):
+#   Create separate OSSA manifests for each agent, then orchestrate them.
+#   See examples/agent-manifests/orchestrators/ for orchestration patterns.
+#
+# ----------------------------------------------------------------------------
+
+---
+apiVersion: ossa/v0.2.2
+kind: Agent
+
+metadata:
+  name: research-agent
+  version: 1.0.0
+  description: Research agent migrated from LangChain multi-agent system
+
+spec:
+  role: |
+    You are a research specialist. Your job is to gather accurate,
+    up-to-date information on topics requested by the supervisor agent.
+    Provide comprehensive, well-sourced research results.
+  
+  llm:
+    provider: openai
+    model: gpt-4
+    temperature: 0.2
+  
+  tools:
+    - type: http
+      name: WebSearch
+      description: Search the web for information
+      endpoint: https://api.search.com/search
+    - type: http
+      name: AcademicSearch
+      description: Search academic papers and publications
+      endpoint: https://api.academic.com/search
+
+---
+apiVersion: ossa/v0.2.2
+kind: Agent
+
+metadata:
+  name: writing-agent
+  version: 1.0.0
+  description: Writing agent migrated from LangChain multi-agent system
+
+spec:
+  role: |
+    You are a writing specialist. Your job is to create well-structured,
+    clear content based on research provided by the research agent.
+    Write in a professional, engaging style.
+  
+  llm:
+    provider: openai
+    model: gpt-4
+    temperature: 0.7
+  
+  tools:
+    - type: function
+      name: FormatDocument
+      description: Format documents in various styles (Markdown, HTML, LaTeX)
+      config:
+        handler: format_handler
+
+# ============================================================================
+# MIGRATION CHECKLIST
+# ============================================================================
+#
+# [ ] 1. Identify LangChain agent type (zero-shot, react, conversational, etc.)
+# [ ] 2. Map LangChain tools to OSSA tools (type: http, function, mcp, etc.)
+# [ ] 3. Convert prompt templates to OSSA role field
+# [ ] 4. Map LLM configuration (model, temperature, etc.)
+# [ ] 5. Define autonomy level (supervised vs autonomous)
+# [ ] 6. Add observability configuration (tracing, metrics, logging)
+# [ ] 7. Define constraints (cost limits, performance, resources)
+# [ ] 8. Validate manifest: ossa validate <manifest.yaml>
+# [ ] 9. Test agent behavior matches LangChain version
+# [ ] 10. Update deployment configuration
+# [ ] 11. Update documentation and runbooks
+#
+# ============================================================================
+# COMMON PATTERNS
+# ============================================================================
+#
+# LangChain Tool → OSSA Tool Type Mapping:
+#   - Python function → type: function
+#   - API endpoint → type: http
+#   - Database query → type: custom (with config)
+#   - File operations → type: function or mcp
+#
+# LangChain Agent Types → OSSA Role Patterns:
+#   - zero-shot-react-description → ReAct-style role with tool descriptions
+#   - conversational-react-description → Conversational role with memory
+#   - structured-chat → Structured role with schema validation
+#
+# ============================================================================
+# VALIDATION & TESTING
+# ============================================================================
+#
+# 1. Validate OSSA manifest:
+#    $ ossa validate examples/migration-guides/from-langchain-to-ossa.yaml
+#
+# 2. Compare behavior:
+#    - Run LangChain agent with test inputs
+#    - Run OSSA agent with same inputs
+#    - Compare outputs and behavior
+#
+# 3. Performance testing:
+#    - Measure latency differences
+#    - Compare resource usage
+#    - Validate cost constraints
+#
+# ============================================================================
+# NEXT STEPS
+# ============================================================================
+#
+# After migration:
+# 1. Deploy OSSA agent to your infrastructure
+# 2. Set up observability (tracing, metrics, logs)
+# 3. Configure cost and performance constraints
+# 4. Integrate with agent registry/discovery
+# 5. Document agent capabilities and usage
+#
+# See also:
+# - examples/migration-guides/from-anthropic-sdk-to-ossa.yaml
+# - examples/migration-guides/from-mcp-to-ossa.yaml
+# - examples/advanced/ for complex patterns
+#
+# ============================================================================
+