Web Services (REST)

Un Web Service est une connexion API REST configurée. Une fois mis en place, vous l'assignez à un agent comme outil, le LLM de l'agent l'appelle en cours de conversation quand nécessaire, en passant les paramètres collectés via le dialogue et en utilisant la réponse pour continuer l'appel.

Créer un web service

1. Allez sur Dashboard → Comptes → [compte] → Connexions → Web Services
2. Cliquez sur New web service
3. Saisissez un Name (étiquette interne, ex : CRM API) et une Description optionnelle
4. Saisissez la Base URL, l'endpoint racine partagé par toutes les actions (ex : https://api.yourcrm.com/v2). Sans slash final.
5. Sélectionnez une méthode d'authentification (voir ci-dessous)
6. Cliquez sur Enregistrer

Méthodes d'authentification

Le auth_type contrôle comment les credentials sont attachés à chaque requête faite par ce service.

Actions

Chaque web service a une ou plusieurs actions, des endpoints API spécifiques que l'agent peut invoquer. Une action définit la méthode HTTP, le chemin, et les paramètres dynamiques que le LLM remplira depuis le contexte de la conversation.

Champs d'une action

Structure JSON d'une action

{
  "id": "get_customer",
  "name": "Get customer",
  "method": "GET",
  "path": "/customers",
  "description": "Rechercher un client par son numéro de compte",
  "dynamicParams": [
    {
      "name": "account_id",
      "type": "string",
      "description": "Le numéro de compte du client, collecté auprès de l'appelant",
      "required": true
    }
  ]
}

Assigner à un agent

Après avoir créé un web service, assignez-le à un agent pour que le LLM puisse l'invoquer pendant les appels :

1. Ouvrez l'éditeur de flux et double-cliquez sur le nœud Welcome (défaut pour tout l'agent) ou sur un nœud Agent (pour le limiter à ce nœud)
2. Allez dans l'onglet Connections du nœud → section Web Services, trouvez votre web service et activez les actions à rendre disponibles
3. Dans le prompt système de ce nœud, décrivez quand l'agent doit invoquer chaque action
4. Enregistrez le flux, puis Make live quand vous êtes prêt pour de vrais appelants

Fonctionnement du tool calling pendant un appel

Quand une action de web service est activée sur un agent :

1. Le LLM reçoit la définition de l'action (name, description, paramètres) en parallèle de la conversation
2. Quand le LLM décide d'invoquer l'action, il fournit les valeurs de paramètres requises depuis la conversation
3. La plateforme émet la requête HTTP vers votre API, l'appelant entend une brève pause (typiquement sous 500 ms pour des APIs rapides)
4. La réponse JSON est repassée au LLM, qui l'utilise pour formuler son prochain énoncé
5. L'appel complet, paramètres de requête, corps de réponse, et timing, est journalisé dans call.tool_calls

Exemple : recherche CRM

Web service : CRM API, action : Get customer (nécessite account_id).

Extrait du prompt système :

Utilise l'action « Get customer » pour rechercher le compte de l'appelant dès qu'il
fournit son numéro de compte. Après la recherche, confirme son nom et son plan actuel.
Si la recherche échoue, excuse-toi et propose de le transférer vers un agent humain.

Conversation :

Agent : « Bonjour, je suis Alex. Quel est votre numéro de compte ? »
Appelant : « C'est ACC-1234. »
[L'agent invoque Get customer → l'API retourne { name: "Marie Dupont", plan: "premium", status: "active" }]
Agent : « Très bien, Marie. Vous êtes sur le plan premium, en quoi puis-je vous aider ? »

L'appel API, les paramètres, la réponse et la latence sont stockés dans call.tool_calls sur l'enregistrement d'appel et visibles dans la vue de détail d'appel.

Gestion d'erreurs

Si l'appel API échoue (timeout, HTTP 4xx/5xx, erreur de connexion), l'échec est journalisé dans call.tool_calls avec les détails de l'erreur. Le LLM reçoit un signal d'erreur structuré qui lui permet de réagir intelligemment et, si votre prompt système inclut une instruction de repli, il s'excusera et continuera la conversation ou proposera de transférer l'appelant.

Sur une réponse HTTP 4xx ou 5xx, l'erreur renvoyée au LLM ne se limite pas au code de statut : elle inclut la ligne de statut et le corps de la réponse (tronqué à environ 1000 caractères), ainsi qu'une instruction indiquant à l'assistant comment la gérer. L'agent peut ainsi réagir au message d'erreur réel de l'API, par exemple en redemandant une valeur que l'API a rejetée, plutôt que de s'excuser aveuglément.

{
  "status": "FAILED",
  "error_type": "rejected_arguments",
  "error": "Client error '400 Bad Request' for url 'https://api.yourcrm.com/v2/customers' | response_body: {\"error\":\"account_id must be numeric\"}",
  "instruction_for_assistant": "The external service REJECTED the arguments as invalid — nothing was written. Do NOT tell the user the action succeeded. Read the validation error in the result (it names the offending field and often the allowed values), correct ONLY those field(s), and call the tool again. Leave the fields that were accepted unchanged."
}

Le champ error_type indique à l'assistant de quel type d'échec il s'agit. Une réponse 4xx (client/validation) renvoie rejected_arguments : le service externe a rejeté les arguments comme invalides, rien n'a été écrit ; l'agent lit l'erreur, corrige uniquement le(s) champ(s) qu'elle nomme, puis rappelle l'outil. network est réservé aux véritables échecs de connectivité — absence de réponse, timeouts ou erreurs serveur 5xx — où les arguments étaient corrects et où une nouvelle tentative peut réussir.

Incluez toujours une instruction de repli dans le prompt système pour chaque action d'outil :

Si l'action « Get customer » échoue ou ne retourne aucune donnée, dis :
« Je n'arrive pas à accéder à votre compte pour le moment. Je vous mets en relation
avec notre équipe de support. » et route vers un agent humain.