Créer un flux d'utilisation de fonctionnalités via éval LLM

Certaines fonctionnalités PostHog (résumés de session de groupe, résumés de session unique, recherche IA dans replay, debug IA du tracking d'erreurs, etc.) génèrent des centaines ou des milliers de traces LLM par semaine. Les lire manuellement n'est pas réalisable. Cette compétence couvre le schéma end-to-end pour transformer ce volume de traces en un flux Slack en direct des cas d'usage canoniques — ce que les utilisateurs font réellement avec la fonctionnalité.

Le workflow est mixte, et privilégie l'UI. L'inspection des traces et la découverte de filtres (étapes 1-2) sont pilotées par MCP. La création d'eval, le test et l'activation (étapes 4-5) sont pilotés par MCP quand les outils posthog:llma-evaluation-* sont exposés à votre agent — mais ce n'est souvent pas le cas, auquel cas basculez sur l'UI (Data pipeline → destinations pour l'alerte est toujours UI). Chaque étape signale son fallback UI. Attendez-vous à finir dans l'UI même si vous commencez par le chat.

Quand l'utiliser

• "Comment les gens utilisent-ils vraiment [feature X] en production ?"
• "Pouvons-nous identifier les cas d'usage canoniques pour [feature X] afin d'écrire une meilleure documentation / prioriser les améliorations ?"
• "Je veux un flux Slack d'exemples d'utilisation représentatifs sans parcourir manuellement les traces."
• "Configurez un flux de cas d'usage pour [feature X] dans #team-[area]-usage."

Si l'utilisateur veut juste déboguer une trace unique ou ajuster une eval existante, redirigez plutôt vers exploring-llm-traces ou exploring-llm-evaluations.

Deux schémas de filtre

Cette compétence supporte deux façons différentes de cibler une eval à « la fonctionnalité qui vous intéresse » :

Schéma A — Préfixe trace_id natif à la fonctionnalité. Pour les fonctionnalités autonomes qui émettent leur propre pattern $ai_trace_id (par ex. session-summary:group:, replay-search:, flux spécifiques au tracking d'erreurs). Filtrez sur le préfixe.

Schéma B — Mode agent PostHog AI. Pour les fonctionnalités avec lesquelles l'utilisateur interagit via PostHog AI dans un mode agent spécifique (tracking d'erreurs, analytics produit, session replay, SQL, flags, surveys, LLM analytics). Filtrez sur ai_product = 'posthog_ai' AND agent_mode = '<mode>'. Cela nécessite PR #55160 (fusionnée avril 2026) à déployer, qui passe agent_mode et supermode sur chaque $ai_generation émis par la boucle d'agent chat. Un effet secondaire ergonomique utile : agent_mode IS NOT NULL est un filtre fiable pour « tour de chat utilisateur » — les batch jobs et les appels LLM internes à l'outil empruntent des chemins de code différents et ont agent_mode=null, donc ils sont exclus gratuitement.

Si l'utilisateur demande « que les utilisateurs essaient-ils DE FAIRE en mode [ET / replay / SQL / flags / surveys] de PostHog AI », c'est le Schéma B. S'il demande « quels cas d'usage [la fonctionnalité autonome] couvre », c'est le Schéma A. Choisissez le schéma en premier — le prompt, le filtre et le nommage du canal Slack en découleront.

Prérequis

Si $session_id manque sur l'un ou l'autre type d'événement, soumettez une correction backend avant de continuer — il n'y a pas de contournement UI. La fonctionnalité session-summary a un exemple travaillé du pattern de threading dans PR #54952. Pour le Schéma B, le pattern de threading du mode agent est dans PR #55160.

Outils

Avant de commencer, *vérifiez quels outils `posthog:llma-evaluation-` sont vraiment exposés dans l'ensemble d'outils MCP de votre agent.** S'ils ne sont pas chargés, traitez les étapes 4-5 comme des parcours UI plutôt que des appels d'outil.

Workflow

Étape 1 — Identifiez le filtre

Schéma A (préfixe trace_id natif à la fonctionnalité) : trouvez le préfixe qui correspond à votre fonctionnalité.

SELECT
    splitByChar(':', coalesce(properties.$ai_trace_id, ''))[1] AS root,
    splitByChar(':', coalesce(properties.$ai_trace_id, ''))[2] AS subtype,
    count() AS events
FROM events
WHERE timestamp > now() - INTERVAL 3 DAY
    AND event = '$ai_generation'
    AND properties.$ai_trace_id IS NOT NULL
GROUP BY root, subtype
ORDER BY events DESC
LIMIT 25

Remarque : coalesce(..., '') est essentiel — splitByChar sur une colonne nullable génère une erreur en HogQL sinon.

Schéma B (mode agent PostHog AI) : vérifiez la couverture et le volume du mode que vous ciblez.

SELECT
    properties.agent_mode AS agent_mode,
    properties.supermode AS supermode,
    count() AS events,
    count(DISTINCT properties.$ai_trace_id) AS traces
FROM events
WHERE timestamp > now() - INTERVAL 3 DAY
    AND event = '$ai_generation'
    AND properties.ai_product = 'posthog_ai'
GROUP BY agent_mode, supermode
ORDER BY events DESC
LIMIT 20

Valeurs attendues pour agent_mode : error_tracking, product_analytics, sql, session_replay, flags, survey, llm_analytics, null. Null ≈ batch jobs + appels internes à l'outil (pas chat utilisateur). supermode='plan' sépare les tours de planification des tours d'exécution — utile à signaler séparément si votre flux concerne spécifiquement le mode plan.

Enregistrez le mode + volume approximatif. Les modes à faible volume (<100 événements/jour) produiront un flux goutte-à-goutte difficile à valider en début ; les modes à haut volume (>1k/jour) peuvent nécessiter un échantillonnage pour éviter de noyer Slack. Voir la section « Tips » sur l'échantillonnage.

Étape 2 — Extrayez quelques traces échantillon

Utilisez-les pour l'itération du prompt à l'étape 4.

Schéma A :

posthog:query-llm-traces-list
{
  "properties": [
    { "type": "event", "key": "$ai_trace_id", "operator": "icontains", "value": "<your-prefix-here>" }
  ],
  "limit": 10,
  "dateRange": { "date_from": "-2d" },
  "randomOrder": true
}

Schéma B :

posthog:query-llm-traces-list
{
  "properties": [
    { "type": "event", "key": "ai_product", "operator": "exact", "value": "posthog_ai" },
    { "type": "event", "key": "agent_mode", "operator": "exact", "value": "<mode-here>" }
  ],
  "limit": 10,
  "dateRange": { "date_from": "-2d" },
  "randomOrder": true
}

randomOrder: true importe — le biais de récence produit un échantillon non-représentatif. Choisissez 5-10 traces pour tester.

Avertissement sur la taille de sortie : query-llm-traces-list avec limit: 10 retourne régulièrement 3-6 MB de JSON (input/output complètes par génération). Cela va exploser votre context window. Déléguez immédiatement la synthèse à un sous-agent dès que vous voyez l'erreur « result exceeds maximum allowed tokens » — demandez au sous-agent d'extraire, par trace : l'id de trace, le premier message utilisateur (tronqué à ~300 caractères), l'URL $current_url échantillonnée, et une description d'une phrase de ce dont traitait la conversation. N'essayez pas de lire le fichier brut en ligne.

Attention au dérive thématique dans les échantillons du Schéma B. Le tag agent_mode reflète la sélection de mode de l'utilisateur au moment du tour — mais l'état chat conserve le mode même si l'utilisateur dévie hors-sujet dans la même conversation (par ex. l'utilisateur a sélectionné « error tracking » mode, puis a posé une question sans rapport sur les prix trois tours après). Le step classification du prompt eval doit être permissif sur la dérive thématique : PASS doit signifier « l'utilisateur fait quelque chose reconnaissablement dans le champ d'application de ce mode », FAIL doit capturer la dérive hors-sujet. Sinon, votre flux inclura des entrées PASS non pertinentes qui portent simplement le tag de mode.

Étape 3 — Rédigez le prompt LLM-judge

Le prompt a deux responsabilités : (a) classer la trace comme pertinente ou non, (b) produire un texte de raisonnement directement postable sur Slack (pas de préambule, pas de méta-description). Le champ de raisonnement devient le corps du message Slack.

Template :

You are analyzing a PostHog [FEATURE NAME] trace to extract its real use case.
Your reasoning text will be posted directly to a Slack channel as a notification.
Write it as a short, ready-to-post message — no preamble, no meta-description.

Step 1 — Classification:
- PASS = this trace is the [feature kind] you care about
- FAIL = a different LLM call or a false match
- N/A = ambiguous from the trace alone

Step 2 — Reasoning (only matters if PASS). Write 2-3 sentences in this exact format:

"[OPENER] [what they targeted/filtered for]. They were
trying to [understand X / debug Y / find Z]. The result surfaced [key pattern
or finding]."

Your output MUST start with the exact phrase "[OPENER]". No other opening is allowed.

Rules:
- No "This is a [feature]..." or "The input contains..." preamble
- No JSON, field names, system-prompt references, or meta-description
- Concrete > generic. "users hitting error tracking for the first time" beats "user behavior"
- If you cannot infer one of the three pieces from the trace, write "(unclear from trace)" in that slot — do not guess

Choisissez un [OPENER] qui correspond à la façon dont les utilisateurs interagissent réellement avec la fonctionnalité. L'ouverture forcée est essentielle (elle empêche le modèle de dériver vers une « this trace is a... » méta-description), mais le verbe exact doit correspondre à l'interaction :

Remarque : supermode='plan' est un sous-filtre qui s'ajoute en haut d'une ligne agent_mode — ce n'est pas sa propre ligne. Si vous voulez plan-mode uniquement, filtrez agent_mode='<mode>' AND supermode='plan' et choisissez un ouverture comme "A user asked PostHog AI to plan".

Si vous forcez "A user ran" sur une fonctionnalité basée sur le chat, le modèle produira des contorsions maladroites (« A user ran a question about... ») qui sonne mal sur Slack. Le pattern ouverture forcée est le mécanisme — la phrase spécifique est par fonctionnalité.

La liste des contre-exemples (« No 'This is a...' preamble », etc.) est essentielle indépendamment de l'ouverture. Ne l'enlevez pas.

Étape 4 — Créez l'eval (désactivée), testez, itérez

Créez avec enabled: false afin qu'elle ne s'étend pas immédiatement à toutes les traces.

Si posthog:llma-evaluation-create est exposé, utilisez ce payload :

posthog:llma-evaluation-create
{
  "name": "[feature] use case feed",
  "description": "Extracts canonical use cases for [feature] for the #team-[area]-usage Slack feed",
  "evaluation_type": "llm_judge",
  "evaluation_config": {
    "prompt": "<full prompt from step 3>"
  },
  "output_type": "boolean",
  "output_config": { "allows_na": true },
  "model_configuration": {
    "provider": "<provider>",
    "model": "<model>"
  },
  "enabled": false,
  "conditions": {
    "filters": [
      // Pattern A — feature-native trace_id prefix:
      { "key": "$ai_trace_id", "operator": "icontains", "value": "<your-prefix>" }

      // Pattern B — PostHog AI agent mode (use these INSTEAD of the trace_id filter):
      // { "key": "ai_product", "operator": "exact", "value": "posthog_ai" },
      // { "key": "agent_mode", "operator": "exact", "value": "<mode>" }
    ]
  }
}

Laissez le choix du modèle à l'utilisateur — le coût LLM-judge s'adapte linéairement avec le volume d'événements, et bon marché vs capable est un vrai trade-off qu'ils doivent faire en fonction de leur propre tolérance de dépenses et exigences de qualité du signal. Ne choisissez pas pour eux.

Fallback UI (quand llma-evaluation-create n'est pas exposé) : LLM analytics → Evaluations → New evaluation. Type = LLM judge, output = boolean + allow N/A, filtres comme ci-dessus, enabled = off. Collez le prompt de l'étape 3.

Puis testez sur vos traces échantillon.

Si posthog:llma-evaluation-run est exposé :

posthog:llma-evaluation-run
{
  "evaluationId": "<uuid from create>",
  "target_event_id": "<a $ai_generation event id from step 2>",
  "timestamp": "<ISO timestamp of that event>"
}

Fallback UI : sur la page de détail eval, utilisez le bouton « Run on event » avec l'id d'événement de l'échantillon de trace.

Regardez le $ai_evaluation_reasoning retourné. S'il ajoute un préambule, dévie ou décrit l'input, corrigez le prompt (via llma-evaluation-update ou en éditant dans l'UI) et relancez. Itérez sur 3-5 traces avant d'activer.

Modes d'échec courants pendant l'itération :

Étape 5 — Activez l'eval

Une fois que 3-5 exécutions échantillon produisent une sortie prête pour Slack.

Si posthog:llma-evaluation-update est exposé :

posthog:llma-evaluation-update
{
  "evaluationId": "<uuid>",
  "enabled": true
}

Fallback UI : LLM analytics → Evaluations → ouvrez l'eval → basculez enabled.

L'eval s'exécutera maintenant sur chaque nouvel événement $ai_generation correspondant.

Étape 6 — Construisez le workflow (UI uniquement)

La configuration du workflow n'est pas accessible en MCP pour les écritures (posthog:workflows-list / posthog:workflows-get sont lecture seule). Les étapes ci-dessous sont un parcours UI.

Prérequis : avant de commencer, invitez le bot PostHog Slack dans votre canal cible (/invite @PostHog dans le canal Slack). Sans cela, l'étape de dispatch Slack échouera avec une erreur de permission opaque au moment de l'envoi, pas au moment de la sauvegarde — facile à manquer.

6.1 Créez le workflow

Data pipeline → Workflows → New workflow. Nommez-le <feature> use case feed pour correspondre au nom eval de l'étape 4.

6.2 Étape de déclenchement

• Event : AI evaluation (LLM) — c'est-à-dire $ai_evaluation. C'est l'événement émis quand une eval s'exécute, et c'est le seul événement qui porte les propriétés $ai_evaluation_*. L'événement $ai_generation original n'est pas enrichi avec les résultats eval, donc filtrer sur $ai_generation ici ne correspond à rien.
• Filtres de propriété (tous deux requis) :
  • AI Evaluation Name (LLM) égale <your eval name from step 4>
  • AI Evaluation Result (LLM) égale true

⚠️ ESSENTIEL : les valeurs stockées pour $ai_evaluation_result sont les chaînes 'True' / 'False' / 'None' — PAS 'PASS' / 'FAIL' / 'N/A' (malgré ce que le template de prompt les appelle en interne). Le filtre de propriété UI des Workflows normalise true → 'True', donc sélectionner equals true dans la dropdown fonctionne. Mais si vous câbliez ceci dans du SQL brut quelque part ailleurs (par ex. une fonction hog), vous auriez besoin du littéral chaîne. Vérifiez la distribution stockée avant de sauvegarder :

SELECT DISTINCT toString(properties.$ai_evaluation_result) AS result, count() AS n
FROM events
WHERE event = '$ai_evaluation'
  AND properties.$ai_evaluation_name = '<your eval name>'
  AND timestamp > now() - INTERVAL 1 HOUR
GROUP BY result

Si les seules valeurs sont True/False/None et True domine, le filtre UI equals true correspondra. Si vous voyez quelque chose d'autre, ajustez en conséquence.

6.3 Étape de dispatch Slack

• Add step → Slack dispatch
• Channel : #<your-team>-usage-feed
• Sender / bot display name : quelque chose qui se lit bien dans le canal (par ex. PostHog Usage Feed)
• Blocks (Slack block-kit JSON) — collez ceci et remplacez <project_id> par votre ID de projet numérique réel (par ex. 2) :

[
  {
    "text": {
      "text": "<emoji> *{event.properties.$ai_evaluation_name}* triggered by *{person.name}*",
      "type": "mrkdwn"
    },
    "type": "section"
  },
  {
    "text": {
      "text": "{event.properties.$ai_evaluation_reasoning}",
      "type": "mrkdwn"
    },
    "type": "section"
  },
  {
    "type": "actions",
    "elements": [
      {
        "url": "https://us.posthog.com/project/<project_id>/llm-analytics/traces/{event.properties.$ai_trace_id}?event={event.properties.$ai_target_event_id}",
        "text": { "text": "View Trace", "type": "plain_text" },
        "type": "button"
      },
      {
        "url": "https://us.posthog.com/project/<project_id>/replay/{event.properties.$session_id}",
        "text": { "text": "View Trigger Session", "type": "plain_text" },
        "type": "button"
      },
      {
        "url": "{person.url}",
        "text": { "text": "View Person", "type": "plain_text" },
        "type": "button"
      }
    ]
  }
]

Choisissez un <emoji> qui correspond à la forme de la fonctionnalité : 📊 product analytics, 🐛 error tracking, 🎬 session replay, 🔎 search/AI search, 🧪 experiments, 🚩 flags, 📋 surveys, 🧠 generic AI.

Les placeholders {event.properties.X} et {person.X} sont une syntaxe de template PostHog valide et se résolvent au moment de l'envoi.

6.4 Testez avant d'activer

Le panneau Test des Workflows a deux modes — cela importe car naïvement cliquer sur « Test » peut ressembler à une intégration cassée alors qu'elle ne l'est pas :

• Synthetic event (par défaut) — le panneau Test fabrique un payload $ai_evaluation et exécute le flux sans frapper l'API réelle de Slack. Utile comme test sec du template de bloc, mais les placeholders {event.properties.$ai_*} peuvent se résoudre à null et le validateur de bloc de Slack rejettera le payload avec invalid_blocks. C'est un artefact de harnais de test, pas un vrai bug — ne le poursuivez pas.
• « Make real HTTPS requests » — basculez ce toggle. Les Workflows extraient alors un événement $ai_evaluation réel récent correspondant à vos filtres et exécutent le flux end-to-end, y compris le vrai post Slack. C'est le test qui vous dit « ça marche » pour de vrai. Si aucun événement réel correspondant n'existe encore (courant si l'eval vient juste d'être activée), déclenchez la fonctionnalité vous-même, attendez ~1 minute, et réessayez.

Flux recommandé : synthetic → vérifiez le rendu du template de bloc → basculez real-requests on → confirmez qu'un vrai post atterrit dans le canal → sauvegardez + activez le workflow.

Étape 7 — Vérifiez end-to-end en production

Une fois le workflow activé, déclenchez la fonctionnalité vous-même. Dans une minute ou deux :

1. L'événement $ai_generation doit apparaître dans LLM Analytics
2. L'eval doit s'exécuter automatiquement et émettre un événement $ai_evaluation
3. Le workflow doit se déclencher et le post Slack doit atterrir dans le canal configuré
4. Cliquez sur « View Trigger Session » — doit atterrir sur l'enregistrement de vous utilisant la fonctionnalité, pas la page d'accueil du replay

Si « View Trigger Session » atterrit sur la page d'accueil du replay, $session_id manque sur l'événement $ai_evaluation (qui est séparé de l'événement $ai_generation — le threading est indépendant pour les deux). Correction backend nécessaire — voir prérequis.

Exemple travaillé A (Schéma A) : cas d'usage de résumé de session de groupe

Pattern : une eval group_summary_use_case_feed streamant vers un canal #<team>-usage-feed. Préfixe de trace : session-summary:group:. Ouverture : "A user ran a group summary on". Le canal Slack affichait par ex. :

📊 _group_summary_use_casefeed triggered by some user "A user ran a group summary on a company's onboarding sessions from the last 7 days. They were trying to understand why account activation rates are low. The summary surfaced that most users abandon at the company onboarding wizard after creating accounts." [View Trace] [View Trigger Session] [View Person]

Les PRs qui ont rendu ceci possible (liées ici comme exemples travaillés du pattern de threading session_id, pas comme étapes de la compétence elle-même) :

• PostHog/posthog#54952 — passe trigger_session_id à travers aux événements $ai_generation sur le backend de résumé de session
• (PR de suivi — passe $session_id sur les événements $ai_evaluation spécifiquement)

Exemple travaillé B (Schéma B) : PostHog AI en mode error tracking

Pattern : un flux scoped agent_mode = 'error_tracking' streamant vers un canal #<team>-usage-feed, répondant à « que les utilisateurs essaient-ils réellement DE FAIRE quand ils chattent avec PostHog AI en mode error tracking ? » Le dimensionnement du mode varie d'un ordre de magnitude ou plus selon les modes d'agent — vérifiez le volume par spot-check §Étape 1 avant de câbler, car un mode haut-volume peut noyer un canal. Ouverture : "A user asked PostHog AI about".

PR d'activation : PostHog/posthog#55160 — passe agent_mode et supermode sur chaque $ai_generation émis par la boucle d'agent chat. Le câblage vit dans ee/hogai/core/agent_modes/executables.py (AgentExecutable._get_model) et passe le dict par le champ posthog_properties existant sur MaxChatMixin dans ee/hogai/llm.py. Avant cette PR, cibler une eval PostHog AI à un mode spécifique n'était pas possible — vous évalueriez chaque génération PostHog AI, qui produisait des flux bruyants avec des taux PASS dans les chiffres simples.

Observation clé du setup : le tag agent_mode reflète le mode au moment du tour, mais l'état chat conserve la sélection de mode même quand les utilisateurs dérvent hors-sujet en milieu de conversation. Vérification par spot-check : un échantillon aléatoire agent_mode=error_tracking incluait une conversation qui finit par concerner le prix du session replay. Le prompt eval doit être permissif sur la dérive thématique — PASS uniquement quand le tour est reconnaissablement dans le champ d'application du mode, FAIL quand la conversation a dérivé vers quelque chose d'autre entièrement.

Valider la qualité du signal après le lancement

Une fois que le flux a été en direct pendant un jour ou deux, vérifiez par spot-check la sortie eval à l'échelle.

Si posthog:llma-evaluation-summary-create est exposé :

posthog:llma-evaluation-summary-create
{
  "evaluation_id": "<uuid>",
  "filter": "fail"
}

Fallback UI : ouvrez l'eval dans LLM analytics → Evaluations → bouton « Summarize results », filter = fail.

Si le bucket FAIL est grand, le step classification est trop strict — assouplissez-le. Si le bucket PASS a beaucoup de raisonnements génériques, itérez sur le prompt pour appliquer la concrétude. L'outil de synthèse vous donne une lecture rapide dessus sans que vous ayez besoin de faire défiler les événements individuels.

Vérifiez les événements bruts quand nécessaire (remarque : la valeur de résultat stockée est 'True', pas 'PASS' — voir étape 6) :

SELECT
    properties.$ai_evaluation_reasoning AS reasoning,
    properties.$ai_trace_id AS trace_id,
    timestamp
FROM events
WHERE event = '$ai_evaluation'
    AND properties.$ai_evaluation_name = '<your eval name>'
    AND properties.$ai_evaluation_result = 'True'
    AND timestamp > now() - INTERVAL 1 DAY
ORDER BY timestamp DESC
LIMIT 25

Tips

• Le champ de raisonnement EST le message Slack — concevez le prompt pour cela, pas pour « chain of thought avant classification ». Les modèles peuvent produire du texte structuré prêt pour Slack en un seul passage.
• Les juges LLM sont non-déterministes entre les reruns. Attendez-vous à 1-5 % de bruit même avec un prompt et un modèle fixes. Si vous avez besoin de reproductibilité, épinglez un provider/seed déterministe dans model_configuration.
• Gardez l'eval étroitement scopée via conditions.filters sur le préfixe $ai_trace_id. Sinon elle s'étend à chaque événement $ai_generation dans le projet et brûle le coût LLM.
• Pour les fonctionnalités haut-volume (>10k traces/semaine), considérez l'échantillonnage — réglez l'eval pour qu'elle s'exécute sur un pourcentage d'événements correspondants plutôt que tous. Noyer Slack est un vrai mode d'échec.
• Le bouton « View Trigger Session » est le lien de plus haute valeur dans l'alerte. Sans lui, le flux est juste du texte — vous ne pouvez pas regarder ce que l'utilisateur faisait réellement. Vérifiez qu'il marche à l'étape 7 avant de considérer que le flux est livré.
• Une fois le flux en direct, relancez périodiquement l'outil de synthèse eval avec filter: "pass" pour faire remonter les clusters de cas d'usage dominants. C'est comment vous transformez le flux en vraies insights produit au lieu de juste un flux de notifications.