Créer un outil d'accessibilité IA avec Optimizely Opal

C'est exactement ce que vous pouvez bâtir avec l'architecture d'outils personnalisés d'Optimizely Opal.

Ce guide sur l'assistant d'accessibilité Optimizely Opal vous accompagne dans la création d'un assistant qui exécute des analyses axe-core directement depuis Opal Chat, retourne des résultats priorisés et peut même générer des suggestions de correction grâce à l'IA. Cette approche permet l'automatisation des tests d'accessibilité dans les flux de travail CMS pour détecter les problèmes avant la mise en ligne.

Prérequis

Avant de commencer, assurez-vous d'avoir :

• Optimizely CMS avec Opal activé (requiert l'authentification Opti ID)
• Les fonctionnalités d'IA générative activées dans votre instance Optimizely
• Un accès administrateur au panneau de configuration Opal
• Un environnement d'hébergement accessible publiquement pour votre service d'outils (ou un accès à Optimizely Connect Platform pour l'hébergement géré)
• Node.js 18 , Python 3.9 ou .NET 6 selon votre SDK préféré

Vous aurez également besoin d'une compréhension des concepts de base des API REST et d'une familiarité avec les outils de test d'accessibilité comme axe-core.

Notre expérience démontre que les équipes sous-estiment souvent l'exigence d'hébergement. Votre service d'outils doit être accessible depuis l'infrastructure d'Optimizely, ce qui signifie soit une URL publique avec SSL approprié, soit un déploiement via OCP.

Comprendre l'architecture

Le système d'outils personnalisés d'Opal fonctionne sur un principe simple : vous construisez un service qui expose ses capacités via un point de terminaison `/discovery`, et Opal appelle votre service quand les utilisateurs demandent ces fonctionnalités.

Pour un assistant d'accessibilité, vous aurez généralement besoin de plusieurs outils travaillant ensemble :

• scan_url - Exécuter axe-core sur une seule page
• scan_sitemap - Auditer plusieurs pages à partir d'un sitemap
• explain_issue - Utiliser l'IA pour expliquer une violation d'accessibilité
• suggest_fix - Générer des suggestions de code pour la correction
• email_report - Formater et envoyer les résultats aux parties prenantes

Ces outils peuvent fonctionner indépendamment, mais la vraie puissance vient de leur intégration dans un Agent Opal qui interprète l'intention de l'utilisateur et appelle les bons outils en séquence.

Implémentation étape par étape

Étape 1 : Choisir votre SDK d'outils personnalisés Opal et configurer le projet

Optimizely fournit des SDK officiels pour trois plateformes :

Python (idéal pour les charges de travail intensives en données ou ML) :

pip install opal-tools-sdk

.NET (idéal pour les backends d'entreprise avec exigences de faible latence) :

dotnet add package Optimizely.Opal.Tools

Node.js/OCP (idéal pour le travail API intensif en I/O) :

npm install @optimizely-opal/opal-tool-ocp-sdk

Pour ce guide, nous utiliserons Python avec FastAPI puisque les intégrations axe-core sont simples via Playwright ou Selenium.

Étape 2 : Créer le point de terminaison Discovery d'Opal

Le point de terminaison `/discovery` indique à Opal ce que votre service peut faire. Voici une structure de base :

from fastapi import FastAPI
from opal_tools_sdk import OpalToolsSDK, Tool, Parameter

app = FastAPI()
sdk = OpalToolsSDK()

@sdk.tool(
    name="scan_url",
    description="Run an accessibility scan on a single URL and return WCAG 2.1 AA violations",
    parameters=[
        Parameter(
            name="url",
            type="string",
            description="The full URL to scan",
            required=True
        )
    ]
)
async def scan_url(url: str):
    # Implementation goes here
    pass

app.include_router(sdk.router)

Le SDK génère automatiquement votre point de terminaison `/discovery` basé sur les fonctions décorées. Quand Opal interroge ce point de terminaison, il reçoit un manifeste décrivant chaque outil, ses paramètres et comment l'appeler.

Étape 3 : Implémenter le scanner d'accessibilité avec l'intégration axe-core Optimizely

La logique de scan utilise axe-core via un navigateur headless. Voici une implémentation simplifiée utilisant les capacités de scan d'accessibilité de Playwright :

from playwright.async_api import async_playwright

async def run_axe_scan(url: str) -> dict:
    async with async_playwright() as p:
        browser = await p.chromium.launch()
        page = await browser.new_page()
        
        await page.goto(url, wait_until="networkidle")
        
        # Inject axe-core
        await page.add_script_tag(
            url="https://cdnjs.cloudflare.com/ajax/libs/axe-core/4.8.2/axe.min.js"
        )
        
        # Run the scan
        results = await page.evaluate("axe.run()")
        
        await browser.close()
        
        return {
            "url": url,
            "violations": results["violations"],
            "passes": len(results["passes"]),
            "incomplete": len(results["incomplete"])
        }

Ceci vous donne la sortie brute d'axe-core. L'étape suivante est de la formater pour Opal.

Étape 4 : Formater les résultats pour votre outil de conformité WCAG Optimizely

Opal affiche les réponses des outils dans le clavardage, alors structurez votre sortie pour la lisibilité :

@sdk.tool(
    name="scan_url",
    description="Run an accessibility scan on a single URL",
    parameters=[
        Parameter(name="url", type="string", required=True)
    ]
)
async def scan_url(url: str):
    results = await run_axe_scan(url)
    
    if not results["violations"]:
        return {
            "summary": f"No WCAG 2.1 AA violations found on {url}",
            "passes": results["passes"]
        }
    
    # Group by severity
    critical = [v for v in results["violations"] if v["impact"] == "critical"]
    serious = [v for v in results["violations"] if v["impact"] == "serious"]
    moderate = [v for v in results["violations"] if v["impact"] == "moderate"]
    
    return {
        "summary": f"Found {len(results['violations'])} violations on {url}",
        "critical": format_violations(critical),
        "serious": format_violations(serious),
        "moderate": format_violations(moderate),
        "recommendation": "Address critical and serious issues first"
    }

Étape 5 : Ajouter des explications propulsées par l'IA

C'est ici qu'Opal brille. Vous pouvez créer un outil séparé qui prend une violation et génère une explication en langage simple. Cette capacité de correction d'accessibilité par IA aide les utilisateurs non techniques à comprendre les problèmes :

@sdk.tool(
    name="explain_issue",
    description="Explain an accessibility violation in plain terms",
    parameters=[
        Parameter(name="violation_id", type="string", required=True),
        Parameter(name="context", type="string", required=False)
    ]
)
async def explain_issue(violation_id: str, context: str = ""):
    # Return structured data that Opal can use with its AI
    return {
        "violation": violation_id,
        "explanation_prompt": f"Explain the WCAG violation '{violation_id}' to a content editor. Context: {context}",
        "suggested_action": get_remediation_template(violation_id)
    }

Nous recommandons de garder les suggestions de correction générées par l'IA comme recommandations plutôt que de les appliquer automatiquement. Les patrons ARIA et les structures de titres nécessitent un jugement humain pour être bien implémentés.

Étape 6 : Enregistrer votre outil personnalisé Optimizely Opal

Une fois votre service déployé et accessible publiquement :

• Connectez-vous à Optimizely et ouvrez le panneau d'administration Opal
• Naviguez vers Outils > Ajouter un outil personnalisé
• Entrez votre URL de découverte (ex. : `https://votre-service.com/discovery`)
• Ajoutez l'authentification si nécessaire (jeton bearer ou OAuth)
• Testez la connexion

Opal récupérera votre manifeste et rendra vos outils disponibles dans le clavardage.

Étape 7 : Tutoriel Agent Opal - Créer un agent d'accessibilité

Les outils sont utiles seuls, mais un Agent les lie ensemble avec un comportement cohérent. Dans l'admin Opal :

• Allez à Agents > Créer un agent
• Nommez-le « Assistant d'accessibilité »
• Ajoutez des instructions comme :

You help editors check content accessibility before publishing. When a user asks 
you to check a page, use the scan_url tool first. If violations are found, 
offer to explain any issues they don't understand using explain_issue. 
Always prioritize critical and serious issues in your summary.

• Assignez les outils que vous avez créés
• Sauvegardez et activez l'agent

Maintenant, les éditeurs peuvent simplement taper « vérifier l'accessibilité de [URL] » dans Opal Chat. Ceci permet les tests d'accessibilité avant publication dans le cadre du flux de travail éditorial standard.

Erreurs courantes à éviter

Le travail avec les équipes nous a appris que la plupart des problèmes d'outils Opal tombent dans quelques catégories :

Point de terminaison discovery non accessible : Votre service doit répondre aux requêtes HTTPS depuis l'infrastructure d'Optimizely. Les URL de développement local ne fonctionneront pas. Utilisez ngrok pour les tests ou déployez dans un environnement de staging.

Manifestes malformés : Si la réponse discovery générée par le SDK est modifiée manuellement, de petites erreurs JSON peuvent briser l'enregistrement. Restez avec les helpers du SDK à moins d'avoir une raison spécifique de personnaliser.

Conflits de noms d'outils : Si vous enregistrez plusieurs services d'outils, chaque nom d'outil doit être unique à travers tous les services. Préfixez les noms d'outils avec l'identifiant de votre service (ex. : `a11y_scan_url` au lieu de `scan_url`).

Problèmes de CORS : Si vous hébergez vous-même, configurez CORS pour permettre les requêtes des domaines Optimizely. L'hébergement Optimizely Connect Platform gère ceci automatiquement pour les outils hébergés sur OCP.

Problèmes de délai d'attente : Les scans d'accessibilité peuvent prendre 10-30 secondes pour les pages complexes. Assurez-vous que votre outil gère les délais d'attente gracieusement et retourne des résultats partiels si nécessaire.

Tests et vérification

Avant de déployer aux éditeurs, vérifiez votre implémentation :

• Testez le point de terminaison discovery directement : `curl https://votre-service.com/discovery` devrait retourner du JSON valide avec vos définitions d'outils
• Testez l'exécution des outils : Appelez votre point de terminaison de scan avec une URL connue et vérifiez le format de réponse
• Testez dans Opal Chat : Demandez à l'assistant de scanner une page simple, puis une complexe
• Vérifiez le comportement de l'agent : Essayez des requêtes ambiguës comme « est-ce que cette page est accessible? » pour voir comment l'agent interprète l'intention
• Testez la gestion des erreurs : Scannez une URL invalide et confirmez que votre outil retourne un message d'erreur utile plutôt que d'échouer silencieusement

Exécutez ces tests contre des pages avec des problèmes d'accessibilité connus pour confirmer que les violations sont détectées correctement.

Conclusion

Bâtir un assistant d'accessibilité avec Opal signifie que les éditeurs et les équipes QA peuvent détecter les problèmes plus tôt, directement dans leur flux de travail de contenu. La combinaison du moteur de scan fiable d'axe-core et des capacités IA d'Opal crée un outil qui est à la fois techniquement précis et accessible pour les utilisateurs non techniques.

Les éléments clés sont simples : un point de terminaison discovery, une ou plusieurs implémentations d'outils, et un agent pour les lier ensemble. Les SDK gèrent la plupart du code générique, vous permettant de vous concentrer sur la logique d'accessibilité elle-même.

Si vous planifiez implémenter ce patron dans votre environnement Optimizely, nous pouvons vous aider à concevoir l'architecture des outils et la configuration de l'agent pour correspondre au flux de travail de publication de votre équipe. Contactez-nous pour discuter de comment l'outillage d'accessibilité s'intègre dans vos opérations de contenu.