Créer une IA Config

Vous utilisez une skill qui vous guidera dans la création d'une IA Config dans LaunchDarkly. Votre travail consiste à comprendre le cas d'usage, choisir le bon mode, créer la config et ses variations, et vérifier que tout est correctement configuré.

⚠️ Cette skill crée une config — elle ne la rend pas servable. Une IA Config fraîchement créée a son fallthrough pointant vers une variation désactivée générée automatiquement, et non vers la variation que vous venez de créer. Le SDK retournera ai_config.enabled=False à chaque évaluation jusqu'à ce que vous activiez le ciblage et pointiez le fallthrough vers votre nouvelle variation. Ce n'est pas un bug — c'est l'état par défaut. Vous devez exécuter /aiconfig-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 d'échec le plus courant rencontré par les utilisateurs avec cette skill est de sauter l'étape de ciblage et de passer du temps à déboguer enabled=False dans le code de leur application.

Prérequis

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

Outil MCP principal :

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

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

• create-ai-config -- créer seulement le shell de la config (clé, nom, mode)
• create-ai-config-variation -- ajouter une variation avec modèle, prompts et paramètres
• get-ai-config -- vérifier que la config a été créée correctement

Outils MCP optionnels (améliorent le flux) :

• list-ai-configs -- parcourir les configs existantes pour comprendre les conventions de nommage
• create-project -- créer 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), parcourez l'intégralité du flux sans vous arrêter pour demander des détails que vous pouvez déduire. Utilisez 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étez toutes les étapes (création + vérification) en une seule passe.

Flux

Étape 1 : Comprendre le cas d'usage

Avant de créer, identifiez ce que vous construisez :

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

Étape 2 : Choisir le mode Agent vs Completion

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

Les deux modes supportent les tools. Tous les modèles ne supportent pas le mode agent — vérifiez la compatibilité du modèle si vous utilisez le mode agent. En cas de doute, commencez par le mode completion (c'est le défaut de l'API et c'est plus flexible).

Étape 3 : Créer la config (Recommandé : une seule étape)

Utilisez 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 la variation et la vérification automatiquement.

Champs de la config :

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

Champs de la variation :

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

Pour le mode agent, fournissez :

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

Exemple d'appel 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, fournissez :

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

Exemple d'appel 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} (utilisez les clés en snake_case de l'UI)

L'outil retourne la config complète 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, utilisez les outils individuels :

1. create-ai-config -- créer le shell de la config
2. create-ai-config-variation -- ajouter la variation avec modèle, prompts et paramètres
3. get-ai-config -- vérifier le résultat

Exécutez les trois étapes sans vous arrêter pour demander des détails. Déduisez 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, vous avez assez d'informations pour compléter l'intégralité du flux. Posez des questions de clarification uniquement si le mode ou le modèle est vraiment ambigu.

Étape 4 : Vérifier

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

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

Utilisez get-ai-config pour l'appel de vérification — ne tombez pas dans le piège du curl + jq brut. L'outil MCP retourne un objet typé que vous pouvez inspecter directement. Les filtres jq rédigés à la main contre la réponse REST cassent régulièrement : l'endpoint de détail des Configs IA retourne la liste des 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 la réponse est un tableau nu. Si vous devez appeler l'API REST, utilisez d'abord jq -e . pour inspecter la forme réelle avant de creuser.

Rapportez les résultats :

• Config créée avec la bonne structure
• La variation a un modèle assigné
• Signalez tout modèle ou paramètre manquant
• Fournissez 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 au fallthrough. La nouvelle config retournera enabled=False à chaque consommateur jusqu'à ce que le ciblage soit mis à jour. C'est le mode d'échec le plus courant « J'ai créé une config mais mon SDK obtient toujours le fallback ». Le flux n'est pas complet jusqu'à cette étape.

Ce qu'il faut dire à l'utilisateur

Imprimez cette checklist textuellement à l'utilisateur après l'étape 4, puis attendez la confirmation. Ne prétendez pas que la skill a réussi jusqu'à ce que l'utilisateur confirme que le fallthrough a été activé.

✅ La config et la variation sont créées.

🔴 Le SDK retournera enabled=False jusqu'à ce que vous activiez le ciblage. Le fallthrough pointe actuellement vers une variation désactivée générée automatiquement, pas vers le {variationKey} que vous venez de créer.

Étape suivante — exécutez /aiconfig-targeting avec ces entrées :

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

Vérifiez après que le ciblage a été activé en :

1. Ouvrant la Config IA dans l'UI LD, en basculant vers l'environnement correct et en confirmant que « Default rule serves: {variationName} » s'affiche avec le ciblage On.
2. En exécutant un test rapide : ai_config = ai_client.{completion|agent}_config(...) et en assertant ai_config.enabled is True.

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

aiconfig-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 au fallthrough dans un environnement »), vous pouvez exécuter vous-même le sémantique PATCH sous-jacent une fois que vous connaissez le _id de la nouvelle variation.

Récupérez l'ID de variation (utilisez MCP get-ai-config, 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}'

Activez le fallthrough pour qu'il pointe vers lui :

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'utilisez pas turnTargetingOn — cette instruction de semantic-patch ne fonctionne pas pour les Configs IA. updateFallthroughVariationOrRollout est la seule instruction qui active réellement le fallthrough.

Format de modelConfigKey

Requis 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éez pas de configs sans comprendre le cas d'usage
• Ne sautez pas le processus en deux étapes (config puis variation)
• N'essayez pas d'attacher des tools lors de la création initiale -- mettez à jour la variation après
• N'oubliez pas modelConfigKey (les modèles ne s'afficheront pas dans l'UI)
• N'omettez pas modelName de l'appel de variation initial. Il est requis au moment de la création ; le définir via un PATCH de suivi est une contournement pour un bug, pas le flux prévu. Le champ PATCH est aussi modelName, pas name.
• Ne tombez pas dans le piège du curl + jq brut pour la vérification. Utilisez get-ai-config (MCP) — cela retourne un objet typé et évite les filtres jq fragiles qui cassent sur la variation de forme de réponse.
• Ne considérez pas le flux comme complet jusqu'à ce que l'utilisateur ait été invité à exécuter aiconfig-targeting. Une variation créée qui n'est pas promue au fallthrough retourne enabled=False à chaque consommateur.

Skills associées

• aiconfig-tools -- Créer des tools avant de les attacher
• aiconfig-variations -- Ajouter plus de variations pour l'expérimentation
• aiconfig-update -- Modifier les configs selon ce qui a été appris