📖 Manuel

Agent Prompt Tuner

Quand utiliser ce skill

• Agent produit des sorties incorrectes, incohérentes ou mal formatées
• Taux d'erreur en production dépasse un seuil acceptable
• Migration vers un nouveau modèle LLM (recalibration nécessaire)
• Création d'un nouvel agent : structurer les instructions dès le départ
• Coût ou latence trop élevés sans gain de qualité

Workflow

1. Constituer la baseline

Avant toute modification, mesurer les métriques actuelles :

taux_succes   = nb_sorties_correctes / nb_total  (par catégorie de tâche)
hallucination = nb_faits_inventés / nb_total
tool_error    = nb_mauvais_appels_outils / nb_appels
latence_p95   = percentile 95 du temps de réponse
coût/req      = tokens_in * prix_in + tokens_out * prix_out

Constituer un dataset d'évaluation de 50 à 200 cas représentatifs avant d'écrire la première ligne révisée. Sans baseline, toute modification est une intuition.

2. Classifier les erreurs

Trier les échecs dans ces catégories (quantifier chacune) :

3. Restructurer le system prompt

Ordre optimal des sections (ne pas mélanger) :

1. Rôle / persona (1-2 phrases max)
2. Capacités disponibles (liste des outils, contexte)
3. Contraintes et interdictions EXPLICITES
4. Format de sortie attendu + exemple inline
5. Comportement sur erreur / cas ambigus

Exemple concret (agent de support) :

Tu es un agent de support bancaire. Tu traites UNIQUEMENT les demandes
liées aux comptes, virements et cartes.

Outils disponibles : get_account_balance, list_transactions, open_ticket.

INTERDIT : donner des conseils d'investissement ou des informations
sur des tiers non liés au compte du client.

Format de réponse :
{"status": "ok|error|escalate", "message": "...", "ticket_id": null|"XXX"}

Si la demande est ambiguë : réponds avec status="escalate" et explique
pourquoi dans "message". Ne devine jamais.

4. Few-shot examples

• Tâches simples : 1-3 exemples
• Tâches complexes ou multi-étapes : 3-8 exemples
• Couvrir : cas nominal, cas limites, cas d'erreur/refus

Structure recommandée par exemple :

<example>
<input>Quel est le solde de mon compte 123456 ?</input>
<thinking>L'utilisateur demande un solde. J'appelle get_account_balance.</thinking>
<output>{"status":"ok","message":"Votre solde est de 1 240,50 €.","ticket_id":null}</output>
</example>

5. Chain-of-thought : quand l'imposer

Forcer le scratchpad uniquement quand nécessaire : chaque token de thinking augmente latence et coût.

6. Descriptions d'outils

Modèle à suivre pour chaque outil :

{
  "name": "search_transactions",
  "description": (
    "Recherche des transactions sur un compte. "
    "UTILISER pour : retrouver un virement, vérifier un débit. "
    "NE PAS UTILISER pour : calculs, infos non transactionnelles."
  ),
  "parameters": {
    "account_id": {"type": "string", "example": "123456"},
    "date_from":  {"type": "string", "format": "YYYY-MM-DD"},
    "limit":      {"type": "integer", "default": 20, "max": 100}
  }
}

Règle : si l'agent appelle le mauvais outil, la description est insuffisante — réécrire avant de chercher ailleurs.

7. Guardrails dans le prompt

Instructions de récupération à intégrer directement :

- Si tu n'es pas sûr à plus de 80%, réponds UNCERTAIN au lieu d'inventer.
- Valide le JSON de sortie avant de retourner (structure, types, champs requis).
- Si un outil retourne une erreur, retente une seule fois avec des args corrigés,
  puis escalade avec status="error".
- Ne concatène jamais d'informations de comptes différents dans une même réponse.

8. A/B testing

variante_A = prompt actuel (contrôle)
variante_B = prompt modifié (une seule variable changée)

Evaluer sur le dataset d'évaluation :
- taux_succes_A vs taux_succes_B
- p-value < 0.05 requis pour déployer (test de proportion z-test)
- si delta < 2% : ne pas déployer, bruit statistique

# Exemple Python rapide (z-test sur taux de succès)
from statsmodels.stats.proportion import proportions_ztest
stat, p = proportions_ztest([ok_B, ok_A], [n_B, n_A])
print(f"p={p:.4f} — {'DEPLOY' if p < 0.05 else 'SKIP'}")

Ne déployer une variante que si l'amélioration est significative ET si le gain justifie l'éventuelle augmentation de coût/latence.

9. Versionnage

Gérer les prompts comme du code :

# Commit après chaque expérimentation
git add prompts/agent_support_v2.txt
git commit -m "prompt: ajouter guardrail hallucination — +4.2% accuracy"

# Tag de version stable
git tag prompt-support-v2.1-stable

Maintenir un PROMPT_CHANGELOG.md minimal :

## 2026-06-24 — v2.1
Auteur : k.benazzouz
Change : ajout guardrail UNCERTAIN + exemple edge case solde nul
Métriques : accuracy 81% → 85.2%, hallucination 6% → 1.8%

10. Boucle d'amélioration continue

Production → logging des échecs → analyse hebdo → update dataset → nouveau cycle

Déclencher un cycle forcé lors de : mise à jour du modèle LLM, changement de cas d'usage, dérive de performance > 5% sur 2 semaines.

Critères de décision rapide

Anti-patterns / pièges

• Modifier plusieurs variables simultanément : impossible d'identifier la cause de l'amélioration ou de la régression.
• Instructions vagues : "sois précis" ne change rien. Remplacer par "réponds en 2 phrases maximum, chiffres inclus".
• Over-fitting au dataset de test : un prompt parfait sur 50 exemples peut échouer en production sur les variantes non représentées. Toujours valider sur un ensemble holdout séparé.
• Few-shots contradictoires : deux exemples qui montrent des formats de sortie différents créent de la confusion. Uniformiser avant d'ajouter.
• Ignorer le coût des guardrails : chaque instruction de validation ajoutée consomme des tokens. Grouper les guardrails en bloc unique plutôt qu'instructions dispersées.
• Pas de rollback prévu : déployer sans tag git ou sauvegarde du prompt précédent = incapacité à revenir en arrière rapidement en cas d'incident.