Créer une Config

Tu utilises une skill qui te guidera dans la création d'une config dans LaunchDarkly. Ton rôle est de comprendre le cas d'usage, de choisir le bon mode, de créer la config et ses variations, et de vérifier que tout est configuré correctement.

⚠️ Cette skill crée une config — elle ne la rend pas servable. Une config nouvellement créée a son fallthrough pointant sur une variation désactivée auto-générée, pas sur la variation que tu viens de créer. Le SDK retournera ai_config.enabled=False à chaque évaluation jusqu'à ce que tu actives le ciblage et que tu pointes le fallthrough sur ta nouvelle variation. Ce n'est pas un bug — c'est l'état par défaut. Tu dois exécuter /configs-targeting (ou l'appel REST / CLI équivalent montré à l'Étape 5) avant de vérifier par rapport au SDK, sinon la vérification ressemblera à un chemin servi par LD cassé alors qu'il ne l'est pas. Le mode de défaillance le plus courant que les utilisateurs rencontrent avec cette skill est de sauter l'étape de ciblage et de passer du temps à déboguer enabled=False dans leur code applicatif.

Prérequis

Cette skill nécessite que le serveur MCP LaunchDarkly hébergé à distance soit configuré dans ton environnement.

Outil MCP principal :

• setup-ai-config -- crée une config avec sa première variation en une seule étape (recommandé)

Outils MCP alternatifs (pour plus de contrôle) :

• create-ai-config -- crée juste la coque de config (key, name, mode)
• create-ai-config-variation -- ajoute une variation avec modèle, prompts et paramètres
• get-ai-config -- vérifie que la config a été créée correctement

Outils MCP optionnels (améliorent le workflow) :

• list-ai-configs -- parcourt les configs existantes pour comprendre les conventions de nommage
• create-project -- crée un projet s'il n'existe pas encore

Important : Biais Vers l'Action

Quand l'utilisateur fournit suffisamment de contexte (cas d'usage, modèle, mode), procède à travers tout le workflow sans t'arrêter pour demander des détails que tu peux inférer. Utilise des valeurs par défaut raisonnables pour les champs non spécifiés : default pour la clé de variation, le cas d'usage comme base pour les instructions/messages, kebab-case pour les clés de config. Complète toutes les étapes (création + vérification) en une seule passe.

Workflow

Étape 1 : Comprendre le Cas d'Usage

Avant de créer, identifie ce que tu construis :

• Quel framework ? LangGraph, LangChain, CrewAI, Strands, OpenAI SDK, Anthropic SDK, personnalisé
• De quoi l'agent a-t-il besoin ? Juste de la génération de texte, ou d'outils/function calling ?
• Agent ou completion ? Voir la matrice de décision ci-dessous

Étape 2 : Choisir le Mode Agent vs Completion

Ce choix porte sur le schéma d'entrée et la compatibilité framework, pas sur le comportement d'exécution. Le mode agent retourne une chaîne instructions ; le mode completion retourne un tableau messages. Les deux fournissent l'abstraction de fournisseur, les tests A/B et le suivi des métriques.

Les deux modes supportent les tools. Tous les modèles ne supportent pas le mode agent -- vérifie la compatibilité du modèle si tu utilises le mode agent. En cas de doute, commence par le mode completion (c'est la valeur par défaut de l'API et c'est plus flexible).

Étape 3 : Créer la Config (Recommandé : Une Seule Étape)

Utilise setup-ai-config pour créer la config et sa première variation en un seul appel. C'est l'approche recommandée : elle gère la création, la configuration de variation et la vérification automatiquement.

Champs de config :

• key -- identifiant unique (minuscules, tirets)
• name -- nom lisible par l'homme
• mode -- "agent" ou "completion"
• Optionnel : description, tags

Champs de variation :

• variationKey, variationName -- identifiants pour la première variation
• modelConfigKey -- doit être au format Provider.model-id (p. ex. OpenAI.gpt-4o, Anthropic.claude-sonnet-4-5)
• modelName -- l'identifiant du modèle (p. ex. gpt-4o). Passe toujours ceci dans l'appel initial — l'omettre produit une variation qui affiche "NO MODEL" et force une seconde requête PATCH pour la définir. Le champ est modelName ; ce n'est pas name ou model.name sur cet endpoint.

Pour le mode agent, fournis :

• instructions -- une chaîne avec les instructions système de l'agent

Exemple d'appel en mode agent :

{
  "projectKey": "my-project", "key": "support-agent", "name": "Support Agent",
  "mode": "agent", "variationKey": "default", "variationName": "Default",
  "modelConfigKey": "OpenAI.gpt-4o", "modelName": "gpt-4o",
  "instructions": "You are a customer support agent. Help users resolve their issues."
}

Pour le mode completion, fournis :

• messages -- un tableau d'objets {role, content} (system, user, assistant)

Exemple d'appel en mode completion :

{
  "projectKey": "my-project", "key": "product-descriptions", "name": "Product Descriptions",
  "mode": "completion", "variationKey": "default", "variationName": "Default",
  "modelConfigKey": "Anthropic.claude-sonnet-4-5", "modelName": "claude-sonnet-4-5",
  "messages": [
    {"role": "system", "content": "You are a product copywriter. Write compelling descriptions."},
    {"role": "user", "content": "Write a description for: {{product_name}}"}
  ]
}

Optionnel :

• parameters -- paramètres du modèle comme {temperature: 0.7, max_tokens: 2000} (respecte les clés snake_case de l'UI)

L'outil retourne le détail complet de la config vérifiée avec la variation attachée.

Étape 3 (Alternative) : Création en Deux Étapes

Si l'utilisateur demande plus de contrôle ou une approche étape par étape, utilise les outils individuels :

1. create-ai-config -- crée la coque de config
2. create-ai-config-variation -- ajoute la variation avec modèle, prompts et paramètres
3. get-ai-config -- vérifie le résultat

Exécute les trois étapes sans t'arrêter pour demander des détails. Déduis la clé de variation (default), le nom (Default), les instructions/messages et le modèle du contexte de la demande de l'utilisateur. Si l'utilisateur a demandé le mode agent GPT-4o, tu as assez pour compléter tout le flux. Pose des questions de clarification seulement si le mode ou le modèle est vraiment ambigu.

Étape 4 : Vérifier

Si tu as utilisé setup-ai-config, la vérification est automatique : la réponse inclut la config complète avec les variations. Vérifie :

1. La config existe avec le bon mode
2. La variation a un modèle assigné (pas "NO MODEL")
3. Les instructions ou messages sont présents
4. Les paramètres sont définis

Utilise get-ai-config pour l'appel de vérification — ne bascule pas à du curl + jq brut. L'outil MCP retourne un objet typé que tu peux inspecter directement. Les filtres jq manuels contre la réponse REST cassent régulièrement : l'endpoint détail des configs retourne la liste de variations sous des clés différentes selon expand, et un filtre comme .variations.items[] échouera avec Cannot index array with string "items" quand la forme de réponse est un tableau nu. Si tu dois appeler l'API REST, utilise d'abord jq -e . pour inspecter la forme réelle avant de creuser.

Rapporte les résultats :

• Config créée avec la bonne structure
• La variation a un modèle assigné
• Signale tout modèle ou paramètre manquant
• Fournis l'URL de la config : https://app.launchdarkly.com/projects/{projectKey}/ai-configs/{configKey}

Étape 5 : Rendre la variation servable

setup-ai-config et create-ai-config-variation créent la variation mais ne la promeuvent pas en fallthrough. La nouvelle config retournera enabled=False à chaque consommateur jusqu'à ce que le ciblage soit mis à jour. C'est le cas de "j'ai créé une config mais mon SDK reçoit toujours le fallback" le plus courant. Le workflow n'est pas complet jusqu'à cette étape.

Ce qu'il faut dire à l'utilisateur

Imprime cette checklist textuellement à l'utilisateur après l'Étape 4, puis attends la confirmation. Ne déclare pas que la skill a réussi jusqu'à ce que l'utilisateur confirme que le fallthrough a été basculé.

✅ Config et variation sont créées.

🔴 Le SDK retournera enabled=False jusqu'à ce que tu actives le ciblage. Le fallthrough pointe actuellement sur une variation désactivée auto-générée, pas sur la {variationKey} que tu viens de créer.

Prochaine étape — exécute /configs-targeting avec ces entrées :

• Clé de projet : {projectKey}
• Clé de config : {configKey}
• Clé d'environnement : l'env dont la clé SDK est dans ton .env (généralement test ou production)
• Variation de fallthrough : {variationKey} (celle que cette skill vient de créer)

Vérifie après que le ciblage a été basculé en :

1. Ouvrant la config dans l'UI LD, basculant vers le bon environnement et confirmant que "Default rule serves: {variationName}" est affiché avec le ciblage On.
2. Exécutant un test rapide : ai_config = ai_client.{completion|agent}_config(...) et affirmant que ai_config.enabled is True.

Raccourci direct si l'utilisateur veut basculer le ciblage sans invoquer la skill sœur

configs-targeting est le chemin canonique — il gère les rollouts en pourcentage, les règles ciblées et les recherches d'ID de variation. Mais pour le cas le plus simple ("promouvoir la nouvelle variation en fallthrough dans un seul environnement"), tu peux exécuter le PATCH sémantique sous-jacent toi-même une fois que tu connaîs le _id de la nouvelle variation.

Obtiens l'ID de variation (utilise get-ai-config MCP, ou) :

curl -s "https://app.launchdarkly.com/api/v2/projects/$PROJECT/ai-configs/$CONFIG_KEY/targeting?env=$ENV" \
  -H "Authorization: $LD_API_KEY" -H "LD-API-Version: beta" \
  | jq '.variations[] | {key, _id}'

Bascule le fallthrough pour qu'il pointe dessus :

curl -X PATCH "https://app.launchdarkly.com/api/v2/projects/$PROJECT/ai-configs/$CONFIG_KEY/targeting?env=$ENV" \
  -H "Authorization: $LD_API_KEY" \
  -H "Content-Type: application/json; domain-model=launchdarkly.semanticpatch" \
  -H "LD-API-Version: beta" \
  -d '{"instructions":[{"kind":"updateFallthroughVariationOrRollout","variationId":"<id-from-step-above>"}]}'

Ou la même chose via la CLI LD si elle est installée localement :

ldcli resources ai-configs update-ai-config-targeting \
  --projectKey $PROJECT --configKey $CONFIG_KEY --envKey $ENV \
  --data '{"instructions":[{"kind":"updateFallthroughVariationOrRollout","variationId":"<id>"}]}'

N'utilise pas turnTargetingOn — cette instruction semantic-patch ne fonctionne pas pour les configs. updateFallthroughVariationOrRollout est la seule instruction qui bascule réellement le fallthrough.

Format de modelConfigKey

Obligatoire pour que les modèles s'affichent dans l'UI. Format : {Provider}.{model-id}

• OpenAI.gpt-4o
• OpenAI.gpt-4o-mini
• Anthropic.claude-sonnet-4-5
• Anthropic.claude-3-5-sonnet

L'outil create-ai-config-variation valide ce format et rejette les valeurs invalides.

Cas Limites

Ce Qu'il NE Faut PAS Faire

• Ne crée pas de configs sans comprendre le cas d'usage
• Ne saute pas le processus en deux étapes (config puis variation)
• N'essaie pas d'attacher les tools lors de la création initiale -- mets à jour la variation après
• N'oublie pas modelConfigKey (les modèles ne s'afficheront pas dans l'UI)
• N'omets pas modelName de l'appel de variation initial. C'est obligatoire à la création ; le définir via une requête PATCH de suivi est une solution de contournement à un bug, pas le flux prévu. Le champ PATCH est aussi modelName, pas name.
• Ne bascule pas à du curl + jq brut pour la vérification. Utilise get-ai-config (MCP) — il retourne un objet typé et évite les filtres jq fragiles qui cassent lors de variations de forme de réponse.
• Ne considère pas le workflow comme complet jusqu'à ce que l'utilisateur ait été informé d'exécuter configs-targeting. Une variation créée qui n'est pas promue en fallthrough retourne enabled=False à chaque consommateur.

Skills Connexes

• tools -- Crée les tools avant d'attacher
• configs-variations -- Ajoute plus de variations pour l'expérimentation
• configs-update -- Modifie les configs selon les apprentissages