# CONSTRUIRE UN AGENT DE PROSPECTION : CONTEXTE ET MARCHE À SUIVRE

Tu vas m'accompagner pas à pas pour monter un agent de prospection qui tourne
chez moi. Ce document contient le montage complet et les règles issues de six
mois d'exploitation d'un système réel, avec les chiffres mesurés qui les
fondent.

## COMMENT TU TRAVAILLES AVEC MOI

Tu ne me rends pas un plan d'un bloc. Tu m'accompagnes :

1. Demande-moi d'abord ce que je vise, ce que j'ai déjà (une liste de leads ?
   un canal de discussion ? une clé de modèle ?) et sur quel marché je vends.
2. Déroule la section B étape par étape. Une étape à la fois. À chaque étape,
   donne-moi la commande ou le fichier exact, adapté à mon cas, puis
   **attends que je te dise que ça a marché** avant de passer à la suivante.
3. Quand une étape échoue, diagnostique avant de proposer autre chose. Les
   pannes fréquentes sont listées à la fin de chaque étape.
4. Les sections D à F sont des contraintes, pas des suggestions. Si une de mes
   demandes en contredit une, dis-le moi et cite le chiffre qui la fonde avant
   de faire ce que je demande.

Système de référence : 937 leads analysés un par un entre mai et août 2026, pour
179 verdicts positifs, soit 19,1 %. Tous les taux cités sont des taux de verdict
positif mesurés sur cette population.

## A. LE PÉRIMÈTRE : CE QU'ON MONTE, ET CE QU'ON NE MONTE PAS

CE QU'ON MONTE EN UNE HEURE.
Un agent qui tourne chez moi, lit une liste de leads dans un fichier, en analyse
un pour de vrai (profil, entreprise, site, actualité), et pose son verdict
motivé dans un canal de discussion où je réponds un mot.

CE QU'ON NE MONTE PAS AUJOURD'HUI.
L'ingestion automatique des signaux, le filtre déterministe en amont,
l'enrichissement payant, les tâches planifiées, la boucle de calibration. C'est
la section G, et elle vient après.

Ne me propose pas de construire tout le système d'un coup. Un agent qui juge un
lead et me le pose sous les yeux vaut mieux qu'un pipeline complet qui ne tourne
pas.

## B. LE MONTAGE, ÉTAPE PAR ÉTAPE

B1. INSTALLER LE RUNTIME.
L'agent tourne sur Hermès (NousResearch), open source, licence MIT, dans un
conteneur Docker. Deux commandes :

    mkdir -p ~/.hermes
    docker run -it --rm -v ~/.hermes:/opt/data nousresearch/hermes-agent setup

L'assistant interactif demande les clés d'API et les écrit dans ~/.hermes/.env.
Il propose aussi de configurer un canal de discussion : on peut passer, on le
traite en B5.
Panne fréquente : sur un serveur, se connecter en SSH et pas par la console web
de l'hébergeur, qui abîme les caractères spéciaux au collage. Une clé tronquée
ne dit pas son nom.

B2. COMPRENDRE OÙ VIT L'ÉTAT.
Tout ce qui est modifiable vit sous ~/.hermes : config, .env, profils, skills,
mémoires, sessions, journaux. C'est le seul dossier que le conteneur voit.
Conséquence pratique : on n'édite jamais de code, on dépose des fichiers.
Pour ouvrir une session et vérifier que l'agent répond :

    docker run -it --rm -v ~/.hermes:/opt/data nousresearch/hermes-agent

B3. CHOISIR LE MODÈLE.
Passer par une passerelle multi-modèles plutôt qu'un fournisseur en direct :
on change de modèle sans toucher à la configuration, et on peut comparer un coût
par lead entre deux modèles sur la même tâche.
Règle de coût, voir F1 : plafonner les jetons en sortie dès maintenant.

B4. ÉCRIRE LES COMPÉTENCES.
Voir la section C pour le format, qui est l'endroit où presque tout le monde se
trompe. Trois compétences suffisent pour l'heure 1 :
  - analyser-un-lead : juge et rend un verdict motivé
  - ecrire-le-message : rédige le premier message à partir du verdict
  - poster-le-verdict : met en forme la carte et attend la réponse humaine

B5. BRANCHER LE CANAL DE DISCUSSION.
Sur Slack, Hermès génère le manifeste. Il n'y a pas de commande `hermes` sur la
machine, seulement l'image : toute sous-commande se passe à l'image.

    docker run --rm -v ~/.hermes:/opt/data \
      nousresearch/hermes-agent slack manifest --agent-view --write

Puis, dans Slack : créer l'application avec ce manifeste, activer Socket Mode et
générer un jeton d'application (préfixe xapp-, portée connections:write),
installer l'application pour obtenir le jeton de bot (préfixe xoxb-).
Socket Mode passe par un WebSocket, donc ça marche derrière un pare-feu sans
ouvrir de port.
Les deux jetons vont dans ~/.hermes/.env AVANT de démarrer la passerelle, en
mode ajout et pas en écrasement :

    cat >> ~/.hermes/.env <<'FIN'
    SLACK_APP_TOKEN=xapp-...
    SLACK_BOT_TOKEN=xoxb-...
    FIN

Panne fréquente : écraser le .env au lieu de le compléter. Une commande qui
remplace un fichier de secrets sans le dire nous a coûté une nuit de production.

B6. DÉMARRER LA PASSERELLE.

    docker run -d --name hermes --restart unless-stopped \
      -v ~/.hermes:/opt/data -p 8642:8642 \
      nousresearch/hermes-agent gateway run

Puis inviter le bot dans un canal et prouver un aller-retour réel.

B7. DONNER LA LISTE DE LEADS.
Un fichier avec, au minimum : la personne, son intitulé, l'entreprise, et LA
TAILLE DE L'ENTREPRISE (voir E1, c'est la donnée qui décide de tout).
Le déposer dans ~/.hermes/, seul dossier visible du conteneur. Un fichier laissé
ailleurs est invisible pour l'agent, et c'est le blocage le plus fréquent.

B8. VÉRIFIER QUE ÇA MARCHE VRAIMENT.
Trois contrôles dans l'ordre, chacun inutile si le précédent échoue :
  1. La passerelle tourne : `docker logs hermes` ne boucle pas sur une erreur.
     Si elle échoue, un jeton est absent ou tronqué.
  2. Le bot répond dans le canal. Sinon il n'y est pas invité, ou Socket Mode
     est resté désactivé.
  3. La compétence se déclenche et LE VERDICT CITE UN FAIT ABSENT DU FICHIER.
     C'est le seul contrôle qui prouve quelque chose : un agent qui reformule la
     fiche n'a pas cherché, il a répondu.

## C. LE FORMAT D'UNE COMPÉTENCE, ET LE PIÈGE

Une compétence est UN DOSSIER contenant un fichier SKILL.md, rangé sous
~/.hermes/skills/<catégorie>/<nom>/. Elle devient automatiquement une commande :
un dossier `analyser-un-lead` donne `/analyser-un-lead`.

Le frontmatter n'a que DEUX champs obligatoires, `name` et `description`. Les six
compétences du système de référence n'en portent aucun autre : ni version, ni
catégorie, ni métadonnées.

LE PIÈGE, ET IL EST COÛTEUX. La description n'est pas un résumé, c'est le
ROUTAGE. C'est tout ce que l'agent voit pour décider s'il charge la compétence :
il liste les noms et les descriptions, puis il ouvre celle qui correspond. Une
description d'une ligne produit un agent qui n'appelle jamais la bonne
compétence au bon moment, et aucun test ne le montre.

Une bonne description fait 400 à 900 caractères et dit, dans cet ordre : ce que
la compétence fait, ce qu'elle exige en entrée, ce qu'elle refuse de faire, puis
une phrase « Use when » qui décrit la situation de déclenchement.

Squelette :

    ---
    name: analyser-un-lead
    description: [400 à 900 caractères, voir ci-dessus]
    ---

    # Titre

    ## Quand l'utiliser
    ## Procédure
    (étapes numérotées, chacune disant ce qu'elle coûte)
    ## Vérification
    (comment savoir que la sortie est bonne)

Quand tu m'aides à écrire une compétence, écris la description EN DERNIER, une
fois le corps connu, et vérifie qu'elle fait bien 400 caractères au moins.

## D. LES QUATRE DÉCISIONS D'ARCHITECTURE

D1. SÉPARER LE VOLUME DU JUGEMENT.
Deux moitiés qui ne se mélangent jamais. Une infrastructure déterministe qui
ingère, enrichit et disqualifie en masse. Un agent qui juge, cherche et rédige,
un lead à la fois. Le traitement en volume s'écrit en code ; le jugement par
unité va au modèle. Un modèle local sans coût par appel est acceptable dans une
boucle ; une API facturée par ligne ne l'est jamais.
Point de jonction unique entre les deux moitiés : la base de données.

D2. DISQUALIFIER LARGE AU LIEU DE QUALIFIER SERRÉ.
Le filtre amont ne sélectionne pas les bons leads : il tue les certitudes
négatives et laisse passer tout le reste. Raison : un bon lead écarté par une
règle serrée ne se manifeste jamais, donc son coût est invisible. Chaque règle
doit répondre à « qu'est-ce que je suis certain de ne pas vouloir ».
Mesure : sur 170 décideurs correctement rattachés, 150 sont écartés avant
l'agent, dont 108 pour une structure de trois salariés ou moins.

D3. L'HUMAIN VALIDE, L'AGENT ENVOIE.
L'agent écrit et poste un verdict. Il n'envoie jamais de lui-même. Trois
garde-fous obligatoires dès le premier message : fenêtre horaire locale du
destinataire, plafond quotidien par compte, protection anti double-envoi.
Ne propose pas de validation par emoji : elle ne permet pas de corriger le
brouillon, donc elle pousse à valider des messages qu'on aurait réécrits.

D4. FERMER LA BOUCLE SUR LES RETOURS.
Stocker chaque retour humain avec sa raison, en texte libre, dès le premier
jour. Un retour non consigné au moment du verdict est définitivement perdu :
c'est la seule matière qui ne se rattrape pas rétroactivement.

## E. LES RÈGLES MESURÉES, CIBLAGE ET MESSAGE

E1. SANS LA TAILLE DE L'ENTREPRISE, L'ANALYSE NE SERT À RIEN.
34 % de verdicts positifs quand la firmographie est connue, 5 % quand elle
manque, et elle manquait sur 52 % des analyses. La taille est une condition
d'entrée dans l'analyse, pas une donnée d'agrément. Si elle manque : aller la
chercher, ou mettre le lead en file d'attente.

E2. TOUTES LES PORTES D'ENTRÉE NE SE VALENT PAS.
Signal d'achat externe (une PME qui recrute un profil IA) : 70,0 % sur 20
analyses. Visite de profil : 23,3 % sur 103. Engagement sur le contenu : 17,5 %
sur 773. Réacteur d'un leader suivi : 12,0 % sur 25.
Conserver l'origine du signal sur chaque fiche dès le départ, sinon ce découpage
est impossible rétroactivement. Citer tout taux avec son échantillon.

E3. UNE DONNÉE MANQUANTE COÛTE MOINS CHER QU'UNE DONNÉE FAUSSE.
Entre un trou et un rattachement douteux, choisir le trou : un faux rattachement
fait entrer le lead avec un mauvais effectif et un mauvais secteur, et personne
ne le verra jamais.

E4. UN FILTRE EN SOUS-CHAÎNE TUE LE MEILLEUR SEGMENT.
Un motif de disqualification se pose en début de mot, jamais en sous-chaîne. Le
motif « formation » touchait 97 intitulés, dont 68 où le mot était
« transformation », qui pesaient 20 verdicts positifs. Avant de brancher un
filtre, sortir la liste des intitulés qu'il tue et la lire.

E5. LE COMMENTAIRE PRÉDIT UN PEU MIEUX QUE LA RÉACTION.
18,9 % contre 13,5 %, à porte d'entrée égale. Un tiers de mieux en relatif, et
l'écart reste dans le bruit de l'échantillon. Séparer les deux signaux dans la
priorisation, ne pas construire de règle dure dessus.

E6. UNE INVITATION DE CONNEXION NE FAIT PAS OFFICE DE PREMIER MESSAGE.
Le message direct à une relation de premier degré tourne autour de 12 % de
réponses ; la note d'invitation, envoyée avant acceptation, n'en a produit
aucune. Dissocier : invitation sans note, message après acceptation.

E7. CE QUE DISENT LES RÉPONDANTS NE DÉCRIT PAS LA POPULATION.
Biais du survivant. Un quart des répondants déclaraient avoir quitté leur
entreprise ; sur un échantillon de ceux qui n'avaient rien dit, environ 1 %.
Avant de dimensionner une correction sur ce que disent les répondants, mesurer
la même chose sur un échantillon silencieux.

## F. LES GARDE-FOUS AVANT DE LAISSER TOURNER

F1. LE COÛT SUIT LE CONTEXTE MULTIPLIÉ PAR LES TOURS.
560 000 jetons par lead au départ, ramenés à 0,20 ou 0,40 dollar après avoir
remplacé trois requêtes par une jointure, plafonné les jetons en sortie et
compressé la procédure. Un outil de plus dans la boucle coûte moins cher qu'une
procédure de mille mots de plus.

F2. UNE INSTRUCTION DURCIE PEUT PARALYSER L'AGENT.
Trois durcissements successifs ont produit trois cycles de réponse vide puis
l'abandon. Préférer une règle permissive avec une friction résiduelle à une
règle parfaite qui bloque tout, et tester chaque durcissement sur un cas réel
avant de l'empiler sur le précédent.

F3. LE MONITORING SE POSE AVANT LE PREMIER CRON.
13 planifications sur 13 étaient sans gestionnaire d'erreur, et l'alerte n'avait
jamais été déclenchée en conditions réelles. Poser une sentinelle indépendante
qui détecte les ABSENCES autant que les échecs : une tâche qui échoue est
visible, une tâche qui ne part pas ne laisse aucune trace.
Doctrine associée : jamais de réessai automatique sur un appel facturé.

F4. MESURER LE RENDEMENT AVANT DE CÂBLER.
Chiffrer une brique payante sur un petit lot avant de la mettre dans une boucle.
Un rattrapage testé sur 20 sociétés pour 0,186 dollar a résolu 5 identités et
récupéré zéro effectif : le code est livré, testé, et volontairement pas branché.

## G. LA SUITE, UNE FOIS L'AGENT DEBOUT

G1. La mesure, AVANT tout enrichissement : combien entrent, combien deviennent
    des verdicts positifs, et d'où ils viennent. Fini quand un chiffre s'affiche
    et qu'on sait quelle requête le produit. C'est l'étape le plus souvent faite
    en dernier, et la plus coûteuse à retarder.
G2. L'ingestion automatique, une seule porte pour commencer, celle où la donnée
    est déjà propre. Les suivantes se branchent sur le même calcul.
G3. Le filtre déterministe en amont, écrit en négatif (D2).
G4. La boucle sur les retours (D4).
G5. L'hébergement : un agent sur un portable s'arrête avec le portable. Pour
    qu'il tourne vraiment il lui faut une machine qui ne dort pas, à partir de
    la même image, avec un volume monté sur /opt/data qui garde tout l'état.

## H. CE QUE TU FAIS MAINTENANT

Commence par me poser tes questions de la section « Comment tu travailles avec
moi ». Ne déroule pas B1 avant d'avoir mes réponses.

Et sache ce que tu ne peux pas savoir : si ces chiffres valent pour mon marché.
Ils viennent d'un seul système, sur six mois, sur des dirigeants de PME
françaises. Traite-les comme un point de départ, et propose-moi la mesure qui me
dirait s'ils tiennent chez moi.

MA DEMANDE :
[écris ta demande ici, ou laisse vide pour qu'il commence par ses questions]