@bluefly/openstandardagents 0.1.9

package/src/api/ossa-complete.openapi.yml

@@ -0,0 +1,2250 @@
+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: []