Outils : l'agent appelle vos points de terminaison HTTP

Tout ce que l'agent fait au-delà de parler passe par des outils : lire un agenda, réserver, vérifier une commande, ouvrir un ticket. Un outil est un point de terminaison GET ou POST de votre côté, décrit pour le modèle avec un schéma JSON. Le modèle décide quand l'appeler et avec quels arguments ; la plateforme effectue la requête.

Définir un outil

Un outil a un nom, une description écrite pour le modèle, un schéma JSON de ses arguments, et la partie exécution : URL, méthode, en-têtes et un modèle de corps facultatif. Écrivez des variables {{nom}} dans l'URL, dans les valeurs d'en-tête ou dans le corps ; chaque variable doit être déclarée dans le schéma avec une description. Le modèle la remplit à partir de la conversation et l'exécution la substitue, encodée dans l'URL et échappée dans un corps JSON.

{
  "name": "book_appointment",
  "description": "Réserve un rendez-vous. À appeler seulement après que l'appelant a confirmé le jour, l'heure et le nom.",
  "method": "POST",
  "url": "https://api.example.ch/clinics/{{clinic}}/appointments",
  "headers": { "Authorization": "Bearer sk_…" },
  "body": "{ \"start\": \"{{start}}\", \"name\": \"{{name}}\", \"phone\": \"{{phone}}\" }",
  "schema": { "type": "object", "properties": {
    "clinic": { "type": "string", "description": "Code du site : toujours 'zurich'" },
    "start":  { "type": "string", "description": "Début, yyyy-MM-dd HH:mm" },
    "name":   { "type": "string", "description": "Prénom et nom de l'appelant" },
    "phone":  { "type": "string", "description": "Téléphone de l'appelant, chiffres seulement" }
  }, "required": ["clinic", "start", "name", "phone"] }
}

Ce que reçoit votre point de terminaison et ce qu'il doit répondre

Chaque requête porte un en-tête token avec le jeton d'outil de l'agent : vérifiez-le en premier. Répondez 200 avec un corps JSON. En cas de succès, { "success": true, "message": "…" } plus d'éventuelles données : le message est destiné à être relayé à l'appelant. En cas d'erreur métier, { "success": false, "error": "…" } avec l'erreur rédigée comme une phrase pour le modèle, par exemple quoi proposer à la place. Sur 401 ou 500, l'agent s'excuse et propose un rappel. Gardez les réponses sous quelques secondes : l'appelant attend en ligne.

app.post('/clinics/:clinic/appointments', express.json(), async (req, res) => {
  if (req.get('token') !== process.env.SWISSAI_TOOL_TOKEN) return res.status(401).end();
  const { start, name, phone } = req.body;
  if (!(await isFree(req.params.clinic, start)))
    return res.json({ success: false, error: 'Ce créneau est pris. Proposez 11:00 ou 14:30 le même jour.' });
  await book(req.params.clinic, start, name, phone);
  res.json({ success: true, message: 'Rendez-vous réservé pour ' + start + '.' });
});

Une seule liste d'outils, partagée par les agents

Les outils vivent dans la section Outils du tableau de bord et les agents les utilisent par référence : modifiez un outil une fois et chaque agent qui l'utilise est mis à jour. Un outil attribué à un client ne peut être utilisé que par les agents de ce client. Avant l'enregistrement, le tableau de bord vérifie la définition avec Claude et construit le schéma à partir des variables.

Essayer sans rien héberger

Le bac à sable est un ensemble de points de terminaison d'exemple fonctionnels, avec des données de test séparées pour chaque compte : agenda, tables de restaurant, stock, rappels, contacts, commandes. Ses 22 outils sont déjà dans la section Outils ; chacun a un guide avec les paramètres, un exemple complet de requête et de réponse et le code du point de terminaison, que vous pouvez télécharger et utiliser comme base.

Pages liées

• La prise de rendez-vous par téléphone, gérée par un agent IA
• Une URI SIP pour chaque agent vocal
• Un bouton d'appel sur votre site, avec l'agent qui répond