Agents IA

Les agents IA conduisent les entretiens vocaux. Chaque agent a une voix, un ton, une langue et des instructions personnalisées. Ils peuvent être globaux (partagés entre toutes les offres) ou liés à une offre précise.

Scope requis : agents:read pour la lecture, agents:write pour la création et la modification.

Vue d'ensemble

Voix OpenAI (provider: "openai")

Valeur	Genre	Description
marin✨	Féminine	Voix féminine naturelle et expressive - Qualité supérieure
cedar✨	Masculine	Voix masculine naturelle et expressive - Qualité supérieure
nova	Féminine	Voix féminine chaleureuse et professionnelle
shimmer	Féminine	Voix féminine douce et accueillante
coral	Féminine	Voix féminine claire et dynamique
sage	Féminine	Voix féminine posée et réfléchie
ballad	Féminine	Voix féminine mélodieuse et apaisante
echo	Masculine	Voix masculine profonde et autoritaire
onyx	Masculine	Voix masculine grave et professionnelle
ash	Masculine	Voix masculine équilibrée et naturelle
verse	Masculine	Voix masculine articulée et expressive
alloy	Neutre	Voix neutre et polyvalente
fable	Neutre	Voix neutre narrative et engageante

Voix ElevenLabs 🇫🇷 (provider: "elevenlabs")

Voix françaises natives haute qualité

Valeur	Genre	Description
kev✨	Masculine	Voix masculine française naturelle et engageante
souni✨	Féminine	Voix féminine française chaleureuse et professionnelle
nova_el	Féminine	Voix féminine française expressive et dynamique
peter	Masculine	Voix masculine française claire et rassurante
jeremy	Masculine	Voix masculine française authentique et posée
camille	Féminine	Voix féminine française élégante et confiante

Tons disponibles (tone)

Valeur	Description
professional	Formel, direct — défaut recommandé
friendly	Convivial, abordable
formal	Très formel, vouvoiement strict
casual	Détendu, familier
empathetic	Bienveillant, à l'écoute

Niveaux de vigilance (suspicionLevel)

Valeur	Comportement
0	Désactivé — aucune détection
1	Faible — alertes discrètes (défaut)
2	Moyen — relances si suspect
3	Maximal — interruption possible

Les voix ElevenLabs (kev, souni, camille…) offrent une qualité supérieure pour le français natif. Les voix OpenAI marin et cedar ✨ sont les plus récentes et recommandées pour un usage multilingue.

Lister les agents

GET/api/agents

Retourne tous les agents de l'organisation, avec le nombre d'entretiens et de configurations associés.

Query Parameters

Paramètre	Type	Requis	Description
`jobId`	string	Non	Filtrer par offre d'emploi.
`isDefault`	boolean	Non	true pour obtenir uniquement les agents par défaut.

Requête

Réponse 200

Obtenir un agent

GET/api/agents/:id

Retourne le détail d'un agent avec ses 20 derniers entretiens et ses configurations associées.

Path Parameters

Paramètre	Type	Requis	Description
`id`	string	Oui	Identifiant de l'agent.

Requête

Réponse 200

Créer un agent

POST/api/agents

Crée un nouvel agent IA pour l'organisation.

Body Parameters

Paramètre	Type	Requis	Description
`name`	string	Oui	Nom affiché de l'agent (ex. "Alexandre").
`voice`	string	Non	Voix TTS OpenAI (voir tableau) — défaut : nova.
`tone`	string	Non	Ton conversationnel (voir tableau) — défaut : professional.
`language`	string	Non	Langue de l'agent : fr \| en \| es \| de \| it — défaut : fr.
`instructions`	string	Non	Instructions libres intégrées au prompt système. Indique à l'agent son rôle, le secteur, les sujets prioritaires.
`suspicionLevel`	integer	Non	Niveau de vigilance anti-triche : 0 à 3 — défaut : 1.
`jobId`	string	Non	Lier l'agent à une offre d'emploi (optionnel — null = agent global).
`isDefault`	boolean	Non	Définir comme agent par défaut pour l'offre liée — défaut : false.
`isGlobal`	boolean	Non	Rendre l'agent disponible pour toutes les offres de l'organisation — défaut : false.
`config`	object	Non	Configuration avancée (rubric, style, guidelines, persona) — voir exemple ci-dessous.

Requête — agent RH complet

Réponse 201

Mettre à jour un agent

PUT/api/agents/:id

Met à jour un ou plusieurs champs d'un agent. Tous les champs sont optionnels — seuls les champs fournis sont modifiés.

Body Parameters

Paramètre	Type	Requis	Description
`name`	string	Non	Nouveau nom de l'agent.
`voice`	string	Non	Nouvelle voix (voir tableau des voix disponibles).
`tone`	string	Non	Nouveau ton conversationnel.
`language`	string	Non	Nouvelle langue.
`instructions`	string	Non	Nouvelles instructions système.
`suspicionLevel`	integer	Non	Nouveau niveau de vigilance (0-3).
`isEnabled`	boolean	Non	Activer / désactiver l'agent.
`isDefault`	boolean	Non	Redéfinir comme agent par défaut.
`config`	object	Non	Nouvelle configuration avancée (remplace entièrement l'existante).

Requête — changer la voix et le ton

Réponse 200

PATCH /api/agents/:id est un alias de PUT /api/agents/:id — ils ont le même comportement.

Supprimer un agent

DELETE/api/agents/:id

Supprime un agent. Si des entretiens lui sont associés, la suppression est logique (isDefault → false, agent conservé en base).

Requête

Réponse 200 — suppression définitive

Réponse 200 — suppression logique (entretiens existants)

Questions fréquentes

voice est la voix de synthèse vocale OpenAI (timbre, accent) — par exemple "echo" (masculine, RP) ou "nova" (féminine). tone est la posture conversationnelle de l'agent (professional, friendly, formal…). Les deux sont indépendants et cumulables.

Oui. Plusieurs agents peuvent être liés au même jobId. Un seul peut avoir isDefault: true par offre. Si un entretien ne spécifie pas d'agentId, l'agent par défaut de l'offre est utilisé.

config est un objet JSON libre qui peut stocker : la rubrique d'évaluation (rubric), le style de conversation (style), des directives supplémentaires (guidelines) et la personnalité de l'agent (persona.name, persona.traits). Ce champ est transmis directement au prompt système de l'agent.

Si l'agent a des entretiens associés, la suppression est logique : l'agent est conservé mais isDefault est mis à false. Si aucun entretien n'y est attaché, l'agent est supprimé définitivement.