Variables dynamiques

Les variables dynamiques sont des paires clé/valeur de type chaîne, propres à chaque appel, qui vous permettent de personnaliser un appel donné sans modifier l’agent partagé. Vous les définissez à la création de l’appel ; la plateforme les substitue dans le prompt directeur de l’agent au démarrage de l’appel et les expose aux outils de l’agent. Elles constituent la manière recommandée d’injecter un contexte propre à l’appel (nom de l’appelant, nom de l’entreprise, informations de compte, un call_action, etc.) dans un agent par ailleurs statique qui traite de nombreux appels simultanés.

1. Les définir à la création de l’appel

Transmettez un objet dynamic_variables (chaîne → chaîne) dans toute requête de création d’appel :

POST /v1/sip/calls/outbound
POST /v1/sip/calls/inbound
POST /v1/sip/calls/browser

json

POST /v1/sip/calls/outbound
{
  "agent_id": "…",
  "from_number": "+44…",
  "destination_number": "+44…",
  "dynamic_variables": {
    "business_name": "Acme Plumbing",
    "customer_name": "Ada",
    "call_action": "answer"
  }
}

Les valeurs DOIVENT être des chaînes. Le champ voisin metadata de ces mêmes requêtes est différent : metadata est un JSON opaque conservé dans la ligne de l’appel et repris dans les événements webhook de cycle de vie — il n’est pas substitué dans le prompt.

Si un hook d’admission préalable à la connexion propre au tenant est configuré, sa réponse peut aussi renvoyer des dynamic_variables, qui sont fusionnées dans l’ensemble de variables de l’appel avant la création de la salle.

2. Substitution dans le prompt de l’agent

Au démarrage de l’appel, le pipeline résout les marqueurs {{varName}} du prompt directeur de l’agent à partir de l’ensemble de variables dynamiques de l’appel, puis envoie le prompt résolu au modèle. Par exemple, un prompt d’agent contenant :

You are the receptionist for {{business_name}}. The caller is {{customer_name}}.

est prononcé et traité comme You are the receptionist for Acme Plumbing. The caller is Ada. pour cet appel uniquement. Un marqueur sans variable correspondante est laissé tel quel (par exemple, {{unknown}} reste littéralement {{unknown}}) — il ne fait jamais échouer l’appel. Les noms correspondent à [a-zA-Z0-9_].

3. Disponibilité pour les outils

Le même ensemble de variables est disponible pour les outils d’appel de fonctions de l’agent de deux manières :

Le gabarit {{varName}} dans l’url d’un ToolConfig, dans la value de ses en-têtes et dans ses paramètres de requête en mode const est résolu à partir du stock de variables dynamiques avant chaque envoi d’outil.
L’instantané call.vars dans l’enveloppe de requête d’envoi d’outil (voir le guide Envoi d’outils) porte la table courante des variables dynamiques, de sorte que le point de terminaison de l’outil peut lire toutes les variables dans la portée.

4. Étendre le stock en cours d’appel (réponses d’outils)

Un outil peut réécrire de nouvelles variables dans le stock : ToolConfig.ResponseVars associe des chemins JSON à points dans le corps de la réponse de l’outil à des noms de variables, et les valeurs scalaires extraites (feuilles de type chaîne, nombre ou booléen) deviennent des variables dynamiques disponibles pour les substitutions {{varName}} et les appels d’outils suivants. C’est ainsi qu’une recherche en cours d’appel (par exemple, une vérification de disponibilité) alimente les tours de parole suivants.

Résumé du cycle de vie

create call (dynamic_variables) ─┐
  (+ admission-hook variables)   ├─▶ resolve {{var}} into the governing prompt at call start
                                 │
                                 ├─▶ tools: {{var}} in url/headers/query + call.vars snapshot
                                 │
tool response (ResponseVars) ────┴─▶ write new vars into the store for later turns

Remarques : les valeurs sont des chaînes ; les marqueurs non résolus sont conservés tels quels ; l’ensemble est limité à un seul appel et n’est jamais partagé entre les appels simultanés d’un tenant.