Agents

Un agent est l'objet de configuration central dans Aethex. Il contient la voix, la langue, le system prompt et les paramètres de comportement que le pipeline utilise sur chaque appel.

Démarrage rapide

Créez votre premier agent avec un seul appel POST /agents :

create_agent.py

python

import os, requests

resp = requests.post(
    "https://api.aethexai.com/api/v1/agents",
    headers={"X-API-Key": os.environ["AETHEX_API_KEY"]},
    json={
        "name": "Acme Storage Support",
        "system_prompt": "You are Maya, a friendly support agent for Acme Storage. Help with bookings, payments, and unit availability. Keep replies short.",
        "first_message": "Hi, thanks for calling Acme Storage. This is Maya. How can I help?",
        "voice_id": "Femi",
        "language": "english",
    },
)
agent = resp.json()
print(f"Created agent: {agent['id']}")

Sauvegardez l'id retourné — vous l'utiliserez pour assigner un numéro de téléphone, déclencher des appels et gérer l'agent.

Comment les agents gèrent les appels

Une fois créé, un agent peut gérer les appels de trois manières :

Entrant. Assignez l'agent à un numéro de téléphone enregistré. Tous les appels entrants vers ce numéro sont acheminés vers l'agent.
Sortant. Déclenchez des appels via POST /calls/trigger avec agent_id et un to_number.
WebRTC. Démarrez une session navigateur ou mobile via le flux appels WebRTC — aucun numéro de téléphone nécessaire.

Les agents peuvent également utiliser des outils pour appeler vos propres points d'accès HTTPS en cours d'appel, et puiser des réponses fondées dans une base de connaissances que vous téléchargez.

Champs principaux

namestringrequis
Nom lisible par l'humain. Utilisé dans les tableaux de bord et les journaux.
system_promptstringrequis
Les instructions que le LLM reçoit avant chaque appel. Définit le personnage, le ton et le flux d'appel.
voice_idstringrequis
Voix à utiliser pour la synthèse vocale. Doit correspondre à la langue de l'agent. Utilisez GET /voices pour parcourir le catalogue.
first_messagestringoptionnel
Ligne d'ouverture optionnelle que l'agent prononce dès que l'appel se connecte. Si omise, l'agent attend que l'appelant parle en premier.
languagestringrequis
Langue que l'agent parle et comprend. Affecte la reconnaissance vocale, la synthèse vocale et la langue de réponse du LLM.
dialect_stylestringoptionnel
Variante dialectale régionale optionnelle. Les valeurs disponibles dépendent de la langue.

Rédiger le system prompt

Le system prompt est le champ le plus important sur un agent. Incluez :

Rôle et personnage. Qui est l'agent, quelle entreprise il représente et comment il s'appelle.
Ton et style. À quel point il est formel, concis et quel vocabulaire utiliser.
Ce qu'il ne faut pas faire. Ce que l'agent ne doit jamais dire ou faire (mentions de concurrents, spéculations sur les prix, conseils juridiques).
Instructions pour les outils. Quand et comment invoquer chaque outil. Par exemple : « Appelez lookup_order quand l'utilisateur mentionne un numéro de commande. »

Consultez le Démarrage rapide pour un exemple de prompt qui aborde les quatre éléments.

Paramètres de comportement

Ces champs réglent le LLM et le comportement de gestion des appels :

temperaturenumberoptionnel
Température d'échantillonnage du LLM (0–2). Des valeurs plus basses rendent les réponses plus prévisibles. Par défaut 0,7. Les modèles de raisonnement d'OpenAI (la série o et la famille gpt-5) n'acceptent pas de température : elle est ignorée pour eux.
max_tokensintegeroptionnel
Nombre maximum de tokens dans une seule réponse du LLM. Contrôle la verbosité. Par défaut 300.
max_duration_secondsintegeroptionnel
Limite stricte de durée d'appel en secondes (30–3 600). L'agent raccroche après cette limite quel que soit l'état de la conversation.
transfer_phone_numberstringoptionnel
Numéro de destination pour l'outil intégré transfer_to_number. Requis pour activer les transferts.
transfer_modestringoptionnel
warm (par défaut) : l'agent briefe la personne vers qui il transfère, puis quitte l'appel. conference : il reste en ligne sans parler, et la suite de l'appel est enregistrée et transcrite (les propos de cette personne apparaissent comme tours human_agent), dans la limite des réglages d'enregistrement et de transcription de l'agent. Le mode conférence exige un appel SIP et un trunk sortant pour le transfert ; les appels Twilio et Teams sont transférés en mode warm.
keypad_capture_enabledbooleanoptionnel
Capture des touches du clavier (DTMF) pendant les appels téléphoniques : lorsqu'un appelant saisit un numéro de carte ou de référence, l'agent lit les chiffres exactement au lieu de les transcrire depuis la parole, puis les relit pour confirmation. Activé par défaut ; définissez false pour le désactiver. Uniquement Twilio et SIP, car les appels par navigateur n'ont pas de clavier.

Remarque

La température affecte la naturalité par rapport à la prévisibilité. Pour les agents de service client scriptés, 0,3–0,5 est un bon point de départ.

Cycle de vie

Mettre à jour

PATCH/agents/{id}

Modifiez n'importe quel champ à tout moment via PATCH. Les changements prennent effet lors du prochain appel — les sessions en cours ne sont pas affectées.

Supprimer

DELETE/agents/{id}

Supprime l'agent et le dissocie de tous les numéros de téléphone enregistrés. Les appels actifs se terminent normalement.