Agents IA

Agent IA : qualifier automatiquement chaque nouveau lead Zoho CRM (architecture et code)

Architecture et code d'un agent IA qui enrichit, note et résume chaque nouveau prospect Zoho CRM, puis alerte le commercial. Hébergé en Europe.

31 octobre 2026

L'essentiel

Un agent IA de qualification travaille sans qu'on le lui demande : dès qu'un prospect est créé dans Zoho CRM, il retrouve l'entreprise dans les données publiques françaises, lui attribue un score de 0 à 100 avec un résumé en français, écrit le tout dans la fiche et prévient le commercial si le prospect est chaud.

Techniquement, quatre briques suffisent : une notification du CRM, une fonction hébergée en Europe sur Zoho Catalyst, l'API publique Recherche d'entreprises et un modèle d'IA. Voici l'architecture et le code de chaque étape.

En bref

L'agent se déclenche à la création du prospect, sans clic ni conversation.
L'enrichissement par l'API Recherche d'entreprises est gratuit et sans clé, dans la limite de 7 appels par seconde.
Le modèle d'IA répond en JSON : un score borné, un résumé et une raison, contrôlés avant d'être écrits.
Chaque décision est journalisée ; le commercial garde la main.
Le coût de fonctionnement reste de l'ordre de quelques centimes au plus par prospect, hors développement.

Pourquoi un agent sur mesure, et pas seulement Zia ou un chat

Zoho propose ses propres fonctions d'IA, regroupées sous le nom Zia, et Zoho MCP permet de discuter avec son CRM depuis Claude ou ChatGPT (notre tutoriel). Si l'une de ces solutions couvre votre besoin, commencez par elle : c'est inclus dans vos licences.

Un agent sur mesure se justifie quand vous avez besoin de l'un de ces cinq points :

Agir sans qu'on le demande. Un assistant de chat ne travaille que dans une conversation. Votre prospect, lui, arrive à 3 heures du matin par le formulaire du site.
Vos propres critères. Votre cible, vos secteurs, vos tailles d'entreprise et vos signaux d'achat, écrits noir sur blanc et modifiables.
Les données publiques françaises. SIREN, code d'activité, tranche d'effectif, siège : l'API Recherche d'entreprises les fournit gratuitement.
Le choix du modèle et de l'hébergement. Un modèle européen, une fonction hébergée dans l'Union européenne, et des données qui ne voyagent pas plus que nécessaire.
Un journal de chaque décision. Pourquoi tel prospect a obtenu 82, avec quelle version des consignes, à quelle date.

L'agent décrit ci-dessous coche ces cinq cases.

L'architecture : le parcours d'un prospect

Le schéma suit un prospect de sa création à l'alerte. Les quatre étapes suivantes détaillent chaque flèche, avec son code.

Un agent sur Catalyst enrichit, note et signale chaque nouveau prospect — Parcours d’un prospect · 5 étapes, 2 services appelés

La notification réveille l'agent ; l'agent interroge deux services, écrit le résultat dans la fiche, puis prévient le commercial si le prospect est chaud.

Étape 1 : déclencher l'agent à la création du prospect

Le déclencheur est un abonnement aux notifications de Zoho CRM sur l'événement « création d'un prospect ». Zoho appelle alors l'adresse de votre fonction avec l'identifiant du prospect.

{
  "watch": [
    {
      "channel_id": "2000000000001",
      "events": ["Leads.create"],
      "notify_url": "https://VOTRE-DOMAINE-CATALYST/server/agent/notification",
      "token": "JETON_DE_VERIFICATION",
      "channel_expiry": "2026-10-26T22:00:00+02:00"
    }
  ]
}

Trois règles, détaillées dans notre guide sur les webhooks Zoho CRM :

l'abonnement expire au plus tard au bout d'une semaine : une tâche planifiée doit le renouveler chaque jour ;
le récepteur vérifie le jeton, répond immédiatement et ne fait pas le travail lui-même ;
il soumet un job par prospect, qui dispose de 15 minutes et de reprises automatiques, comme expliqué dans notre guide sur Deluge et Catalyst.

Pourquoi ne pas tout faire dans la réception ? Parce qu'un appel à un modèle d'IA prend plusieurs secondes et qu'une fonction HTTP de Catalyst s'arrête à 30 secondes. Le job, lui, absorbe les lenteurs et rejoue en cas d'échec.

Étape 2 : enrichir avec l'API Recherche d'entreprises

L'API Recherche d'entreprises, publiée par l'État, est publique et ne demande pas de clé. Elle renvoie notamment le SIREN, le code d'activité, la tranche d'effectif et le siège des entreprises françaises, dans la limite de 7 appels par seconde (data.gouv.fr). Elle ne donne pas accès aux entreprises dont les données ne sont pas diffusibles.

// Étape 2 : retrouver l'entreprise dans les données publiques (Node.js 18, fetch intégré).
// Noms de champs à confirmer dans la documentation de l'API.
async function enrichir(nomSociete, codePostal) {
  const q = encodeURIComponent([nomSociete, codePostal].filter(Boolean).join(' '));
  const reponse = await fetch(`https://recherche-entreprises.api.gouv.fr/search?per_page=1&q=${q}`);
  if (!reponse.ok) return null;                 // erreur possible au-delà de 7 appels par seconde
  const donnees = await reponse.json();
  const e = donnees.results && donnees.results[0];
  if (!e) return null;
  return {
    siren: e.siren,
    nom: e.nom_complet,
    naf: e.activite_principale,
    effectif: e.tranche_effectif_salarie,       // code INSEE de tranche, par exemple "21"
    ville: e.siege ? e.siege.libelle_commune : null
  };
}

Le piège de cette étape est l'homonymie. « Martin Conseil » existe en plusieurs exemplaires. Trois parades :

chercher par SIREN quand le formulaire le demande, c'est la seule correspondance certaine ;
sinon, ajouter le code postal à la recherche, comme dans le code ci-dessus ;
marquer la correspondance comme « à vérifier » quand le nom trouvé diffère trop du nom saisi, plutôt que d'écrire une donnée fausse.

Pour enrichir aussi les comptes existants, en masse, voir notre guide sur l'enrichissement SIREN dans Zoho CRM.

Étape 3 : noter et résumer avec un modèle d'IA

Le modèle reçoit le prospect, les données d'entreprise et vos critères, et doit répondre dans un format strict. Nous utilisons ici l'API de Mistral, un fournisseur européen, dont le mode JSON garantit une réponse au format JSON (Mistral). Le même principe vaut pour Claude ou GPT.

// Étape 3 : score, résumé et raison, en JSON, avec des garde-fous.
const CONSIGNES = `Tu qualifies des prospects B2B pour SquadNovia.
Cible : PME françaises de 10 à 250 salariés, qui utilisent ou envisagent Zoho.
Signaux forts : projet daté, besoin d'intégration, facturation électronique.
Réponds uniquement en JSON :
{"score": entier de 0 à 100, "resume": "3 phrases en français", "raison": "une phrase"}`;
async function noter(prospect, entreprise) {
  const reponse = await fetch('https://api.mistral.ai/v1/chat/completions', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${process.env.MISTRAL_API_KEY}`
    },
    body: JSON.stringify({
      model: 'mistral-small-latest',
      response_format: { type: 'json_object' },
      messages: [
        { role: 'system', content: CONSIGNES },
        { role: 'user', content: JSON.stringify({ prospect, entreprise }) }
      ]
    })
  });
  if (!reponse.ok) throw new Error(`Modèle indisponible : ${reponse.status}`);
  const json = await reponse.json();
  const r = JSON.parse(json.choices[0].message.content);
  // Garde-fous : score borné, textes forcés en chaînes, rien d'autre n'est accepté
  return {
    score: Math.max(0, Math.min(100, Math.round(Number(r.score) || 0))),
    resume: String(r.resume || '').slice(0, 1000),
    raison: String(r.raison || '').slice(0, 300)
  };
}

Trois choix comptent plus que le modèle lui-même :

Des critères écrits. La qualité du score dépend de la précision des consignes. Versionnez-les, comme du code.
Le minimum de données. Envoyez la société, la source et le message du formulaire ; évitez le nom, l'e-mail et le téléphone de la personne, qui n'apportent rien au score.
Un contrôle de la sortie. Un modèle peut se tromper de format ou de bornes. Le code ne fait jamais confiance à la réponse sans la vérifier.

Étape 4 : écrire dans le CRM et alerter l'équipe

Le résultat est écrit dans des champs dédiés du prospect, puis un message part dans Zoho Cliq si le score dépasse le seuil fixé.

// Étape 4 : écriture dans Zoho CRM (API v8) et alerte Cliq.
// Score_IA, Resume_IA, SIREN et Code_NAF sont des champs personnalisés à créer sur les prospects.
async function ecrire(idProspect, entreprise, note, jeton, apiDomain) {
  const corps = {
    data: [{
      id: idProspect,
      Score_IA: note.score,
      Resume_IA: note.resume,
      SIREN: entreprise ? entreprise.siren : null,
      Code_NAF: entreprise ? entreprise.naf : null
    }],
    trigger: []                                   // ne redéclenche aucun workflow
  };
  const reponse = await fetch(`${apiDomain}/crm/v8/Leads`, {
    method: 'PUT',
    headers: { Authorization: `Zoho-oauthtoken ${jeton}`, 'Content-Type': 'application/json' },
    body: JSON.stringify(corps)
  });
  if (!reponse.ok) throw new Error(`Écriture CRM refusée : ${reponse.status}`);
}
async function alerter(note, societe) {
  if (note.score < 70) return;                    // seuil à ajuster
  await fetch(process.env.CLIQ_WEBHOOK_URL, {     // URL du canal Cliq avec son jeton de webhook (zapikey)
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ text: `Prospect chaud (${note.score}/100) : ${societe}. ${note.raison}` })
  });
}

Et la fonction Job qui enchaîne les quatre étapes pour un prospect :

// Fonction Job Catalyst : qualifie un prospect de bout en bout et journalise la décision.
// obtenirAccesZoho() et lireProspect() dépendent de votre gestion du jeton OAuth.
module.exports = async (jobRequest, context) => {
  const id = jobRequest.getJobParam('lead_id');
  try {
    const { jeton, apiDomain } = await obtenirAccesZoho();
    const p = await lireProspect(id, jeton, apiDomain);   // GET /crm/v8/Leads/{id}
    const entreprise = await enrichir(p.Company, p.Zip_Code);
    const note = await noter(
      { societe: p.Company, source: p.Lead_Source, message: p.Description },
      entreprise
    );
    await ecrire(id, entreprise, note, jeton, apiDomain);
    await alerter(note, p.Company);
    console.log(JSON.stringify({ id, score: note.score, raison: note.raison, consignes: 'v3' }));
    context.closeWithSuccess();
  } catch (erreur) {
    console.log(erreur.message);
    context.closeWithFailure();                    // nouvel essai selon la configuration du job
  }
};

Le trigger: [] est important : sans lui, l'écriture du score peut déclencher les workflows configurés sur les prospects, et créer des effets en cascade.

Gouvernance : coûts, RGPD, AI Act et journal

Un agent qui écrit dans votre CRM sans supervision doit être gouverné comme un collaborateur : un périmètre, un budget, une trace.

Les coûts de fonctionnement. L'API Recherche d'entreprises est gratuite. Un petit modèle d'IA traite un prospect pour quelques centimes au plus. Catalyst dispose d'un palier gratuit mensuel. Chaque prospect consomme deux ou trois crédits d'API du CRM. Le vrai coût est le développement et le réglage des critères, pas l'exécution.

Le RGPD. Même en B2B, un prospect est souvent une personne identifiable. Quatre précautions :

documenter le traitement dans votre registre, avec sa base légale, en général l'intérêt légitime pour la prospection B2B ;
informer les prospects, dans votre politique de confidentialité, de l'enrichissement et de la notation automatiques ;
n'envoyer au modèle que les données utiles au score, comme vu à l'étape 3 ;
choisir des fournisseurs qui traitent les données dans l'Union européenne, ou encadrer les transferts.

L'AI Act. Noter des prospects pour prioriser des relances commerciales ne figure pas, a priori, parmi les usages à haut risque du règlement. Gardez néanmoins la décision finale humaine : le score oriente le commercial, il ne décide pas à sa place. Notre guide agents IA, RGPD et AI Act détaille ces points.

Le journal. Chaque exécution écrit le score, la raison et la version des consignes. Une fois par semaine, relisez un échantillon de vingt prospects : c'est ainsi qu'on détecte une dérive avant qu'elle coûte des ventes.

Voir l'agent fonctionner

Le plus simple pour juger est de voir un prospect traverser les quatre étapes, du formulaire à l'alerte.

Un agent de qualification dans votre Zoho CRM

SquadNovia adapte l'agent à vos critères, l'héberge en Europe, branche vos notifications et vous livre le journal de décisions. Mise en place sur devis selon le périmètre, puis un suivi mensuel.

Voir la démo et en parler

Le même modèle s'applique à d'autres événements : un ticket qui arrive dans Zoho Desk, un appel terminé dans Ringover ou Aircall, un devis sans réponse depuis dix jours.

Questions fréquentes

Combien coûte un agent de qualification de leads pour Zoho CRM ?

Le fonctionnement coûte peu : quelques centimes au plus par prospect pour le modèle d'IA, l'enrichissement est gratuit et Catalyst a un palier gratuit. L'essentiel du coût est la mise en place et le réglage des critères.

Faut-il obligatoirement Zoho Catalyst ?

Non. N'importe quel serveur capable de recevoir les notifications et de faire tourner une file de tâches convient. Catalyst a l'avantage d'être intégré à Zoho et de proposer un hébergement européen.

Quel modèle d'IA choisir ?

Un petit modèle suffit pour noter et résumer un prospect. Privilégiez un fournisseur qui traite les données dans l'Union européenne, ou encadrez le transfert si vous choisissez Claude ou GPT.

Que se passe-t-il si l'IA se trompe ?

Le score oriente, il ne décide pas. Le commercial voit la raison donnée par le modèle, et la revue hebdomadaire d'un échantillon permet de corriger les consignes.

L'API Recherche d'entreprises est-elle vraiment gratuite ?

Oui. Elle est publique, ne demande pas de clé et accepte jusqu'à 7 appels par seconde. Elle ne couvre pas les entreprises dont les données ne sont pas diffusibles.

Peut-on faire de même avec Zia ?

Zia couvre une partie des besoins sans développement. Un agent sur mesure se justifie pour vos propres critères, les données publiques françaises, le choix du modèle et la journalisation complète.

Sources

Pages consultées les 20 et 21 octobre 2026.