aethexDocs

Votre propre LLM

Faites tourner les appels vocaux d'un agent sur votre propre serveur de modèle compatible OpenAI. Aethex gère toujours l'appel ; votre serveur rédige les réponses de l'agent.

Fonctionnement

Associez une fois l'adresse et la clé de votre serveur, puis réglez le llm_model d'un agent sur custom:<model>. À chaque tour des appels de cet agent, Aethex envoie la conversation à votre serveur et prononce sa réponse.Tout le reste reste chez Aethex : la ligne téléphonique ou la connexion WebRTC, la reconnaissance vocale, la prise de parole et les interruptions, la voix, les outils et les transcriptions. Votre serveur voit la conversation sous forme de texte et répond par du texte et des appels d'outils.Votre serveur n'est jamais remplacé par un autre modèle. S'il échoue ou répond trop lentement, ce tour reste sans réponse ; l'appel ne bascule jamais sur un modèle Aethex.

Mise en place

Deux appels : associez le point de terminaison, puis faites-y pointer un agent.

  1. Associer votre point de terminaison

    Appelez POST /api/v1/llm-credentials avec provider à custom, base_url à la racine chat-completions de votre serveur et api_key à la clé qu'attend votre serveur. Aethex vérifie la clé auprès de votre serveur avant de l'enregistrer, chiffrée (voir Exigences). Votre compte a un seul point de terminaison : en associer un autre le remplace sans interruption.

    Associer le point de terminaison
    bash
    curl -X POST https://api.aethexai.com/api/v1/llm-credentials \
      -H "X-API-Key: $AETHEX_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "provider": "custom",
        "base_url": "https://llm.example.com/v1",
        "api_key": "your-endpoint-key",
        "label": "Our model gateway"
      }'
  2. Y faire pointer un agent

    Réglez le llm_model de l'agent sur custom: suivi du nom de modèle qu'attend votre serveur. Tout ce qui suit custom: est envoyé dans model. Un agent ne peut désigner un modèle custom: qu'une fois votre point de terminaison associé, et celui-ci ne peut pas être libéré tant qu'un agent l'utilise.

    L'utiliser sur un agent
    bash
    curl -X PATCH https://api.aethexai.com/api/v1/agents/$AGENT_ID \
      -H "X-API-Key: $AETHEX_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "llm_model": "custom:acme/support-v2" }'

Ce que reçoit votre point de terminaison

Chaque tour de l'appel est une requête en streaming :- POST <base_url>/chat/completions, avec Authorization: Bearer <api_key>.
- Trois en-têtes identifient l'appel : X-Aethex-Agent-Id, X-Aethex-Conversation-Id et X-Aethex-Call-Id, chacun envoyé quand l'appel en a un. Vos outils personnalisés reçoivent les mêmes valeurs.
- Un corps chat-completions standard : model, messages, tools (quand l'agent en a), temperature, max_completion_tokens, stream: true et stream_options.include_usage: true. Aucun autre paramètre d'échantillonnage n'est envoyé.

Exemple de requête
http
POST /v1/chat/completions HTTP/1.1
Host: llm.example.com
Authorization: Bearer your-endpoint-key
X-Aethex-Agent-Id: 3f2b8c1e-...
X-Aethex-Conversation-Id: 9a7d4e20-...
X-Aethex-Call-Id: c51e0b7f-...
Content-Type: application/json

{
  "model": "acme/support-v2",
  "stream": true,
  "stream_options": { "include_usage": true },
  "temperature": 0.7,
  "max_completion_tokens": 300,
  "messages": [
    { "role": "system", "content": "You are on a phone call. ..." },
    { "role": "assistant", "content": "Hello, this is Ada from Acme. How can I help?" },
    { "role": "user", "content": "I'd like to move my appointment to Friday." }
  ],
  "tools": [
    { "type": "function", "function": { "name": "end_call", "parameters": { "...": "..." } } }
  ]
}

Contenu des messages

- Le prompt système construit par Aethex : les règles pour parler au téléphone, puis le prompt de votre agent avec ses variables dynamiques remplies, ses outils et ses garde-fous.
- La conversation jusqu'ici : ce que l'appelant a dit, tel que transcrit, et ce que l'agent a dit.
- Des notes d'Aethex, envoyées comme messages `user` commençant par System note, do not read aloud:. Elles indiquent au modèle ce qui se passe pendant l'appel : un résultat d'outil arrivé en retard, une parole de l'appelant impossible à transcrire, la fin de l'appel et l'au revoir à dire. Votre modèle doit en tenir compte sans jamais les prononcer.
- Les réponses interrompues. Quand l'appelant parle par-dessus l'agent, le dernier message de l'agent garde le texte généré jusque-là, suivi de [user interrupted before this response finished]. C'est ce que votre serveur a généré, qui peut aller au-delà de ce que l'appelant a réellement entendu.

Outils

Les outils de l'agent sont envoyés dans tools : les outils intégrés, comme end_call, transfer_to_number et voicemail_detected, et vos propres outils personnalisés. Quand votre serveur renvoie des tool_calls au format OpenAI dans le flux, Aethex exécute l'outil et envoie son résultat dans la requête suivante, sous forme de message tool.

Attention
Les outils ne fonctionnent que si votre serveur diffuse des tool_calls au format OpenAI. Sans eux, l'agent ne peut ni raccrocher, ni transférer, ni détecter une messagerie vocale, ni exécuter vos outils, et un appel ne se termine que lorsque l'appelant raccroche ou qu'une limite d'appel est atteinte.

Ce que renvoie votre point de terminaison

Un flux d'événements server-sent events contenant des objets chat.completion.chunk et se terminant par data: [DONE], comme le renvoie l'API de streaming d'OpenAI.- Délais. Le premier token doit arriver en moins de 5 secondes, et le flux ne doit jamais rester silencieux plus de 10 secondes ensuite. Sinon, Aethex ferme la requête et l'appelant n'entend plus rien pour ce tour. Le tour suivant interroge à nouveau votre serveur, et le texte déjà prononcé n'est jamais répété.
- Erreurs. Tout statut autre que 2xx met fin au tour de la même façon.
- Échecs répétés. Après 5 échecs sur l'ensemble des appels de votre compte, Aethex cesse d'envoyer des requêtes à votre serveur pendant 60 secondes ; les tours pendant ce délai restent sans réponse.
- Les redirections ne sont pas suivies.

Exemple de flux
text
data: {"id":"c1","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Sure, "}}]}

data: {"id":"c1","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Friday works."},"finish_reason":"stop"}]}

data: [DONE]

Exigences pour base_url

- HTTPS sur le port 443, vers un nom d'hôte ou une adresse IP publics.
- Ni nom d'utilisateur ou mot de passe, ni chaîne de requête, ni fragment, et 2 000 caractères au plus.
- La racine à laquelle /chat/completions est ajouté : https://llm.example.com/v1, et non https://llm.example.com/v1/chat/completions.Quand vous associez le point de terminaison, Aethex envoie GET <base_url>/models avec votre clé et ne lit que le statut. Un 400, 401 ou 403 refuse la clé. Un 404 est accepté, car beaucoup de serveurs ne servent pas /models : vérifiez donc après l'association que les appels atteignent bien votre serveur.Aethex ne se connecte à votre serveur qu'à des adresses publiques. Le nom d'hôte est résolu à nouveau avant chaque requête : il ne peut donc pas être redirigé plus tard vers une adresse privée.

Limites

- Appels vocaux uniquement. Le chat texte (POST /agents/{id}/chat) refuse un agent sur un modèle custom: avec une erreur 422, et les messages qui atteignent un tel agent par SMS ou WhatsApp restent sans réponse.
- Un point de terminaison par compte. En associer un autre le remplace.
- Pas de modèles temps réel. Un agent custom: utilise toujours la reconnaissance vocale et la voix d'Aethex.