Créer un agent

Outils

Les outils permettent à l'agent d'agir pendant l'appel : retrouver une commande, vérifier un créneau, ouvrir un ticket, envoyer un lien par SMS. Un outil appartient au compte et sert à tous les agents qui y font référence.

Quatre types

Type	Ce qu'il fait	Réglages clés
`custom`	Envoie à votre endpoint HTTPS les arguments collectés par l'agent et lit la réponse.	`url`, `parameters` (JSON Schema), `apiTimeout`
`query`	Cherche dans le contenu d'une ou plusieurs pages web pour répondre à une question.	`urls`
`sendSms`	Envoie un SMS pendant l'appel, à un numéro fixe ou à l'appelant.	`body`, `to`
`sendEmail`	Envoie un email pendant l'appel, avec les notes de l'agent.	`subject`, `body`, `to`, `notesInstructions`

Créer un outil personnalisé

parameters suit le format du function calling : un objet JSON Schema qui décrit les arguments que l'agent doit collecter avant d'appeler l'outil.

Terminal

curl -X POST "https://api.callshift.ai/v1/tools" \
  -H "Authorization: Bearer $CALLSHIFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "custom",
    "name": "Check order",
    "description": "Looks up an order by its number and returns its status.",
    "config": {
      "url": "https://example.com/api/orders/lookup?token=YOUR_SECRET",
      "apiTimeout": 10,
      "parameters": {
        "type": "object",
        "properties": {
          "orderNumber": { "type": "string", "description": "The order number, e.g. ORD-1234" }
        },
        "required": ["orderNumber"]
      },
      "messages": { "requestStart": { "content": "Let me look that up." } }
    }
  }'

Pendant l'appel, votre endpoint reçoit un POST : le nom de la fonction, les arguments collectés par l'agent dans args, l'état de l'appel à ce stade dans call et, quand l'appelant est un contact connu, le contact.

JSON

{
  "name": "checkOrder",
  "args": {
    "orderNumber": "ORD-1234"
  },
  "call": {
    "id": "8f14e45f-ceea-467a-9575-6d3c0a5f2b1e",
    "type": "inbound",
    "phoneNumber": "+33612345678",
    "startedAt": "2026-10-30T09:12:00.000Z",
    "createdAt": "2026-10-30T09:11:58.000Z",
    "agentId": "550e8400-e29b-41d4-a716-446655440000",
    "agentName": "Alice",
    "transcript": "Assistant: Hello, this is Alice...\nUser: Where is my order ORD-1234?"
  },
  "contact": {
    "id": "c56a4180-65aa-42ec-a945-5fd21dec0538",
    "firstName": "Ada",
    "lastName": "Lovelace",
    "email": "ada@example.com",
    "phoneNumber": "+33612345678",
    "metadata": {
      "plan": "pro"
    }
  }
}

Répondez en quelques secondes, avec un JSON court que l'agent peut lire : l'appelant attend. La requête n'est pas signée : mettez un jeton secret dans l'URL et vérifiez-le.

Transférer vers un numéro choisi par votre système

Ne renvoyez pas le numéro depuis un outil personnalisé : l'agent le lirait et pourrait se tromper d'un chiffre. Utilisez un nœud forwardCall dont le numéro est recherché par votre service, qui reçoit la même requête : voir Parcours d'appel.

Rattacher un outil à un agent

Pour rattacher un outil, référencez-le dans le prompt d'un nœud knowHow, avec un élément <tool-node>. Son texte est l'instruction que lit l'agent.

HTML

<tool-node functionname="checkOrder" category="custom" toolslug=""
  toolid="550e8400-e29b-41d4-a716-446655440000">Use checkOrder to look up the caller's order.</tool-node>

functionname est la forme camelCase du nom de l'outil (Check order devient checkOrder).
category vaut custom ou query pour ces types, et notifications pour sendSms et sendEmail.
toolid est l'id de l'outil. Un diagramme dont un nœud d'outil ne correspond à aucun outil, à la fois par id et par nom de fonction, est refusé avec une erreur 422.

GET/v1/agents/{agentId} liste les outils qu'un agent référence dans son champ tools, en lecture seule.

Renommer un outil

Les agents trouvent un outil par son nom de fonction. Renommer un outil le détache des agents qui l'utilisent, jusqu'à ce que leur <tool-node functionname> soit mis à jour.

Ce que dit l'agent quand il utilise un outil

Message	Prononcé quand
`requestStart`	L'appel à l'outil commence. `blocking: true` attend d'abord la fin de la phrase.
`requestComplete`	L'outil a répondu
`requestFailed`	L'outil a échoué
`requestDelayed`	L'outil n'a pas répondu au bout de `timingMilliseconds` (1 000 à 30 000)

Un requestStart ou un requestDelayed omis reçoit une phrase par défaut ; envoyé sans content, il reste silencieux. Avec async: true, l'agent continue de parler sans attendre le résultat.

Modifier et supprimer

PATCH/v1/tools/{toolId} remplace chaque champ de premier niveau de config que vous envoyez (pour changer une seule entrée de messages ou de parameters, envoyez l'objet en entier), et null efface un champ facultatif. Le type ne peut pas changer. DELETE/v1/tools/{toolId} est refusé avec une erreur 409 qui liste les agents qui référencent encore l'outil, sauf si vous ajoutez ?force=true.