Créez votre premier agent vocal avec l'API Aethex

Avant d'écrire la moindre ligne de code : parlez à un agent en direct dès maintenant via le widget de Chat Vocal sur aethexai.com.

Un restaurant bondé dispose d'un téléphone qui ne s'arrête jamais de sonner. La plupart des appels concernent toujours les mêmes requêtes : réserver une table, modifier une réservation, confirmer notre venue pour jeudi, demander les horaires d'ouverture. Chaque appel représente un chiffre d'affaires potentiel. Mais chaque appel interrompt un membre de l'équipe en plein service, et les appels qui finissent sur messagerie se soldent généralement par une réservation chez un concurrent.

C'est pourquoi Samuel, le propriétaire, a développé un agent pour répondre au téléphone. Pas un menu interactif du type « tapez 1 », mais un agent conversationnel nommé Esther qui échange avec les clients, consulte le carnet de réservation en temps réel et enregistre les réservations. Voici l'intégralité du projet, y compris la partie qui reste habituellement floue : ce qui se passe concrètement lorsque l'agent utilise un outil.

Sur Aethex, un agent est un objet simple : une voix, une langue, quelques paramètres et un prompt système lu avant chaque appel. Le pipeline de traitement de la parole sous-jacent – qui convertit l'audio en texte, détermine la réponse et la synthétise en voix – est entièrement géré. Il est conçu pour s'adapter naturellement à la langue et au dialecte de vos clients plutôt que d'utiliser une voix standardisée. La seule partie que vous devez rédiger est le prompt système. C'est là qu'Esther prend vie.

Rédiger le prompt

La documentation propose une structure en quatre parties : l'identité de l'agent, sa charte vocale, ses limites strictes et les cas d'utilisation des outils. Le travail consiste à enrichir ces sections avec des instructions précises plutôt qu'avec des adjectifs vagues. (Remplacez l'espace réservé par le nom de votre propre restaurant.)

# Identité
Vous êtes Esther, standardiste pour [Nom du restaurant]. Vous aidez les clients à réserver, confirmer et modifier leurs réservations, et vous répondez aux questions courantes sur les horaires, l'adresse et le menu. Vous êtes chaleureuse, efficace et agréable.

# Style
Limitez vos réponses à une ou deux phrases courtes et posez une seule question à la fois. Parlez naturellement : utilisez des formulations simples et directes. Prononcez les dates et les heures comme à l'oral, par exemple "jeudi à dix-neuf heures" et jamais "Jeu 19:00". Pas de listes ni de mise en forme. Il s'agit d'une interaction parlée.

# Périmètre
Prise, confirmation et modification de réservations ; nombre de couverts ; horaires et adresse ; questions de base sur le menu ou les allergènes.

# Base de connaissances (Grounding)
Répondez aux questions sur le menu, les horaires et les conditions uniquement à l'aide de la base de connaissances et des outils ci-dessous. Si vous n'avez pas la réponse, dites-le clairement et proposez d'être rappelé. Ne devinez jamais une heure, une table ou une règle.

# Confirmer avant d'agir
Répétez les détails clés avant de valider ou de modifier quoi que ce soit (nom, date, heure et nombre de couverts) et attendez une confirmation explicite. Les noms et les numéros sont faciles à mal entendre, relisez-les systématiquement.

# Outils
Lorsqu'un client pose une question sur une réservation existante, appelez get_reservation avec son numéro de téléphone. S'il souhaite un autre créneau, appelez check_availability, puis book_reservation une fois qu'il a confirmé.

# Limites (Don'ts)
Ne promettez jamais un horaire ou une table que les outils n'ont pas validé. Pour les grands groupes ou les événements privés, proposez la confirmation par le gérant plutôt que de deviner. Si un client est mécontent ou demande à parler au responsable, dites que vous le mettez en relation et transférez l'appel

Les blocs qui semblent les plus rigides sont pourtant les plus cruciaux. Les règles de Style garantissent que les réponses d'Esther soient fluides à l'oral, car un modèle qui rédige pour un écran sonne faux lorsqu'il est lu. Le bloc Confirmer avant d'agir est indispensable car la reconnaissance vocale est performante mais pas infaillible ; un chiffre mal interprété dans un numéro de téléphone devient immédiatement une donnée erronée pour l'agent. Enfin, les consignes de Grounding empêchent Esther d'improviser une heure ou une table disponible, ce qui est le moyen le plus rapide de perdre la confiance d'un client.

Choisir une voix

La voix est le point de contact direct avec votre client, son choix requiert donc une attention particulière. La méthode list_voices retourne le catalogue d'une langue donnée ; testez-en plusieurs en leur faisant lire la phrase d'accueil d'Esther pour faire votre choix à l'oreille, et non sur un simple nom.

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

candidates = client.list_voices(language="french", limit=5)

for v in candidates:
    clip = client.synthesize_speech(
        voice_id=v.id,
        text="Bonjour et merci d'appeler, je suis Esther. Comment puis-je vous aider ?",
        language="french",
    )
    with open(f"audition_{v.name}.wav", "wb") as f:
        f.write(clip)

Sélectionnez celle qui convient le mieux à votre clientèle. Configurez la propriété language de l'agent en fonction de votre marché cible, et si la voix prend en charge des accents régionaux, ajustez le paramètre dialect_style pour correspondre au langage local de vos appelants.

voice = client.get_voice(candidates[1].id)
print(voice.name, voice.supports_dialect_style)

esther_voice = voice.id

Créer l'agent

Une fois le prompt rédigé et la voix sélectionnée, l'initialisation se fait en un seul appel. Les méthodes d'écriture retournent du JSON brut, récupérez l'identifiant directement via l'accès par clé.

agent = client.create_agent(
    name="Front Desk Agent",
    system_prompt=SYSTEM_PROMPT,        # le prompt défini ci-dessus
    first_message="Bonjour et merci d'appeler, je suis Esther. Comment puis-je vous aider ?",
    voice_id=esther_voice,
    language="french",
    temperature=0.4,
)
agent_id = agent["id"]

Deux paramètres sont ici essentiels. Le first_message est la phrase prononcée par Esther dès la connexion pour éviter tout silence gênant. De plus, une temperature=0.4 permet de s'assurer qu'Esther respecte strictement ses consignes ; la valeur par défaut est de 0.7, mais pour un agent connecté à un système de réservation réel, une plage comprise entre 0.3 et 0.5 s'avère plus stable. Si l'agent commence à improviser des informations, réduisez cette valeur avant de modifier le prompt.

Fonctionnement concret d'un appel d'outil

L'expression « l'agent appelle un outil » englobe plusieurs étapes clés. Voici le cycle complet et précis lorsqu'un client souhaite vérifier une réservation. L'ensemble de ce processus s'exécute en tâche de fond pendant l'appel, en une seconde ou deux.

1. L'appelant demande : « Notre réservation de jeudi est-elle toujours confirmée ? »

2. Esther détecte qu'elle doit utiliser get_reservation. Elle demande et valide le numéro de téléphone conformément à ses instructions, et le modèle génère un appel d'outil en passant ce numéro en argument.

3. Aethex appelle votre endpoint_url via HTTPS et lui transmet ces arguments au format JSON. Il s'agit de votre propre serveur, de votre base de données et de votre logique applicative. Aethex agit uniquement en tant que transporteur.

4. Votre point d'accès recherche la réservation et renvoie une réponse JSON.

5. Esther interprète ce résultat et le formule de vive voix : « Oui, une table pour quatre personnes, ce jeudi à dix-neuf heures. »

L'enregistrement de l'outil s'effectue en une seule fois. Le bloc parameters est un schéma JSON qui indique précisément au modèle les informations à collecter ; l'URL endpoint_url correspond à l'adresse qu'Aethex contactera lorsque l'outil sera sollicité par Esther.

client.add_agent_tool(
    agent_id,
    name="get_reservation",
    description="Rechercher la réservation à venir d'un client par son numéro de téléphone.",
    parameters={
        "type": "object",
        "properties": {
            "phone_number": {
                "type": "string",
                "description": "Le numéro de téléphone du client.",
            },
        },
        "required": ["phone_number"],
    },
    endpoint_url="https://api.example.com/reservations/lookup",
)

Le point d'accès de votre côté est un gestionnaire web classique. Il reçoit les arguments, effectue la recherche et retourne le JSON que vous souhaitez qu'Esther formule oralement.

# Votre serveur (simplifié). Aethex transmet ici les arguments de l'outil.
@app.post("/reservations/lookup")
def lookup_reservation(args):
    res = find_by_phone(args["phone_number"])
    return {
        "date": res.date,            # Esther traduit ces données en langage parlé
        "time": res.time,
        "party_size": res.party_size,
    }

La structure de cette réponse est entièrement libre. Esther ne lit pas directement le JSON, elle l'utilise pour construire sa réponse parlée. Intégrez de la même façon check_availability et book_reservation, et définissez le paramètre transfer_phone_number de l'agent afin que le scénario de transfert vers le responsable redirige vers une ligne réelle. Pour les données statiques comme les horaires de service, la carte ou les conditions générales, chargez directement les documents de référence dans la base de connaissances de l'agent plutôt que de surcharger le prompt ; Aethex y effectuera des recherches en temps réel lors de l'appel.

L'architecture logique est simple : le prompt définit quand faire appel à un outil, le schéma JSON détermine quelles informations transmettre, et votre point d'accès décide des données à renvoyer.

Le premier appel

Samuel n'a pas attendu un vrai client pour faire un test. La méthode d'évaluation la plus rapide consiste à diriger l'agent vers votre propre numéro de téléphone.

call = client.trigger_call(
    agent_id=agent_id,
    to_number="+14803927165",    # votre numéro
    from_number="+13125540871",  # un numéro de téléphone lié à votre compte
)
print(call["id"], call["status"])

Note importante : le numéro d'appel sortant from_number doit être préalablement configuré et vérifié sur votre compte, sans quoi l'appel sera rejeté avant d'être acheminé. Une fois ce paramètre validé, le téléphone sonne : Esther décroche, prend note d'une demande de réservation, consulte l'état des tables, valide les coordonnées et confirme la réservation.

Optimisation continue à l'usage

L'efficacité d'un prompt ne s'évalue pas uniquement à la lecture. Appelez l'agent et simulez des comportements d'utilisateurs complexes : l'interlocuteur hésitant, celui qui modifie l'heure à deux reprises ou qui s'interrompt en milieu de phrase. Si Esther manque de fluidité, assouplissez le bloc Style ; si ses réponses sont trop détaillées, demandez-lui d'aller à l'essentiel ; si elle extrapole, renforcez les directives de Grounding. La quasi-totalité des ajustements s'effectue directement dans le prompt sous forme de consignes, sans toucher au code applicatif.

Ce cycle d'itération est extrêmement rapide car il ne nécessite aucune phase de compilation. Modifiez n'importe quel paramètre instantanément : la mise à jour s'appliquera au prochain appel entrant, tandis que les communications en cours se termineront sans interruption de service.

client.update_agent(agent_id, temperature=0.35)

Déploiement en production

Une fois le comportement d'Esther validé, associez l'agent au numéro de téléphone officiel du restaurant pour la gestion des appels entrants. Ce même agent peut également initier des appels sortants à partir de vos applications ou s'intégrer directement dans votre navigateur via WebRTC, sans aucune modification de code. Le prompt, la voix et l'expérience restent identiques.

La mise en place de la chaîne de traitement de la voix est entièrement prise en charge par Aethex. Votre valeur ajoutée réside dans la définition du rôle de votre agent, de sa personnalité vocale et de son niveau d'intégration avec vos outils internes. En structurant correctement ces éléments, la gestion de votre standard téléphonique ne sera plus une contrainte.

Créez votre premier agent en 5 minutes → · Parcourir la bibliothèque de voix · SDK Python