Dynamische Variablen

Dynamische Variablen sind pro-Anruf-String-Schlüssel-Wert-Paare, mit denen Sie einen einzelnen Anruf personalisieren können, ohne den gemeinsam genutzten Agenten zu ändern. Sie werden bei der Anrufserstellung gesetzt; die Plattform substituiert sie zum Anrufstart in den Governing Prompt des Agenten und stellt sie den Werkzeugen des Agenten zur Verfügung. Sie sind die empfohlene Methode, um pro-Anruf-Kontext (Name des Anrufers, Unternehmensname, Kontodetails, eine call_action usw.) in einen ansonsten statischen Agenten einzuspeisen, der viele gleichzeitige Anrufe bedient.

1. Setzen bei der Anrufserstellung

Übergeben Sie ein dynamic_variables-Objekt (string → string) bei jeder Anrufserstellungsanfrage:

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"
  }
}

Werte MÜSSEN Strings sein. Das Geschwisterfeld metadata in denselben Anfragen ist anders: metadata ist opakes JSON, das in der Anrufzeile gespeichert und bei Lebenszyklus-Webhook-Ereignissen zurückgegeben wird — es wird nicht in den Prompt substituiert.

Wenn ein pro-Mandant-Pre-Connect-Admission-Hook konfiguriert ist, kann seine Antwort ebenfalls dynamic_variables zurückgeben, die in das Variablen-Set des Anrufs eingemischt werden, bevor der Raum erstellt wird.

2. Substitution in den Agenten-Prompt

Zum Anrufstart löst die Pipeline {{varName}}-Platzhalter im Governing Prompt des Agenten gegen das dynamische Variablen-Set des Anrufs auf und sendet den aufgelösten Prompt dann an das Modell. Beispiel: Ein Agenten-Prompt mit:

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

wird für diesen Anruf als You are the receptionist for Acme Plumbing. The caller is Ada. verarbeitet. Ein Platzhalter ohne übereinstimmende Variable bleibt unverändert (z. B. bleibt {{unknown}} wörtlich {{unknown}}) — der Anruf wird dadurch nie unterbrochen. Namen entsprechen [a-zA-Z0-9_].

3. Verfügbarkeit für Werkzeuge

Dasselbe Variablen-Set steht den Function-Calling-Werkzeugen des Agenten auf zwei Weisen zur Verfügung:

{{varName}}-Templating in der url, dem Header-value und const-Mode-Query- Parametern eines ToolConfig wird vor jedem Werkzeug-Dispatch aus dem dynamischen Variablen-Speicher aufgelöst.
Der call.vars-Snapshot im Werkzeug-Dispatch-Anfrage-Envelope (siehe den Leitfaden Werkzeug-Dispatch) enthält die aktuelle Map der dynamischen Variablen, sodass der Werkzeug-Endpunkt alle im Gültigkeitsbereich befindlichen Variablen lesen kann.

4. Erweiterung des Speichers während des Anrufs (Werkzeug-Antworten)

Ein Werkzeug kann neue Variablen in den Speicher zurückschreiben: ToolConfig.ResponseVars bildet JSON-Dot-Paths im Antwort-Body des Werkzeugs auf Variablennamen ab, und die extrahierten skalaren Werte (Blattknoten vom Typ string/number/bool) werden zu dynamischen Variablen, die für nachfolgende {{varName}}-Substitutionen und Werkzeugaufrufe verfügbar sind. Auf diese Weise speist ein Mid-Call-Lookup (z. B. eine Verfügbarkeitsprüfung) spätere Gesprächsrunden.

Zusammenfassung des Lebenszyklus

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

Hinweise: Werte sind Strings; unaufgelöste Platzhalter werden wörtlich beibehalten; das Set ist auf den einzelnen Anruf beschränkt und wird nie zwischen gleichzeitigen Anrufen eines Mandanten geteilt.