@bluefly/openstandardagents 0.2.4

package/examples/minimal/agent.yml

@@ -0,0 +1,152 @@
+# ========================================
+# Hello World - Minimal OSSA Agent Example
+# ========================================
+#
+# Use Case:
+#   Simplest possible OSSA agent to demonstrate core concepts
+#   and provide a starting template for beginners.
+#
+# Target Audience:
+#   Developers learning OSSA fundamentals, new agent creators,
+#   teams evaluating OSSA for their infrastructure.
+#
+# Complexity Level:
+#   Minimal - ~50 lines, covers essential fields only, no advanced features
+#
+# Key Concepts Demonstrated:
+#   1. Minimal required fields for OSSA compliance
+#   2. Basic capability definition (greeting, echo, status)
+#   3. Simple REST API endpoint mapping
+#   4. Service discovery configuration
+#
+# Related Examples:
+#   - See ../production/ for enterprise-grade examples
+#   - See ../advanced/ for complex multi-capability agents
+#   - See ../kagent/ for Kubernetes-integrated examples
+#
+# Learning Path:
+#   1. Start here to understand basic structure
+#   2. Move to ../production/ for best practices
+#   3. Explore ../advanced/ for custom configurations
+#
+# ========================================
+
+# OSSA specification version (required)
+# This declares which version of the OSSA spec this manifest adheres to
+# Current stable version: 1.0
+ossa: 1.0
+
+# Agent metadata section (required)
+agent:
+  # Unique identifier for this agent across all deployments
+  # Format: lowercase alphanumeric + hyphens (DNS-safe)
+  # Example: "hello-world", "user-auth-agent", "data-processor-v2"
+  name: hello-world
+
+  # Semantic version of the agent (major.minor.patch)
+  # Increment when creating breaking changes, features, or fixes
+  # Example: 1.0.0 → 1.0.1 (patch fix) → 1.1.0 (new feature) → 2.0.0 (breaking change)
+  version: 1.0.0
+
+  # Human-readable description displayed in registries and dashboards
+  # Keep to 1-2 sentences; detailed docs belong in README/wiki
+  description: Minimal OSSA-compliant agent example
+
+  # Author or organization name for attribution and support contact
+  # Can be team name, company, or individual contributor
+  author: OSSA Community
+
+  # Software license identifier (SPDX standard)
+  # Common: MIT, Apache-2.0, GPL-3.0, Proprietary
+  # See https://spdx.org/licenses/ for complete list
+  license: MIT
+
+# Service discovery configuration (required for production)
+# Controls how other services find and register this agent
+discover:
+  # Enable automatic service discovery
+  # true = agent automatically registers itself when deployed
+  # false = manual registration required via external registry
+  auto: true
+
+# Agent capabilities (required)
+# Lists logical functions/features this agent can perform
+# Each capability can be invoked through REST API endpoints
+# Format: list of capability names (lowercase, hyphen-separated)
+capabilities:
+  # Simple greeting capability - generates personalized responses
+  - greeting
+
+  # Echo capability - reflects input back (useful for testing/debugging)
+  - echo
+
+  # Status capability - reports agent health and runtime information
+  - status
+
+# REST API endpoint definitions (required)
+# Maps HTTP methods + paths to agent capabilities
+# Enables external services to invoke agent functionality
+api:
+  # POST /greet endpoint
+  # HTTP Method: POST (creates/executes something)
+  # Path: /greet (relative to agent base URL)
+  POST /greet:
+    # Which capability this endpoint invokes
+    # Must match a name in the capabilities list above
+    capability: greeting
+
+    # Human-readable description for API documentation
+    # Displayed in OpenAPI/Swagger documentation
+    description: Generate a personalized greeting
+
+  # POST /echo endpoint
+  # Demonstrates request body processing capability
+  POST /echo:
+    # Routes to echo capability defined above
+    capability: echo
+
+    # Documents expected behavior in API docs
+    description: Echo input back to user
+
+  # GET /status endpoint
+  # HTTP Method: GET (retrieves information without side effects)
+  # Used for health checks, monitoring, and readiness probes
+  GET /status:
+    # Links to status capability for runtime inspection
+    capability: status
+
+    # Documents the purpose of status endpoint
+    description: Get agent status
+
+# ========================================
+# Validation & Next Steps
+# ========================================
+#
+# To validate this manifest:
+#
+#   ossa validate ./agent.yml
+#
+# To validate with strict OSSA 1.0 compliance:
+#
+#   ossa validate ./agent.yml --version 1.0 --strict
+#
+# To create a new agent from this template:
+#
+#   ossa init my-agent --template minimal
+#   # Then customize agent.yml with your values
+#
+# To run this agent locally:
+#
+#   ossa run ./agent.yml --port 3000
+#   # Then test endpoints:
+#   curl -X POST http://localhost:3000/greet -H "Content-Type: application/json" -d '{"name":"World"}'
+#   curl -X GET http://localhost:3000/status
+#
+# Key Next Steps:
+#   1. Customize name, description, author for your use case
+#   2. Define actual implementation for each capability
+#   3. Add request/response schemas for type safety
+#   4. Add authentication/authorization if needed (see ../production/)
+#   5. Push to registry: ossa publish ./agent.yml
+#
+# ========================================

package/examples/minimal/openapi.yaml

@@ -0,0 +1,95 @@
+openapi: 3.1.0
+info:
+  title: Hello World Agent
+  version: 1.0.0
+  description: Minimal OSSA-compliant agent API
+
+servers:
+  - url: http://localhost:3000
+    description: Local development server
+
+paths:
+  /greet:
+    post:
+      summary: Generate greeting
+      operationId: greet
+      tags: [greeting]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [name]
+              properties:
+                name:
+                  type: string
+                  description: Name to greet
+                language:
+                  type: string
+                  enum: [en, es, fr, de]
+                  default: en
+      responses:
+        '200':
+          description: Greeting generated successfully
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  message:
+                    type: string
+                  timestamp:
+                    type: string
+                    format: date-time
+
+  /echo:
+    post:
+      summary: Echo input
+      operationId: echo
+      tags: [echo]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [message]
+              properties:
+                message:
+                  type: string
+      responses:
+        '200':
+          description: Message echoed
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  echo:
+                    type: string
+                  received_at:
+                    type: string
+                    format: date-time
+
+  /status:
+    get:
+      summary: Get agent status
+      operationId: getStatus
+      tags: [status]
+      responses:
+        '200':
+          description: Agent status
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  status:
+                    type: string
+                    enum: [online, offline, maintenance]
+                  version:
+                    type: string
+                  uptime:
+                    type: integer
+                    description: Uptime in seconds

package/examples/openai/swarm-agent.ossa.json

@@ -0,0 +1,59 @@
+{
+  "apiVersion": "ossa/v0.2.3",
+  "kind": "Agent",
+  "metadata": {
+    "name": "swarm-agent",
+    "version": "1.0.0",
+    "description": "OpenAI Agents SDK swarm agent"
+  },
+  "spec": {
+    "role": "You are a helpful AI assistant that can coordinate with other agents to solve complex tasks.",
+    "llm": {
+      "provider": "openai",
+      "model": "gpt-4o",
+      "temperature": 0.7
+    },
+    "tools": [
+      {
+        "type": "function",
+        "name": "search_web",
+        "capabilities": ["search", "retrieve"]
+      },
+      {
+        "type": "function",
+        "name": "execute_code",
+        "capabilities": ["run", "evaluate"]
+      }
+    ]
+  },
+  "extensions": {
+    "openai_agents": {
+      "enabled": true,
+      "model": "gpt-4o",
+      "instructions": "You are a helpful AI assistant that can coordinate with other agents to solve complex tasks.",
+      "tools_mapping": [
+        {
+          "ossa_capability": "search_web",
+          "openai_tool_name": "web_search",
+          "description": "Search the web for information"
+        },
+        {
+          "ossa_capability": "execute_code",
+          "openai_tool_name": "code_executor",
+          "description": "Execute Python code safely"
+        }
+      ],
+      "guardrails": {
+        "enabled": true,
+        "max_tool_calls": 10,
+        "timeout_seconds": 300
+      },
+      "memory": {
+        "enabled": true,
+        "type": "session",
+        "max_messages": 50
+      }
+    }
+  }
+}
+

package/examples/openapi-extensions/README.md

@@ -0,0 +1,87 @@
+# OSSA OpenAPI Extensions Examples
+
+This directory contains example OpenAPI 3.1 specifications demonstrating OSSA extensions for AI agents.
+
+## Examples
+
+### minimal-agent-api.openapi.yml
+
+**Purpose**: Minimal example showing basic OSSA extensions
+
+**Features Demonstrated**:
+- Root-level `x-ossa-metadata` extension
+- Root-level `x-ossa` extension with agent identification
+- Operation-level `x-ossa-capability` extension
+- Operation-level `x-ossa-autonomy` extension
+- Operation-level `x-ossa-llm` extension
+
+**Use Case**: Simple greeting agent that demonstrates the basics of OSSA extensions without complexity.
+
+### worker-agent-api.openapi.yml
+
+**Purpose**: Complete worker agent API showing all OSSA extensions
+
+**Features Demonstrated**:
+- Full `x-ossa-metadata` with governance and compliance
+- Complete `x-ossa` and `x-agent` root extensions
+- All operation-level extensions (capability, autonomy, constraints, tools, llm)
+- Parameter extensions (`X-OSSA-Agent-ID`, `X-OSSA-Version`)
+- Schema extensions (`x-ossa-capability-schema`)
+- Real-world example: Kubernetes troubleshooting agent
+
+**Use Case**: Production-ready worker agent that diagnoses Kubernetes pod issues using MCP tools.
+
+### orchestrator-agent-api.openapi.yml
+
+**Purpose**: Multi-agent orchestration example
+
+**Features Demonstrated**:
+- Orchestrator agent type
+- Multi-agent coordination capabilities
+- Complex workflow execution with task delegation
+- Higher-level constraints for orchestrator operations
+- Multiple MCP tool integrations (agent-router, agent-mesh, workflow-engine)
+
+**Use Case**: Orchestrator that coordinates multiple worker agents to execute complex workflows.
+
+## Running Examples
+
+### Validate Examples
+
+```bash
+# Validate a specific example
+ossa validate --openapi examples/openapi-extensions/minimal-agent-api.openapi.yml
+
+# Validate all examples
+find examples/openapi-extensions -name "*.openapi.yml" -exec ossa validate --openapi {} \;
+```
+
+### Using with OpenAPI Tools
+
+All examples are valid OpenAPI 3.1 specs and work with standard OpenAPI tools:
+
+```bash
+# Generate documentation with Redoc
+npx @redocly/cli build-docs examples/openapi-extensions/worker-agent-api.openapi.yml
+
+# Generate client with openapi-generator
+npx @openapitools/openapi-generator-cli generate \
+  -i examples/openapi-extensions/worker-agent-api.openapi.yml \
+  -g typescript-axios \
+  -o ./generated-client
+```
+
+### Viewing Examples
+
+Use any OpenAPI viewer:
+- [Swagger Editor](https://editor.swagger.io/) - Paste YAML content
+- [Swagger UI](https://swagger.io/tools/swagger-ui/) - Host locally
+- [Stoplight Studio](https://stoplight.io/studio) - Desktop app
+
+## Documentation
+
+For complete documentation on OSSA OpenAPI extensions, see:
+- [OpenAPI Extensions Documentation](../../docs/openapi-extensions.md)
+- [OSSA Specification](../../spec/v0.2.2/OSSA-SPECIFICATION-v0.2.2.md)
+- [GitLab Wiki](https://gitlab.bluefly.io/llm/openapi-ai-agents-standard/-/wikis/home)
+

package/examples/openapi-extensions/minimal-agent-api.openapi.yml

@@ -0,0 +1,288 @@
+# ============================================================================
+# OSSA OpenAPI Extensions Example: Minimal Agent API
+# ============================================================================
+#
+# PURPOSE:
+#   Demonstrates the minimal OpenAPI 3.1 specification with OSSA extensions
+#   for defining agent APIs. Shows how to add OSSA metadata to standard
+#   OpenAPI specs for agent discovery, validation, and lifecycle management.
+#
+# KEY CONCEPTS:
+#   - OpenAPI 3.1 as the base specification (JSON Schema compatible)
+#   - OSSA extensions via x-ossa-* fields (vendor extensions)
+#   - Agent capabilities mapped to OpenAPI operations
+#   - Type-safe contracts with JSON Schema validation
+#   - LLM configuration at the operation level
+#
+# ARCHITECTURE:
+#   OpenAPI 3.1 Spec
+#     + x-ossa-metadata (document-level OSSA info)
+#     + x-ossa (agent configuration)
+#     + x-ossa-capability (operation-level capability metadata)
+#     + x-ossa-autonomy (operation-level autonomy controls)
+#     + x-ossa-llm (operation-level LLM configuration)
+#     → OSSA-compliant Agent API
+#
+# USE CASE:
+#   Simple greeting agent that generates personalized greetings in multiple
+#   languages using GPT-3.5-turbo. Demonstrates OSSA's OpenAPI-first approach.
+#
+# RELATED DOCUMENTATION:
+#   - OSSA OpenAPI Extensions: spec/OSSA_OpenAPI_Extensions.md
+#   - OpenAPI 3.1 Spec: https://spec.openapis.org/oas/v3.1.0
+#   - Worker Agent Example: examples/openapi-extensions/worker-agent-api.openapi.yml
+# ============================================================================
+
+openapi: 3.1.0
+
+# ============================================================================
+# API Information Block (Standard OpenAPI)
+# ============================================================================
+info:
+  title: Hello World Agent API
+  version: 1.0.0
+  description: |
+    Minimal OSSA-compliant agent API demonstrating basic OpenAPI extensions.
+    This example shows a simple greeting agent with OSSA metadata.
+
+# ============================================================================
+# OSSA Metadata Extension (Document-Level)
+# ============================================================================
+# x-ossa-metadata provides OSSA-specific information about the API document.
+# This is separate from the agent configuration (x-ossa) to allow for
+# governance, compliance, and operational metadata.
+# ============================================================================
+x-ossa-metadata:
+  # OSSA specification version this document conforms to
+  version: 0.2.2
+
+  # Compliance information for governance and audit
+  compliance:
+    level: basic              # basic, intermediate, advanced, enterprise
+    frameworks:
+      - OSSA                  # Open Standard for System Agents
+      - OpenAPI 3.1           # Base specification
+
+# ============================================================================
+# OSSA Agent Configuration Extension
+# ============================================================================
+# x-ossa defines the agent's identity, type, and compliance status.
+# This metadata enables agent registries, discovery, and validation tools.
+# ============================================================================
+x-ossa:
+  # OSSA version (should match x-ossa-metadata.version)
+  version: 0.2.2
+
+  # Agent identity and type
+  agent:
+    # Unique agent identifier (DNS-compatible)
+    id: hello-world-agent
+
+    # Agent type determines execution model:
+    # - "worker": Task-based, stateless execution
+    # - "chat": Interactive, stateful conversation
+    # - "orchestrator": Coordinates other agents
+    # - "integration": Long-running service connector
+    type: worker
+
+    # Compliance tracking for validation pipelines
+    compliance:
+      # Standards this agent implementation adheres to
+      standards:
+        - openapi-first       # API-first design approach
+
+      # Validation status (set by OSSA validators)
+      validated: true
+      validatedAt: "2024-01-15T10:00:00Z"  # ISO 8601 timestamp
+
+# ============================================================================
+# API Paths (Standard OpenAPI with OSSA Extensions)
+# ============================================================================
+paths:
+  # ==========================================================================
+  # /greet - Generate Personalized Greeting
+  # ==========================================================================
+  # Demonstrates OSSA capability mapping to OpenAPI operation.
+  # Each operation represents one agent capability with:
+  # - Standard OpenAPI request/response schemas
+  # - OSSA capability metadata (x-ossa-capability)
+  # - Autonomy controls (x-ossa-autonomy)
+  # - LLM configuration (x-ossa-llm)
+  # ==========================================================================
+  /greet:
+    post:
+      # Standard OpenAPI operation metadata
+      summary: Generate greeting
+      description: Generates a personalized greeting using LLM
+
+      # Unique operation identifier (used for code generation)
+      operationId: greet
+
+      # Tags for grouping operations in documentation
+      tags:
+        - Greeting
+
+      # ======================================================================
+      # OSSA Capability Extension
+      # ======================================================================
+      # Maps this OpenAPI operation to an OSSA agent capability.
+      # Capability name must match agent manifest capability IDs.
+      # ======================================================================
+      x-ossa-capability: greeting
+
+      # ======================================================================
+      # OSSA Autonomy Extension
+      # ======================================================================
+      # Defines autonomy level and approval requirements for this operation.
+      # Controls how much freedom the agent has when executing this capability.
+      # ======================================================================
+      x-ossa-autonomy:
+        # Autonomy levels:
+        # - "autonomous": Agent can execute without human approval
+        # - "supervised": Human must approve before execution
+        # - "collaborative": Human and agent work together
+        level: autonomous
+
+        # Whether approval is required (overrides level if true)
+        approval_required: false
+
+      # ======================================================================
+      # OSSA LLM Extension
+      # ======================================================================
+      # Specifies which LLM to use for this specific operation.
+      # Allows per-operation model selection for cost/performance optimization.
+      # ======================================================================
+      x-ossa-llm:
+        provider: openai             # LLM provider (openai, anthropic, etc.)
+        model: gpt-3.5-turbo         # Model identifier (fast, low-cost)
+        temperature: 0.7             # Creativity level (0.0-1.0)
+
+      # Standard OpenAPI request body definition
+      requestBody:
+        required: true
+        content:
+          # JSON content type (most common for agent APIs)
+          application/json:
+            # JSON Schema for request validation
+            schema:
+              type: object
+
+              # Required fields (validated before execution)
+              required:
+                - name
+
+              properties:
+                # Person's name to include in greeting
+                name:
+                  type: string
+                  description: Name to greet
+                  example: "Alice"
+
+                # Target language for greeting (enum constraint)
+                language:
+                  type: string
+                  enum:
+                    - en    # English
+                    - es    # Spanish
+                    - fr    # French
+                    - de    # German
+                  default: en
+                  description: Language for greeting
+
+      # Response definitions (standard OpenAPI)
+      responses:
+        # Success response (200 OK)
+        '200':
+          description: Greeting generated successfully
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  # Generated greeting text
+                  message:
+                    type: string
+                    description: The greeting message
+                    example: "Hello, Alice! Welcome to OSSA."
+
+                  # Timestamp for audit trail
+                  timestamp:
+                    type: string
+                    format: date-time
+                    description: When the greeting was generated
+
+  # ==========================================================================
+  # /status - Agent Health Check
+  # ==========================================================================
+  # Standard health check endpoint for monitoring and orchestration.
+  # Does not use LLM, so no x-ossa-llm extension needed.
+  # ==========================================================================
+  /status:
+    get:
+      summary: Get agent status
+      description: Returns the current status of the agent
+      operationId: getStatus
+
+      tags:
+        - Status
+
+      responses:
+        '200':
+          description: Agent status
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  # Current operational status
+                  status:
+                    type: string
+                    enum:
+                      - online        # Agent is operational
+                      - offline       # Agent is not responding
+                      - maintenance   # Agent is in maintenance mode
+                    description: Current agent status
+
+                  # Agent version for deployment tracking
+                  version:
+                    type: string
+                    description: Agent version
+
+                  # Uptime metric for monitoring
+                  uptime:
+                    type: integer
+                    description: Uptime in seconds
+
+# ============================================================================
+# End of Minimal OSSA OpenAPI Example
+# ============================================================================
+#
+# VALIDATION:
+#   # Validate OpenAPI spec
+#   swagger-cli validate minimal-agent-api.openapi.yml
+#
+#   # Validate OSSA extensions
+#   ossa validate minimal-agent-api.openapi.yml
+#
+# CODE GENERATION:
+#   # Generate server stub
+#   openapi-generator generate -i minimal-agent-api.openapi.yml \
+#     -g python-flask -o ./server
+#
+#   # Generate client SDK
+#   openapi-generator generate -i minimal-agent-api.openapi.yml \
+#     -g typescript-axios -o ./client
+#
+# KEY TAKEAWAYS:
+#   1. OSSA extends OpenAPI 3.1 with x-ossa-* vendor extensions
+#   2. Standard OpenAPI tooling still works (validators, generators, docs)
+#   3. OSSA extensions add agent-specific metadata (capabilities, autonomy, LLM)
+#   4. One OpenAPI operation = One agent capability
+#   5. Type-safe contracts with JSON Schema validation
+#
+# RELATED EXAMPLES:
+#   - examples/openapi-extensions/worker-agent-api.openapi.yml (full features)
+#   - examples/drupal/gitlab-ml-recommender.ossa.yaml (YAML manifest format)
+#   - spec/OSSA_OpenAPI_Extensions.md (complete specification)
+# ============================================================================
+