@bluefly/openstandardagents 0.1.9 → 0.2.5-RC

package/specs/ossa-complete.openapi.yml

@@ -1,2250 +0,0 @@
-openapi: 3.1.0
-info:
-  title: OSSA Complete API
-  version: 0.1.9
-  summary: Open Standards for Scalable Agents - Complete OpenAPI 3.1 Implementation
-  description: |
-    # OSSA Complete API v0.1.9
-
-    This is a comprehensive OpenAPI 3.1 specification showcasing all advanced features:
-    - **JSON Schema Draft 2020-12** for validation
-    - **Webhooks** for event-driven architecture
-    - **Discriminator mapping** for polymorphic schemas
-    - **Content encoding** for binary data
-    - **Security schemes** with OAuth 2.1 and API keys
-    - **Path templating** with complex parameters
-    - **Advanced examples** with external references
-    - **Callbacks** for asynchronous operations
-    - **Links** for HATEOAS implementation
-
-    ## Agent Types Hierarchy
-    
-    OSSA defines a sophisticated agent taxonomy with inheritance and composition:
-    
-    ```
-    Agent (base)
-    ├── ExecutionAgent
-    │   ├── WorkerAgent (task execution)
-    │   ├── OrchestratorAgent (coordination)
-    │   └── ProcessorAgent (data transformation)
-    ├── GovernanceAgent
-    │   ├── CriticAgent (quality control)
-    │   ├── JudgeAgent (decision making)
-    │   └── GovernorAgent (policy enforcement)
-    └── ObservabilityAgent
-        ├── MonitorAgent (system observation)
-        ├── TracerAgent (execution tracking)
-        └── AuditorAgent (compliance logging)
-    ```
-
-    ## OpenAPI 3.1 Features Demonstrated
-
-    This specification showcases:
-    - ✅ JSON Schema Draft 2020-12 (`$schema`, `$vocabulary`)
-    - ✅ Discriminator with mapping for polymorphic inheritance
-    - ✅ Webhooks for event-driven notifications
-    - ✅ Content encoding for binary payloads
-    - ✅ Advanced security with OAuth 2.1 PKCE
-    - ✅ Path item references and reusable components
-    - ✅ Examples with external references
-    - ✅ Callbacks for async workflow triggers
-    - ✅ Links for HATEOAS navigation
-    - ✅ Multiple content types per operation
-    - ✅ Complex parameter dependencies
-    - ✅ Conditional schemas with `if/then/else`
-
-  termsOfService: https://ossa.bluefly.io/terms
-  contact:
-    name: OSSA Development Team
-    url: https://gitlab.bluefly.io/llm/openapi-ai-agents-standard
-    email: ossa@bluefly.io
-  license:
-    name: MIT
-    url: https://spdx.org/licenses/MIT.html
-  x-logo:
-    url: https://ossa.bluefly.io/logo.svg
-    altText: OSSA Logo
-
-externalDocs:
-  description: Complete OSSA Documentation
-  url: https://docs.ossa.bluefly.io
-
-servers:
-  - url: https://api.ossa.bluefly.io/v1
-    description: Production Server
-  - url: https://staging.api.ossa.bluefly.io/v1
-    description: Staging Server
-  - url: http://localhost:3000/v1
-    description: Local Development Server
-
-tags:
-  - name: Agents
-    description: Agent lifecycle management operations
-    externalDocs:
-      description: Agent Management Guide
-      url: https://docs.ossa.bluefly.io/agents
-  - name: Specifications
-    description: OpenAPI specification operations
-    externalDocs:
-      description: Specification Guide
-      url: https://docs.ossa.bluefly.io/specs
-  - name: Orchestration
-    description: Workflow and orchestration operations
-  - name: Registry
-    description: Agent discovery and registration
-  - name: Monitoring
-    description: System monitoring and observability
-  - name: Governance
-    description: Compliance and policy enforcement
-
-paths:
-  /agents:
-    get:
-      tags: [Agents]
-      summary: List all agents
-      description: |
-        Retrieve a paginated list of agents with advanced filtering and sorting capabilities.
-        
-        Supports:
-        - Type-based filtering with inheritance hierarchy
-        - Capability-based search with fuzzy matching
-        - Status filtering (active, inactive, error, deploying)
-        - Creation date range queries
-        - Performance metric filtering
-      operationId: listAgents
-      parameters:
-        - $ref: '#/components/parameters/PageParam'
-        - $ref: '#/components/parameters/LimitParam'
-        - $ref: '#/components/parameters/SortParam'
-        - name: type
-          in: query
-          description: Filter by agent type (supports inheritance)
-          schema:
-            $ref: '#/components/schemas/AgentType'
-          style: form
-          explode: false
-        - name: status
-          in: query
-          description: Filter by agent status
-          schema:
-            type: array
-            items:
-              $ref: '#/components/schemas/AgentStatus'
-          style: form
-          explode: true
-        - name: capabilities
-          in: query
-          description: Filter by required capabilities (AND logic)
-          schema:
-            type: array
-            items:
-              type: string
-            minItems: 1
-            maxItems: 10
-          style: form
-          explode: true
-        - name: created_after
-          in: query
-          description: Filter agents created after this timestamp
-          schema:
-            type: string
-            format: date-time
-        - name: performance_min
-          in: query
-          description: Minimum performance score (0-100)
-          schema:
-            type: number
-            minimum: 0
-            maximum: 100
-      responses:
-        '200':
-          description: List of agents retrieved successfully
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/AgentListResponse'
-              examples:
-                with_workers:
-                  summary: Response with worker agents
-                  externalValue: https://examples.ossa.bluefly.io/agents/workers.json
-                with_orchestrators:
-                  summary: Response with orchestrator agents
-                  value:
-                    agents:
-                      - id: "orch-001"
-                        type: "orchestrator"
-                        name: "Workflow Master"
-                        status: "active"
-                        created_at: "2025-01-15T10:30:00Z"
-                    pagination:
-                      page: 1
-                      limit: 20
-                      total: 1
-                      has_next: false
-            application/yaml:
-              schema:
-                $ref: '#/components/schemas/AgentListResponse'
-            text/csv:
-              schema:
-                type: string
-              example: |
-                id,type,name,status,created_at
-                agent-001,worker,Data Processor,active,2025-01-15T10:30:00Z
-        '400':
-          $ref: '#/components/responses/BadRequest'
-        '401':
-          $ref: '#/components/responses/Unauthorized'
-        '403':
-          $ref: '#/components/responses/Forbidden'
-        '429':
-          $ref: '#/components/responses/TooManyRequests'
-        '500':
-          $ref: '#/components/responses/InternalServerError'
-      callbacks:
-        agentStatusChange:
-          '{$request.body#/webhook_url}':
-            post:
-              summary: Agent status change notification
-              requestBody:
-                content:
-                  application/json:
-                    schema:
-                      $ref: '#/components/schemas/AgentStatusEvent'
-              responses:
-                '200':
-                  description: Webhook received successfully
-
-    post:
-      tags: [Agents]
-      summary: Create a new agent
-      description: |
-        Create a new agent with comprehensive validation and automatic capability inference.
-        
-        Features:
-        - **Polymorphic agent types** with discriminator-based validation
-        - **Automatic capability detection** from provided specifications
-        - **Version conflict resolution** with semantic versioning
-        - **Dependency validation** against existing agents
-        - **Resource quota enforcement** per organization
-        - **Async creation** with webhook notifications
-      operationId: createAgent
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/CreateAgentRequest'
-            examples:
-              worker_agent:
-                summary: Create a worker agent
-                value:
-                  type: "worker"
-                  name: "Data Processor"
-                  description: "Processes incoming data streams"
-                  capabilities: ["data-processing", "validation"]
-                  configuration:
-                    max_concurrent_tasks: 10
-                    timeout_seconds: 300
-              orchestrator_agent:
-                summary: Create an orchestrator agent
-                value:
-                  type: "orchestrator"
-                  name: "Workflow Manager"
-                  description: "Manages complex workflows"
-                  capabilities: ["orchestration", "monitoring"]
-                  configuration:
-                    max_concurrent_workflows: 5
-                    workflow_timeout_minutes: 60
-          application/yaml:
-            schema:
-              $ref: '#/components/schemas/CreateAgentRequest'
-          multipart/form-data:
-            schema:
-              type: object
-              properties:
-                agent_data:
-                  $ref: '#/components/schemas/CreateAgentRequest'
-                specification_file:
-                  type: string
-                  format: binary
-                  description: OpenAPI specification file
-                dockerfile:
-                  type: string
-                  format: binary
-                  description: Optional Dockerfile for containerized agents
-            encoding:
-              specification_file:
-                contentType: application/yaml, application/json
-              dockerfile:
-                contentType: text/plain
-      responses:
-        '201':
-          description: Agent created successfully
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Agent'
-          links:
-            GetAgent:
-              operationId: getAgent
-              parameters:
-                agent_id: '$response.body#/id'
-              description: Get the created agent details
-            UpdateAgent:
-              operationId: updateAgent
-              parameters:
-                agent_id: '$response.body#/id'
-              description: Update the created agent
-            DeleteAgent:
-              operationId: deleteAgent
-              parameters:
-                agent_id: '$response.body#/id'
-              description: Delete the created agent
-        '400':
-          $ref: '#/components/responses/BadRequest'
-        '401':
-          $ref: '#/components/responses/Unauthorized'
-        '403':
-          $ref: '#/components/responses/Forbidden'
-        '409':
-          description: Agent with this name already exists
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ConflictError'
-        '422':
-          description: Validation failed
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ValidationError'
-        '429':
-          $ref: '#/components/responses/TooManyRequests'
-        '500':
-          $ref: '#/components/responses/InternalServerError'
-
-  /agents/{agent_id}:
-    parameters:
-      - $ref: '#/components/parameters/AgentIdParam'
-    
-    get:
-      tags: [Agents]
-      summary: Get agent details
-      description: |
-        Retrieve detailed information about a specific agent including:
-        - Current status and health metrics
-        - Performance statistics and SLA compliance
-        - Capability matrix and dependencies
-        - Recent execution history
-        - Configuration and metadata
-      operationId: getAgent
-      parameters:
-        - name: include
-          in: query
-          description: Additional data to include in response
-          schema:
-            type: array
-            items:
-              type: string
-              enum: [metrics, history, dependencies, logs]
-          style: form
-          explode: true
-      responses:
-        '200':
-          description: Agent details retrieved successfully
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Agent'
-              examples:
-                worker_agent:
-                  $ref: '#/components/examples/WorkerAgentExample'
-                orchestrator_agent:
-                  $ref: '#/components/examples/OrchestratorAgentExample'
-            application/yaml:
-              schema:
-                $ref: '#/components/schemas/Agent'
-        '404':
-          $ref: '#/components/responses/NotFound'
-        '401':
-          $ref: '#/components/responses/Unauthorized'
-        '403':
-          $ref: '#/components/responses/Forbidden'
-        '500':
-          $ref: '#/components/responses/InternalServerError'
-
-    put:
-      tags: [Agents]
-      summary: Update agent
-      description: |
-        Update an existing agent with full replacement semantics.
-        
-        Supports:
-        - **Atomic updates** with rollback on failure
-        - **Version-aware updates** with optimistic locking
-        - **Capability migration** with backwards compatibility
-        - **Hot updates** for non-breaking changes
-        - **Blue-green deployment** for breaking changes
-      operationId: updateAgent
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/UpdateAgentRequest'
-      responses:
-        '200':
-          description: Agent updated successfully
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Agent'
-        '400':
-          $ref: '#/components/responses/BadRequest'
-        '401':
-          $ref: '#/components/responses/Unauthorized'
-        '403':
-          $ref: '#/components/responses/Forbidden'
-        '404':
-          $ref: '#/components/responses/NotFound'
-        '409':
-          description: Version conflict detected
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ConflictError'
-        '422':
-          $ref: '#/components/responses/ValidationError'
-        '500':
-          $ref: '#/components/responses/InternalServerError'
-
-    patch:
-      tags: [Agents]
-      summary: Partially update agent
-      description: |
-        Perform partial updates to an agent using JSON Patch (RFC 6902) operations.
-        
-        Supports atomic patch operations:
-        - `add` - Add new properties or array elements
-        - `remove` - Remove properties or array elements  
-        - `replace` - Replace existing values
-        - `move` - Move values within the document
-        - `copy` - Copy values within the document
-        - `test` - Test values before applying other operations
-      operationId: patchAgent
-      requestBody:
-        required: true
-        content:
-          application/json-patch+json:
-            schema:
-              type: array
-              items:
-                $ref: '#/components/schemas/JsonPatchOperation'
-            examples:
-              add_capability:
-                summary: Add a new capability
-                value:
-                  - op: "add"
-                    path: "/capabilities/-"
-                    value: "machine-learning"
-              update_status:
-                summary: Update agent status
-                value:
-                  - op: "replace"
-                    path: "/status"
-                    value: "maintenance"
-              remove_deprecated_config:
-                summary: Remove deprecated configuration
-                value:
-                  - op: "remove"
-                    path: "/configuration/deprecated_setting"
-      responses:
-        '200':
-          description: Agent patched successfully
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Agent'
-        '400':
-          $ref: '#/components/responses/BadRequest'
-        '401':
-          $ref: '#/components/responses/Unauthorized'
-        '403':
-          $ref: '#/components/responses/Forbidden'
-        '404':
-          $ref: '#/components/responses/NotFound'
-        '422':
-          description: Patch operation failed
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/PatchError'
-        '500':
-          $ref: '#/components/responses/InternalServerError'
-
-    delete:
-      tags: [Agents]
-      summary: Delete agent
-      description: |
-        Delete an agent with comprehensive cleanup and dependency management.
-        
-        Features:
-        - **Graceful shutdown** with configurable timeout
-        - **Dependency validation** to prevent orphaned workflows
-        - **Data retention policies** with configurable periods
-        - **Audit trail preservation** for compliance
-        - **Cascading deletion** of related resources
-      operationId: deleteAgent
-      parameters:
-        - name: force
-          in: query
-          description: Force deletion even if agent has active dependencies
-          schema:
-            type: boolean
-            default: false
-        - name: retention_days
-          in: query
-          description: Days to retain agent data after deletion
-          schema:
-            type: integer
-            minimum: 0
-            maximum: 365
-            default: 30
-      responses:
-        '204':
-          description: Agent deleted successfully
-        '400':
-          $ref: '#/components/responses/BadRequest'
-        '401':
-          $ref: '#/components/responses/Unauthorized'
-        '403':
-          $ref: '#/components/responses/Forbidden'
-        '404':
-          $ref: '#/components/responses/NotFound'
-        '409':
-          description: Cannot delete agent due to dependencies
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  error:
-                    type: string
-                    example: "Cannot delete agent due to active dependencies"
-                  dependencies:
-                    type: array
-                    items:
-                      type: object
-                      properties:
-                        type:
-                          type: string
-                          enum: [workflow, orchestration, subscription]
-                        id:
-                          type: string
-                        name:
-                          type: string
-        '500':
-          $ref: '#/components/responses/InternalServerError'
-
-  /agents/{agent_id}/execute:
-    parameters:
-      - $ref: '#/components/parameters/AgentIdParam'
-    
-    post:
-      tags: [Agents]
-      summary: Execute agent operation
-      description: |
-        Execute a specific operation on an agent with comprehensive input validation
-        and execution tracking.
-        
-        Execution Features:
-        - **Input schema validation** against agent capabilities
-        - **Execution context isolation** for security
-        - **Real-time progress tracking** via WebSocket
-        - **Result caching** with configurable TTL
-        - **Execution history** and audit logging
-        - **Resource quotas** and throttling
-      operationId: executeAgent
-      parameters:
-        - name: async
-          in: query
-          description: Execute asynchronously and return execution ID
-          schema:
-            type: boolean
-            default: false
-        - name: timeout
-          in: query
-          description: Maximum execution time in seconds
-          schema:
-            type: integer
-            minimum: 1
-            maximum: 3600
-            default: 300
-        - name: priority
-          in: query
-          description: Execution priority (higher numbers = higher priority)
-          schema:
-            type: integer
-            minimum: 1
-            maximum: 10
-            default: 5
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/ExecutionRequest'
-            examples:
-              data_processing:
-                summary: Data processing execution
-                value:
-                  operation: "process_data"
-                  input:
-                    data_source: "s3://bucket/data.json"
-                    transformation: "normalize"
-                    output_format: "parquet"
-                  context:
-                    user_id: "user-123"
-                    organization_id: "org-456"
-              workflow_orchestration:
-                summary: Workflow orchestration execution
-                value:
-                  operation: "execute_workflow"
-                  input:
-                    workflow_id: "wf-789"
-                    parameters:
-                      input_data: {"key": "value"}
-                      parallel_tasks: 3
-                  context:
-                    trigger: "api"
-                    correlation_id: "corr-999"
-      responses:
-        '200':
-          description: Execution completed successfully (synchronous)
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ExecutionResult'
-        '202':
-          description: Execution started (asynchronous)
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/AsyncExecutionResponse'
-          links:
-            GetExecutionStatus:
-              operationId: getExecutionStatus
-              parameters:
-                agent_id: '$request.path.agent_id'
-                execution_id: '$response.body#/execution_id'
-        '400':
-          $ref: '#/components/responses/BadRequest'
-        '401':
-          $ref: '#/components/responses/Unauthorized'
-        '403':
-          $ref: '#/components/responses/Forbidden'
-        '404':
-          $ref: '#/components/responses/NotFound'
-        '422':
-          description: Execution validation failed
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ExecutionValidationError'
-        '429':
-          $ref: '#/components/responses/TooManyRequests'
-        '500':
-          $ref: '#/components/responses/InternalServerError'
-
-  /agents/{agent_id}/executions/{execution_id}:
-    parameters:
-      - $ref: '#/components/parameters/AgentIdParam'
-      - $ref: '#/components/parameters/ExecutionIdParam'
-    
-    get:
-      tags: [Agents]
-      summary: Get execution status
-      description: |
-        Retrieve the status and results of an asynchronous execution.
-        
-        Provides:
-        - **Real-time status** (pending, running, completed, failed)
-        - **Progress indicators** with percentage completion
-        - **Intermediate results** for long-running operations
-        - **Resource usage metrics** (CPU, memory, duration)
-        - **Error details** with stack traces and context
-      operationId: getExecutionStatus
-      responses:
-        '200':
-          description: Execution status retrieved successfully
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ExecutionStatus'
-        '404':
-          $ref: '#/components/responses/NotFound'
-        '401':
-          $ref: '#/components/responses/Unauthorized'
-        '403':
-          $ref: '#/components/responses/Forbidden'
-        '500':
-          $ref: '#/components/responses/InternalServerError'
-
-  /specifications:
-    get:
-      tags: [Specifications]
-      summary: List OpenAPI specifications
-      description: |
-        Retrieve all OpenAPI specifications with metadata and validation status.
-        
-        Features:
-        - **Version history** tracking with semantic versioning
-        - **Validation status** against OpenAPI 3.1 schema
-        - **Dependency mapping** between specifications
-        - **Usage analytics** and adoption metrics
-      operationId: listSpecifications
-      parameters:
-        - $ref: '#/components/parameters/PageParam'
-        - $ref: '#/components/parameters/LimitParam'
-        - name: version
-          in: query
-          description: Filter by OpenAPI version
-          schema:
-            type: string
-            enum: ["3.0.0", "3.0.1", "3.0.2", "3.0.3", "3.1.0"]
-        - name: status
-          in: query
-          description: Filter by validation status
-          schema:
-            type: string
-            enum: [valid, invalid, warning, unknown]
-      responses:
-        '200':
-          description: Specifications retrieved successfully
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/SpecificationListResponse'
-        '400':
-          $ref: '#/components/responses/BadRequest'
-        '401':
-          $ref: '#/components/responses/Unauthorized'
-        '500':
-          $ref: '#/components/responses/InternalServerError'
-
-  /specifications/{spec_id}:
-    parameters:
-      - $ref: '#/components/parameters/SpecIdParam'
-    
-    get:
-      tags: [Specifications]
-      summary: Get specification
-      description: Retrieve a specific OpenAPI specification with full content and metadata
-      operationId: getSpecification
-      parameters:
-        - name: format
-          in: query
-          description: Response format
-          schema:
-            type: string
-            enum: [json, yaml]
-            default: json
-      responses:
-        '200':
-          description: Specification retrieved successfully
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/OpenAPISpecification'
-            application/yaml:
-              schema:
-                $ref: '#/components/schemas/OpenAPISpecification'
-        '404':
-          $ref: '#/components/responses/NotFound'
-        '401':
-          $ref: '#/components/responses/Unauthorized'
-        '500':
-          $ref: '#/components/responses/InternalServerError'
-
-# OpenAPI 3.1 Webhooks Feature
-webhooks:
-  agentCreated:
-    post:
-      summary: Agent created notification
-      description: Triggered when a new agent is successfully created
-      requestBody:
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/AgentCreatedEvent'
-      responses:
-        '200':
-          description: Webhook received successfully
-
-  agentStatusChanged:
-    post:
-      summary: Agent status change notification
-      description: Triggered when an agent's status changes
-      requestBody:
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/AgentStatusEvent'
-      responses:
-        '200':
-          description: Webhook received successfully
-
-  executionCompleted:
-    post:
-      summary: Execution completed notification
-      description: Triggered when an agent execution completes
-      requestBody:
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/ExecutionCompletedEvent'
-      responses:
-        '200':
-          description: Webhook received successfully
-
-components:
-  schemas:
-    # Base Agent Schema with Discriminator (OpenAPI 3.1 feature)
-    Agent:
-      type: object
-      discriminator:
-        propertyName: type
-        mapping:
-          worker: '#/components/schemas/WorkerAgent'
-          orchestrator: '#/components/schemas/OrchestratorAgent'
-          critic: '#/components/schemas/CriticAgent'
-          judge: '#/components/schemas/JudgeAgent'
-          monitor: '#/components/schemas/MonitorAgent'
-          governor: '#/components/schemas/GovernorAgent'
-      properties:
-        id:
-          type: string
-          pattern: '^[a-z0-9-]+$'
-          minLength: 3
-          maxLength: 63
-          example: "agent-001"
-          description: Unique agent identifier following DNS naming conventions
-        type:
-          $ref: '#/components/schemas/AgentType'
-        name:
-          type: string
-          minLength: 1
-          maxLength: 255
-          example: "Data Processing Agent"
-          description: Human-readable agent name
-        description:
-          type: string
-          maxLength: 1000
-          example: "Processes incoming data streams with validation and transformation"
-        version:
-          type: string
-          pattern: '^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$'
-          example: "1.2.3"
-          description: Semantic version following SemVer specification
-        status:
-          $ref: '#/components/schemas/AgentStatus'
-        capabilities:
-          type: array
-          items:
-            type: string
-            pattern: '^[a-z0-9-]+$'
-          minItems: 1
-          maxItems: 50
-          uniqueItems: true
-          example: ["data-processing", "validation", "transformation"]
-          description: List of capabilities this agent provides
-        configuration:
-          type: object
-          additionalProperties: true
-          description: Agent-specific configuration parameters
-        metadata:
-          $ref: '#/components/schemas/AgentMetadata'
-        created_at:
-          type: string
-          format: date-time
-          example: "2025-01-15T10:30:00Z"
-          description: Agent creation timestamp in ISO 8601 format
-        updated_at:
-          type: string
-          format: date-time
-          example: "2025-01-15T14:30:00Z"
-          description: Last update timestamp in ISO 8601 format
-        metrics:
-          $ref: '#/components/schemas/AgentMetrics'
-      required:
-        - id
-        - type
-        - name
-        - version
-        - status
-        - capabilities
-        - created_at
-        - updated_at
-
-    # Specialized Agent Types (Polymorphic with discriminator)
-    WorkerAgent:
-      allOf:
-        - $ref: '#/components/schemas/Agent'
-        - type: object
-          properties:
-            type:
-              type: string
-              const: worker
-            configuration:
-              type: object
-              properties:
-                max_concurrent_tasks:
-                  type: integer
-                  minimum: 1
-                  maximum: 100
-                  default: 10
-                timeout_seconds:
-                  type: integer
-                  minimum: 1
-                  maximum: 3600
-                  default: 300
-                retry_attempts:
-                  type: integer
-                  minimum: 0
-                  maximum: 10
-                  default: 3
-              additionalProperties: true
-            specialization:
-              type: string
-              enum: [data-processing, api-integration, file-handling, validation]
-              description: Worker specialization type
-          required:
-            - specialization
-
-    OrchestratorAgent:
-      allOf:
-        - $ref: '#/components/schemas/Agent'
-        - type: object
-          properties:
-            type:
-              type: string
-              const: orchestrator
-            configuration:
-              type: object
-              properties:
-                max_concurrent_workflows:
-                  type: integer
-                  minimum: 1
-                  maximum: 50
-                  default: 5
-                workflow_timeout_minutes:
-                  type: integer
-                  minimum: 1
-                  maximum: 1440
-                  default: 60
-                enable_parallel_execution:
-                  type: boolean
-                  default: true
-              additionalProperties: true
-            managed_agents:
-              type: array
-              items:
-                type: string
-                pattern: '^[a-z0-9-]+$'
-              description: List of agent IDs this orchestrator manages
-
-    CriticAgent:
-      allOf:
-        - $ref: '#/components/schemas/Agent'
-        - type: object
-          properties:
-            type:
-              type: string
-              const: critic
-            configuration:
-              type: object
-              properties:
-                quality_threshold:
-                  type: number
-                  minimum: 0
-                  maximum: 100
-                  default: 80
-                automated_fixes:
-                  type: boolean
-                  default: false
-                review_categories:
-                  type: array
-                  items:
-                    type: string
-                    enum: [code-quality, security, performance, compliance]
-              additionalProperties: true
-
-    JudgeAgent:
-      allOf:
-        - $ref: '#/components/schemas/Agent'
-        - type: object
-          properties:
-            type:
-              type: string
-              const: judge
-            configuration:
-              type: object
-              properties:
-                decision_model:
-                  type: string
-                  enum: [consensus, majority, weighted, ai-assisted]
-                  default: majority
-                confidence_threshold:
-                  type: number
-                  minimum: 0
-                  maximum: 1
-                  default: 0.8
-              additionalProperties: true
-
-    MonitorAgent:
-      allOf:
-        - $ref: '#/components/schemas/Agent'
-        - type: object
-          properties:
-            type:
-              type: string
-              const: monitor
-            configuration:
-              type: object
-              properties:
-                monitoring_interval_seconds:
-                  type: integer
-                  minimum: 1
-                  maximum: 3600
-                  default: 60
-                alert_thresholds:
-                  type: object
-                  properties:
-                    cpu_percent:
-                      type: number
-                      minimum: 0
-                      maximum: 100
-                      default: 80
-                    memory_percent:
-                      type: number
-                      minimum: 0
-                      maximum: 100
-                      default: 80
-                    error_rate_percent:
-                      type: number
-                      minimum: 0
-                      maximum: 100
-                      default: 5
-              additionalProperties: true
-
-    GovernorAgent:
-      allOf:
-        - $ref: '#/components/schemas/Agent'
-        - type: object
-          properties:
-            type:
-              type: string
-              const: governor
-            configuration:
-              type: object
-              properties:
-                policy_enforcement_level:
-                  type: string
-                  enum: [strict, moderate, permissive]
-                  default: strict
-                compliance_frameworks:
-                  type: array
-                  items:
-                    type: string
-                    enum: [ISO42001, NIST-AI-RMF, EU-AI-ACT, SOX, HIPAA]
-              additionalProperties: true
-
-    AgentType:
-      type: string
-      enum: [worker, orchestrator, critic, judge, monitor, governor]
-      description: |
-        Agent type classification:
-        - **worker**: Task execution agents
-        - **orchestrator**: Workflow coordination agents
-        - **critic**: Quality control and review agents
-        - **judge**: Decision-making agents
-        - **monitor**: System observation agents
-        - **governor**: Policy enforcement agents
-
-    AgentStatus:
-      type: string
-      enum: [active, inactive, error, deploying, maintenance, deprecated]
-      description: |
-        Current agent status:
-        - **active**: Agent is running and available
-        - **inactive**: Agent is stopped but can be started
-        - **error**: Agent has encountered an error
-        - **deploying**: Agent is being deployed
-        - **maintenance**: Agent is under maintenance
-        - **deprecated**: Agent is deprecated and should not be used
-
-    AgentMetadata:
-      type: object
-      properties:
-        author:
-          type: string
-          maxLength: 255
-          example: "John Doe <john@example.com>"
-        organization:
-          type: string
-          maxLength: 255
-          example: "Acme Corporation"
-        tags:
-          type: array
-          items:
-            type: string
-            pattern: '^[a-z0-9-]+$'
-          maxItems: 20
-          uniqueItems: true
-          example: ["ml", "data", "production"]
-        documentation_url:
-          type: string
-          format: uri
-          example: "https://docs.example.com/agents/data-processor"
-        source_repository:
-          type: string
-          format: uri
-          example: "https://github.com/example/data-processor-agent"
-        license:
-          type: string
-          example: "MIT"
-        cost_per_execution:
-          type: number
-          minimum: 0
-          description: Cost in USD per execution
-          example: 0.001
-      additionalProperties: true
-
-    AgentMetrics:
-      type: object
-      properties:
-        total_executions:
-          type: integer
-          minimum: 0
-          example: 12543
-        successful_executions:
-          type: integer
-          minimum: 0
-          example: 12123
-        failed_executions:
-          type: integer
-          minimum: 0
-          example: 420
-        average_execution_time_ms:
-          type: number
-          minimum: 0
-          example: 1250.5
-        last_execution_at:
-          type: string
-          format: date-time
-          example: "2025-01-15T14:25:00Z"
-        success_rate_percent:
-          type: number
-          minimum: 0
-          maximum: 100
-          example: 96.65
-        cpu_usage_percent:
-          type: number
-          minimum: 0
-          maximum: 100
-          example: 23.5
-        memory_usage_mb:
-          type: number
-          minimum: 0
-          example: 512.8
-      additionalProperties: false
-
-    # Request/Response Schemas
-    CreateAgentRequest:
-      type: object
-      discriminator:
-        propertyName: type
-        mapping:
-          worker: '#/components/schemas/CreateWorkerAgentRequest'
-          orchestrator: '#/components/schemas/CreateOrchestratorAgentRequest'
-          critic: '#/components/schemas/CreateCriticAgentRequest'
-          judge: '#/components/schemas/CreateJudgeAgentRequest'
-          monitor: '#/components/schemas/CreateMonitorAgentRequest'
-          governor: '#/components/schemas/CreateGovernorAgentRequest'
-      properties:
-        type:
-          $ref: '#/components/schemas/AgentType'
-        name:
-          type: string
-          minLength: 1
-          maxLength: 255
-        description:
-          type: string
-          maxLength: 1000
-        version:
-          type: string
-          pattern: '^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$'
-          default: "1.0.0"
-        capabilities:
-          type: array
-          items:
-            type: string
-            pattern: '^[a-z0-9-]+$'
-          minItems: 1
-          maxItems: 50
-          uniqueItems: true
-        configuration:
-          type: object
-          additionalProperties: true
-        metadata:
-          $ref: '#/components/schemas/AgentMetadata'
-        webhook_url:
-          type: string
-          format: uri
-          description: URL to receive status change notifications
-      required:
-        - type
-        - name
-        - capabilities
-
-    CreateWorkerAgentRequest:
-      allOf:
-        - $ref: '#/components/schemas/CreateAgentRequest'
-        - type: object
-          properties:
-            type:
-              type: string
-              const: worker
-            specialization:
-              type: string
-              enum: [data-processing, api-integration, file-handling, validation]
-            configuration:
-              type: object
-              properties:
-                max_concurrent_tasks:
-                  type: integer
-                  minimum: 1
-                  maximum: 100
-                  default: 10
-                timeout_seconds:
-                  type: integer
-                  minimum: 1
-                  maximum: 3600
-                  default: 300
-              additionalProperties: true
-          required:
-            - specialization
-
-    CreateOrchestratorAgentRequest:
-      allOf:
-        - $ref: '#/components/schemas/CreateAgentRequest'
-        - type: object
-          properties:
-            type:
-              type: string
-              const: orchestrator
-            configuration:
-              type: object
-              properties:
-                max_concurrent_workflows:
-                  type: integer
-                  minimum: 1
-                  maximum: 50
-                  default: 5
-                workflow_timeout_minutes:
-                  type: integer
-                  minimum: 1
-                  maximum: 1440
-                  default: 60
-              additionalProperties: true
-
-    CreateCriticAgentRequest:
-      allOf:
-        - $ref: '#/components/schemas/CreateAgentRequest'
-        - type: object
-          properties:
-            type:
-              type: string
-              const: critic
-            configuration:
-              type: object
-              properties:
-                quality_threshold:
-                  type: number
-                  minimum: 0
-                  maximum: 100
-                  default: 80
-                automated_fixes:
-                  type: boolean
-                  default: false
-              additionalProperties: true
-
-    CreateJudgeAgentRequest:
-      allOf:
-        - $ref: '#/components/schemas/CreateAgentRequest'
-        - type: object
-          properties:
-            type:
-              type: string
-              const: judge
-            configuration:
-              type: object
-              properties:
-                decision_model:
-                  type: string
-                  enum: [consensus, majority, weighted, ai-assisted]
-                  default: majority
-              additionalProperties: true
-
-    CreateMonitorAgentRequest:
-      allOf:
-        - $ref: '#/components/schemas/CreateAgentRequest'
-        - type: object
-          properties:
-            type:
-              type: string
-              const: monitor
-            configuration:
-              type: object
-              properties:
-                monitoring_interval_seconds:
-                  type: integer
-                  minimum: 1
-                  maximum: 3600
-                  default: 60
-              additionalProperties: true
-
-    CreateGovernorAgentRequest:
-      allOf:
-        - $ref: '#/components/schemas/CreateAgentRequest'
-        - type: object
-          properties:
-            type:
-              type: string
-              const: governor
-            configuration:
-              type: object
-              properties:
-                policy_enforcement_level:
-                  type: string
-                  enum: [strict, moderate, permissive]
-                  default: strict
-              additionalProperties: true
-
-    UpdateAgentRequest:
-      type: object
-      properties:
-        name:
-          type: string
-          minLength: 1
-          maxLength: 255
-        description:
-          type: string
-          maxLength: 1000
-        version:
-          type: string
-          pattern: '^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$'
-        capabilities:
-          type: array
-          items:
-            type: string
-            pattern: '^[a-z0-9-]+$'
-          minItems: 1
-          maxItems: 50
-          uniqueItems: true
-        configuration:
-          type: object
-          additionalProperties: true
-        metadata:
-          $ref: '#/components/schemas/AgentMetadata'
-        expected_version:
-          type: string
-          description: Expected current version for optimistic locking
-      minProperties: 1
-
-    AgentListResponse:
-      type: object
-      properties:
-        agents:
-          type: array
-          items:
-            $ref: '#/components/schemas/Agent'
-        pagination:
-          $ref: '#/components/schemas/PaginationInfo'
-        filters:
-          type: object
-          description: Applied filters for this query
-          additionalProperties: true
-      required:
-        - agents
-        - pagination
-
-    PaginationInfo:
-      type: object
-      properties:
-        page:
-          type: integer
-          minimum: 1
-          example: 1
-        limit:
-          type: integer
-          minimum: 1
-          maximum: 100
-          example: 20
-        total:
-          type: integer
-          minimum: 0
-          example: 157
-        has_next:
-          type: boolean
-          example: true
-        has_previous:
-          type: boolean
-          example: false
-      required:
-        - page
-        - limit
-        - total
-        - has_next
-        - has_previous
-
-    # Execution Schemas
-    ExecutionRequest:
-      type: object
-      properties:
-        operation:
-          type: string
-          minLength: 1
-          maxLength: 255
-          example: "process_data"
-          description: Name of the operation to execute
-        input:
-          type: object
-          additionalProperties: true
-          description: Input parameters for the operation
-        context:
-          type: object
-          properties:
-            user_id:
-              type: string
-              example: "user-123"
-            organization_id:
-              type: string
-              example: "org-456"
-            correlation_id:
-              type: string
-              example: "corr-789"
-            trace_id:
-              type: string
-              example: "trace-abc"
-          additionalProperties: true
-          description: Execution context and metadata
-        options:
-          type: object
-          properties:
-            cache_result:
-              type: boolean
-              default: true
-            cache_ttl_seconds:
-              type: integer
-              minimum: 1
-              maximum: 86400
-              default: 3600
-            notify_on_completion:
-              type: boolean
-              default: false
-            retry_on_failure:
-              type: boolean
-              default: true
-          additionalProperties: true
-          description: Execution options and preferences
-      required:
-        - operation
-        - input
-
-    ExecutionResult:
-      type: object
-      properties:
-        execution_id:
-          type: string
-          example: "exec-123"
-        status:
-          type: string
-          enum: [completed, failed]
-        result:
-          type: object
-          additionalProperties: true
-          description: Execution output data
-        error:
-          $ref: '#/components/schemas/ExecutionError'
-        metadata:
-          type: object
-          properties:
-            duration_ms:
-              type: integer
-              minimum: 0
-              example: 1250
-            cpu_time_ms:
-              type: integer
-              minimum: 0
-              example: 950
-            memory_used_mb:
-              type: number
-              minimum: 0
-              example: 128.5
-            cache_hit:
-              type: boolean
-              example: false
-          additionalProperties: true
-        started_at:
-          type: string
-          format: date-time
-        completed_at:
-          type: string
-          format: date-time
-      required:
-        - execution_id
-        - status
-        - started_at
-
-    AsyncExecutionResponse:
-      type: object
-      properties:
-        execution_id:
-          type: string
-          example: "exec-123"
-        status:
-          type: string
-          enum: [pending, running]
-        estimated_duration_seconds:
-          type: integer
-          minimum: 0
-          example: 300
-        progress_url:
-          type: string
-          format: uri
-          example: "https://api.ossa.bluefly.io/v1/agents/agent-001/executions/exec-123"
-        websocket_url:
-          type: string
-          format: uri
-          example: "wss://api.ossa.bluefly.io/v1/agents/agent-001/executions/exec-123/progress"
-        started_at:
-          type: string
-          format: date-time
-      required:
-        - execution_id
-        - status
-        - progress_url
-        - started_at
-
-    ExecutionStatus:
-      type: object
-      properties:
-        execution_id:
-          type: string
-        agent_id:
-          type: string
-        status:
-          type: string
-          enum: [pending, running, completed, failed, cancelled]
-        progress:
-          type: object
-          properties:
-            percentage:
-              type: number
-              minimum: 0
-              maximum: 100
-            current_step:
-              type: string
-            total_steps:
-              type: integer
-              minimum: 1
-            estimated_completion:
-              type: string
-              format: date-time
-        result:
-          type: object
-          additionalProperties: true
-        error:
-          $ref: '#/components/schemas/ExecutionError'
-        logs:
-          type: array
-          items:
-            $ref: '#/components/schemas/ExecutionLogEntry'
-        metadata:
-          type: object
-          additionalProperties: true
-        started_at:
-          type: string
-          format: date-time
-        completed_at:
-          type: string
-          format: date-time
-      required:
-        - execution_id
-        - agent_id
-        - status
-        - started_at
-
-    ExecutionError:
-      type: object
-      properties:
-        code:
-          type: string
-          example: "VALIDATION_FAILED"
-        message:
-          type: string
-          example: "Input validation failed for required field 'data_source'"
-        details:
-          type: object
-          additionalProperties: true
-        stack_trace:
-          type: string
-          description: Stack trace for debugging (only in development mode)
-        correlation_id:
-          type: string
-          example: "corr-789"
-      required:
-        - code
-        - message
-
-    ExecutionLogEntry:
-      type: object
-      properties:
-        timestamp:
-          type: string
-          format: date-time
-        level:
-          type: string
-          enum: [debug, info, warn, error]
-        message:
-          type: string
-        data:
-          type: object
-          additionalProperties: true
-      required:
-        - timestamp
-        - level
-        - message
-
-    ExecutionValidationError:
-      type: object
-      properties:
-        error:
-          type: string
-          example: "Execution validation failed"
-        validation_errors:
-          type: array
-          items:
-            type: object
-            properties:
-              field:
-                type: string
-                example: "input.data_source"
-              code:
-                type: string
-                example: "REQUIRED"
-              message:
-                type: string
-                example: "Field is required"
-              value:
-                description: The invalid value that was provided
-        operation:
-          type: string
-          example: "process_data"
-        agent_capabilities:
-          type: array
-          items:
-            type: string
-          example: ["data-processing", "validation"]
-      required:
-        - error
-        - validation_errors
-
-    # JSON Patch Operations (OpenAPI 3.1 feature)
-    JsonPatchOperation:
-      type: object
-      properties:
-        op:
-          type: string
-          enum: [add, remove, replace, move, copy, test]
-        path:
-          type: string
-          pattern: '^(/[^/~]*(~[01][^/~]*)*)*$'
-          description: JSON Pointer path
-        value:
-          description: Value for add, replace, and test operations
-        from:
-          type: string
-          pattern: '^(/[^/~]*(~[01][^/~]*)*)*$'
-          description: Source path for move and copy operations
-      required:
-        - op
-        - path
-      if:
-        properties:
-          op:
-            enum: [add, replace, test]
-      then:
-        required:
-          - value
-      else:
-        if:
-          properties:
-            op:
-              enum: [move, copy]
-        then:
-          required:
-            - from
-
-    # OpenAPI Specification Schemas
-    OpenAPISpecification:
-      type: object
-      properties:
-        id:
-          type: string
-          pattern: '^[a-z0-9-]+$'
-          example: "user-api"
-        name:
-          type: string
-          example: "User Management API"
-        description:
-          type: string
-          example: "API for managing user accounts and profiles"
-        content:
-          type: object
-          description: The actual OpenAPI specification content
-          additionalProperties: true
-        validation_status:
-          type: string
-          enum: [valid, invalid, warning, unknown]
-        validation_errors:
-          type: array
-          items:
-            type: object
-            properties:
-              path:
-                type: string
-              message:
-                type: string
-              severity:
-                type: string
-                enum: [error, warning, info]
-        version:
-          type: string
-          example: "3.1.0"
-        created_at:
-          type: string
-          format: date-time
-        updated_at:
-          type: string
-          format: date-time
-      required:
-        - id
-        - name
-        - content
-        - validation_status
-        - version
-        - created_at
-        - updated_at
-
-    SpecificationListResponse:
-      type: object
-      properties:
-        specifications:
-          type: array
-          items:
-            $ref: '#/components/schemas/OpenAPISpecification'
-        pagination:
-          $ref: '#/components/schemas/PaginationInfo'
-      required:
-        - specifications
-        - pagination
-
-    # Event Schemas for Webhooks
-    AgentCreatedEvent:
-      type: object
-      properties:
-        event_type:
-          type: string
-          const: agent.created
-        event_id:
-          type: string
-          format: uuid
-        timestamp:
-          type: string
-          format: date-time
-        agent:
-          $ref: '#/components/schemas/Agent'
-        organization_id:
-          type: string
-        user_id:
-          type: string
-      required:
-        - event_type
-        - event_id
-        - timestamp
-        - agent
-
-    AgentStatusEvent:
-      type: object
-      properties:
-        event_type:
-          type: string
-          const: agent.status_changed
-        event_id:
-          type: string
-          format: uuid
-        timestamp:
-          type: string
-          format: date-time
-        agent_id:
-          type: string
-        previous_status:
-          $ref: '#/components/schemas/AgentStatus'
-        new_status:
-          $ref: '#/components/schemas/AgentStatus'
-        reason:
-          type: string
-          description: Reason for status change
-        organization_id:
-          type: string
-        user_id:
-          type: string
-      required:
-        - event_type
-        - event_id
-        - timestamp
-        - agent_id
-        - previous_status
-        - new_status
-
-    ExecutionCompletedEvent:
-      type: object
-      properties:
-        event_type:
-          type: string
-          const: execution.completed
-        event_id:
-          type: string
-          format: uuid
-        timestamp:
-          type: string
-          format: date-time
-        execution_id:
-          type: string
-        agent_id:
-          type: string
-        status:
-          type: string
-          enum: [completed, failed]
-        duration_ms:
-          type: integer
-          minimum: 0
-        result:
-          type: object
-          additionalProperties: true
-        error:
-          $ref: '#/components/schemas/ExecutionError'
-        organization_id:
-          type: string
-        user_id:
-          type: string
-      required:
-        - event_type
-        - event_id
-        - timestamp
-        - execution_id
-        - agent_id
-        - status
-        - duration_ms
-
-    # Error Schemas
-    ErrorResponse:
-      type: object
-      properties:
-        error:
-          type: string
-          description: Error type/code
-        message:
-          type: string
-          description: Human-readable error message
-        details:
-          type: object
-          additionalProperties: true
-          description: Additional error details
-        correlation_id:
-          type: string
-          description: Unique identifier for this error instance
-        timestamp:
-          type: string
-          format: date-time
-        path:
-          type: string
-          description: API path where error occurred
-      required:
-        - error
-        - message
-        - correlation_id
-        - timestamp
-
-    ValidationError:
-      allOf:
-        - $ref: '#/components/schemas/ErrorResponse'
-        - type: object
-          properties:
-            validation_errors:
-              type: array
-              items:
-                type: object
-                properties:
-                  field:
-                    type: string
-                    description: Field that failed validation
-                  code:
-                    type: string
-                    description: Validation error code
-                  message:
-                    type: string
-                    description: Field-specific error message
-                  value:
-                    description: The invalid value
-                required:
-                  - field
-                  - code
-                  - message
-
-    ConflictError:
-      allOf:
-        - $ref: '#/components/schemas/ErrorResponse'
-        - type: object
-          properties:
-            conflicting_resource:
-              type: object
-              properties:
-                type:
-                  type: string
-                  example: "agent"
-                id:
-                  type: string
-                  example: "agent-001"
-                name:
-                  type: string
-                  example: "Existing Agent"
-
-    PatchError:
-      allOf:
-        - $ref: '#/components/schemas/ErrorResponse'
-        - type: object
-          properties:
-            failed_operations:
-              type: array
-              items:
-                type: object
-                properties:
-                  operation_index:
-                    type: integer
-                    minimum: 0
-                  operation:
-                    $ref: '#/components/schemas/JsonPatchOperation'
-                  error:
-                    type: string
-
-  # Reusable Examples
-  examples:
-    WorkerAgentExample:
-      summary: Example worker agent
-      value:
-        id: "worker-001"
-        type: "worker"
-        name: "Data Processing Worker"
-        description: "Processes incoming data streams with validation and transformation"
-        version: "1.2.3"
-        status: "active"
-        capabilities: ["data-processing", "validation", "transformation"]
-        configuration:
-          max_concurrent_tasks: 10
-          timeout_seconds: 300
-          retry_attempts: 3
-        specialization: "data-processing"
-        metadata:
-          author: "John Doe <john@example.com>"
-          organization: "Acme Corporation"
-          tags: ["ml", "data", "production"]
-          license: "MIT"
-        created_at: "2025-01-15T10:30:00Z"
-        updated_at: "2025-01-15T14:30:00Z"
-        metrics:
-          total_executions: 12543
-          successful_executions: 12123
-          failed_executions: 420
-          success_rate_percent: 96.65
-          average_execution_time_ms: 1250.5
-
-    OrchestratorAgentExample:
-      summary: Example orchestrator agent
-      value:
-        id: "orch-001"
-        type: "orchestrator"
-        name: "Workflow Orchestrator"
-        description: "Manages complex multi-step workflows with parallel execution"
-        version: "2.1.0"
-        status: "active"
-        capabilities: ["orchestration", "workflow-management", "monitoring"]
-        configuration:
-          max_concurrent_workflows: 5
-          workflow_timeout_minutes: 60
-          enable_parallel_execution: true
-        managed_agents: ["worker-001", "worker-002", "critic-001"]
-        metadata:
-          author: "Jane Smith <jane@example.com>"
-          organization: "Acme Corporation"
-          tags: ["orchestration", "workflow", "production"]
-          license: "MIT"
-        created_at: "2025-01-15T09:00:00Z"
-        updated_at: "2025-01-15T15:00:00Z"
-        metrics:
-          total_executions: 3421
-          successful_executions: 3398
-          failed_executions: 23
-          success_rate_percent: 99.33
-          average_execution_time_ms: 5420.8
-
-  # Reusable Parameters
-  parameters:
-    AgentIdParam:
-      name: agent_id
-      in: path
-      required: true
-      description: Unique identifier for the agent
-      schema:
-        type: string
-        pattern: '^[a-z0-9-]+$'
-        minLength: 3
-        maxLength: 63
-      example: "agent-001"
-
-    ExecutionIdParam:
-      name: execution_id
-      in: path
-      required: true
-      description: Unique identifier for the execution
-      schema:
-        type: string
-        pattern: '^exec-[a-z0-9-]+$'
-      example: "exec-123"
-
-    SpecIdParam:
-      name: spec_id
-      in: path
-      required: true
-      description: Unique identifier for the specification
-      schema:
-        type: string
-        pattern: '^[a-z0-9-]+$'
-      example: "user-api"
-
-    PageParam:
-      name: page
-      in: query
-      description: Page number for pagination (1-based)
-      schema:
-        type: integer
-        minimum: 1
-        default: 1
-      example: 1
-
-    LimitParam:
-      name: limit
-      in: query
-      description: Number of items per page
-      schema:
-        type: integer
-        minimum: 1
-        maximum: 100
-        default: 20
-      example: 20
-
-    SortParam:
-      name: sort
-      in: query
-      description: Sort order for results
-      schema:
-        type: string
-        enum: [created_at, updated_at, name, status, type]
-        default: created_at
-      example: "name"
-
-  # Reusable Responses
-  responses:
-    BadRequest:
-      description: Bad request - invalid input parameters
-      content:
-        application/json:
-          schema:
-            $ref: '#/components/schemas/ErrorResponse'
-          example:
-            error: "BAD_REQUEST"
-            message: "Invalid input parameters provided"
-            correlation_id: "corr-123"
-            timestamp: "2025-01-15T14:30:00Z"
-            path: "/v1/agents"
-
-    Unauthorized:
-      description: Unauthorized - authentication required
-      content:
-        application/json:
-          schema:
-            $ref: '#/components/schemas/ErrorResponse'
-          example:
-            error: "UNAUTHORIZED"
-            message: "Authentication credentials are required"
-            correlation_id: "corr-124"
-            timestamp: "2025-01-15T14:30:00Z"
-
-    Forbidden:
-      description: Forbidden - insufficient permissions
-      content:
-        application/json:
-          schema:
-            $ref: '#/components/schemas/ErrorResponse'
-          example:
-            error: "FORBIDDEN"
-            message: "Insufficient permissions to perform this operation"
-            correlation_id: "corr-125"
-            timestamp: "2025-01-15T14:30:00Z"
-
-    NotFound:
-      description: Resource not found
-      content:
-        application/json:
-          schema:
-            $ref: '#/components/schemas/ErrorResponse'
-          example:
-            error: "NOT_FOUND"
-            message: "The requested resource was not found"
-            correlation_id: "corr-126"
-            timestamp: "2025-01-15T14:30:00Z"
-
-    ValidationError:
-      description: Validation failed
-      content:
-        application/json:
-          schema:
-            $ref: '#/components/schemas/ValidationError'
-
-    TooManyRequests:
-      description: Too many requests - rate limit exceeded
-      content:
-        application/json:
-          schema:
-            $ref: '#/components/schemas/ErrorResponse'
-          example:
-            error: "TOO_MANY_REQUESTS"
-            message: "Rate limit exceeded. Please try again later."
-            correlation_id: "corr-127"
-            timestamp: "2025-01-15T14:30:00Z"
-      headers:
-        X-RateLimit-Limit:
-          schema:
-            type: integer
-          description: The rate limit ceiling for that given request
-        X-RateLimit-Remaining:
-          schema:
-            type: integer
-          description: The number of requests left for the time window
-        X-RateLimit-Reset:
-          schema:
-            type: integer
-          description: The time at which the rate limit resets (Unix timestamp)
-
-    InternalServerError:
-      description: Internal server error
-      content:
-        application/json:
-          schema:
-            $ref: '#/components/schemas/ErrorResponse'
-          example:
-            error: "INTERNAL_SERVER_ERROR"
-            message: "An unexpected error occurred. Please try again later."
-            correlation_id: "corr-128"
-            timestamp: "2025-01-15T14:30:00Z"
-
-  # Security Schemes (OpenAPI 3.1 OAuth 2.1 support)
-  securitySchemes:
-    OAuth2:
-      type: oauth2
-      description: |
-        OAuth 2.1 with PKCE for secure authentication.
-        
-        Supported flows:
-        - **Authorization Code with PKCE**: For web and mobile applications
-        - **Client Credentials**: For service-to-service communication
-        
-        Required scopes:
-        - `agents:read`: Read access to agents
-        - `agents:write`: Create and update agents
-        - `agents:delete`: Delete agents
-        - `agents:execute`: Execute agent operations
-        - `specifications:read`: Read access to specifications
-        - `specifications:write`: Create and update specifications
-        - `admin`: Full administrative access
-      flows:
-        authorizationCode:
-          authorizationUrl: https://auth.ossa.bluefly.io/oauth/authorize
-          tokenUrl: https://auth.ossa.bluefly.io/oauth/token
-          refreshUrl: https://auth.ossa.bluefly.io/oauth/refresh
-          scopes:
-            agents:read: Read access to agents
-            agents:write: Create and update agents
-            agents:delete: Delete agents
-            agents:execute: Execute agent operations
-            specifications:read: Read access to specifications
-            specifications:write: Create and update specifications
-            admin: Full administrative access
-        clientCredentials:
-          tokenUrl: https://auth.ossa.bluefly.io/oauth/token
-          scopes:
-            agents:read: Read access to agents
-            agents:write: Create and update agents
-            agents:delete: Delete agents
-            agents:execute: Execute agent operations
-            specifications:read: Read access to specifications
-            specifications:write: Create and update specifications
-            admin: Full administrative access
-
-    ApiKey:
-      type: apiKey
-      in: header
-      name: X-API-Key
-      description: |
-        API key authentication for service-to-service communication.
-        
-        Include your API key in the `X-API-Key` header:
-        ```
-        X-API-Key: ossa_ak_1234567890abcdef
-        ```
-        
-        API keys can be managed in the OSSA dashboard and have configurable
-        permissions and rate limits.
-
-    BearerAuth:
-      type: http
-      scheme: bearer
-      bearerFormat: JWT
-      description: |
-        JWT Bearer token authentication.
-        
-        Include your JWT token in the Authorization header:
-        ```
-        Authorization: Bearer <your-jwt-token>
-        ```
-        
-        JWT tokens are obtained through the OAuth 2.1 flow and contain
-        user identity and scope information.
-
-# Global Security Requirements
-security:
-  - OAuth2: [agents:read]
-  - ApiKey: []
-  - BearerAuth: []