Créer un agent

Agents et modèles

Un agent, c'est tout ce qu'entend l'appelant : sa langue, sa voix, le modèle qui l'anime, son parcours d'appel et ce qui se passe une fois l'appel terminé.

Créer ou dupliquer

POST/v1/agents crée un agent de zéro : un nom, un genre et une langue suffisent. Pour une variante d'un agent qui fonctionne déjà (un autre club, une autre langue, une version de test), dupliquez-le plutôt : la copie conserve le parcours d'appel, les prompts, les réglages et le webhook attribué.

Terminal

curl -X POST "https://api.callshift.ai/v1/agents/$AGENT_ID/duplicate" \
  -H "Authorization: Bearer $CALLSHIFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
# { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" }

curl -X PATCH "https://api.callshift.ai/v1/agents/7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -H "Authorization: Bearer $CALLSHIFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Alice (Spanish)", "language": "es" }'

Réglages

Champ	Valeurs	Par défaut
`name`	1 à 50 caractères	obligatoire
`gender`	`FEMALE`, `MALE`	obligatoire
`language`	`fr`, `en`, `nl`, `pt`, `es`	obligatoire
`provider`, `model`	Voir Choisir un modèle	`google`, `gemini-live-3.1-flash`
`voiceId`	Une voix de la famille du modèle, telle qu'affichée dans le sélecteur de voix du tableau de bord. En écriture seule : `GET` ne la renvoie pas.	La voix par défaut de la famille
`temperature`	0 à 2
`maxTokens`	1 à 10 000
`silenceTimeoutSeconds`	5 à 120 : l'agent raccroche après ce délai de silence de l'appelant	25
`maxDurationSeconds`	60 à 3600 : l'appel se termine alors avec `max-duration-exceeded`	420
`minEndpointingDelay`	0,3 à 2,5 secondes d'attente de l'agent après que l'appelant a fini de parler. Modèles pipeline uniquement.	Valeur par défaut de la plateforme
`backgroundSound`	`office_ambience`, `city_ambience`, `forest_ambience`, `crowded_room`, `keyboard_typing`, `keyboard_typing2`, `hold_music`, `gym_ambience`, ou `null`	Aucun
`backgroundSoundVolume`	0 à 1	0,2
`summaryPrompt`, `evaluationPrompt`, `informationToCollect`	Voir Analyse des appels
`diagram`	Voir Parcours d'appel
`entityId`, `entityExternalId`	Voir Entités	Partagé

Choisir un modèle

Deux familles de modèles peuvent animer un agent.

Famille	Modèles (fournisseur)	Quand la choisir
Speech-to-speech (temps réel)	`gemini-3.8-live`, `gemini-live-3.1-flash` (`google`) · `gpt-realtime-2.1-mini`, `gpt-live-1` (`openai`) · `grok-voice-3.0` (`xai`)	Le modèle entend et parle directement : les tours de parole les plus naturels et les délais de réponse les plus courts.
Pipeline	`gpt-4o-mini`, `gpt-4o`, `gpt-4.1-mini`, `gpt-5-mini`, `gpt-5.4-mini` (`openai`)	Reconnaissance vocale, modèle de langage, puis synthèse vocale : un plus large choix de voix, et plus de fiabilité sur les adresses e-mail et les numéros dictés. `minEndpointingDelay` s'applique.

Remarque

Envoyez un provider et un model de cette liste, puis récupérez l'agent avec GET/v1/agents/{agentId} pour vérifier. Pour comparer les deux familles en coût et en latence, utilisez le simulateur speech-to-speech vs pipeline.

Mettre à jour un agent sans risque

PATCH/v1/agents/{agentId} remplace en entier chaque champ que vous envoyez, et ne touche pas aux autres. Le diagram est un seul champ : récupérez l'agent, modifiez le diagramme et renvoyez-le en entier.

const api = (path, init = {}) =>
  fetch(`https://api.callshift.ai${path}`, {
    ...init,
    headers: {
      Authorization: `Bearer ${process.env.CALLSHIFT_API_KEY}`,
      "Content-Type": "application/json",
    },
  }).then((r) => r.json());

const agent = await api(`/v1/agents/${agentId}`);
const start = agent.diagram.nodes.find((n) => n.type === "startCall");
start.data.welcomeMessage =
  "Hello, this is Alice, the AI assistant of Club Lyon Part-Dieu. How can I help?";

await api(`/v1/agents/${agentId}`, {
  method: "PATCH",
  body: JSON.stringify({ diagram: agent.diagram }),
});

import os
import requests

API = "https://api.callshift.ai"
H = {"Authorization": f"Bearer {os.environ['CALLSHIFT_API_KEY']}"}

agent = requests.get(f"{API}/v1/agents/{agent_id}", headers=H).json()
start = next(n for n in agent["diagram"]["nodes"] if n["type"] == "startCall")
start["data"]["welcomeMessage"] = (
    "Hello, this is Alice, the AI assistant of Club Lyon Part-Dieu. How can I help?"
)

requests.patch(f"{API}/v1/agents/{agent_id}", headers=H, json={"diagram": agent["diagram"]})

Les modifications s'appliquent dès l'appel suivant, et un agent n'a pas d'historique de versions. Dupliquez un agent avant une modification importante pour garder la version précédente. Pour une copie de préproduction, préfixez son nom ([STAGING] Alice) et n'attribuez vos numéros qu'à l'agent de production.

Supprimer un agent

DELETE/v1/agents/{agentId} supprime l'agent et libère les numéros qui lui étaient attribués. Ses appels passés restent consultables.