Agent-Schritte und Übergaben

Teilen Sie einen Agenten in Schritte mit eigenen Anweisungen, Tools und erfassten Werten auf und übergeben Sie Anrufe während des Gesprächs zwischen Agenten.

Ein einzelner Prompt gibt dem Modell die gesamte Aufgabe auf einmal. Schritte geben ihm jeweils eine Phase des Anrufs: Jeder Schritt hat eigene Anweisungen, eigene Tools, eine optionale wortwörtlich gesprochene Zeile und Werte, die er erfassen muss, bevor er fortfährt. Übergaben ermöglichen es einem anderen Agenten in Ihrer Organisation, einen Anruf mitten im Gespräch zu übernehmen, wobei das Transkript erhalten bleibt, sodass Anrufer sich nie wiederholen müssen.

Jeder Agent beginnt als einzelner Prompt. Daran ändert sich nichts, bis Sie Schritte oder Übergaben hinzufügen.

Schritte oder ein einzelner Prompt?#

Schritte sind kein geskripteter Telefonbaum. Innerhalb eines Schritts führt das Modell das Gespräch wie mit einem einzelnen Prompt. Der Schritt bestimmt, woran es arbeitet, welche Tools es verwenden kann und was es benötigt, bevor es ihn verlassen kann.

So wird ein Agent mit Schritten aufgebaut#

Wenn ein Agent Schritte hat, enthält sein prompt die gemeinsamen Anweisungen: die Persona und Regeln, die in jedem Schritt gelten. Jeder Schritt fügt darüber hinaus eigene Anweisungen hinzu. In jedem Turn sieht das Modell die gemeinsamen Anweisungen, den Namen und die Anweisungen des aktuellen Schritts sowie die bisher erfassten Werte.

Wechseln Sie im Builder den Agenten von Einzelner Prompt zu Schritte. Sie erhalten pro Schritt eine Karte mit Name, Anweisungen, Sprechzeile, Tools, erfassten Werten und Übergängen, eine Übergabeauswahl sowie ein schreibgeschütztes Ablaufdiagramm der Schritte. Beim Zurückwechseln zu einem einzelnen Prompt wird ein zusammengeführter Prompt angeboten, der die gemeinsamen Anweisungen und jeden Schritt vereint.

Über die API sind steps und handoffs Felder des Agenten. Wie jedes Agentenfeld speichert ein PATCH sie im Entwurf; POST /v1/agents/{agent_id}/deploy veröffentlicht sie. Das Senden von "steps": null stellt den Agenten wieder auf einen einzelnen Prompt um. Testanrufe und Sprechen verwenden den Entwurf.

Schrittfelder#

Der Graph selbst ist {"start_step": "<step id>", "steps": [...]}. Der Anruf beginnt bei start_step.

Übergänge#

Jeder Übergang hat to, eine Schritt-ID, und genau eines der folgenden Elemente:

• when: natürliche Sprache, und das Modell entscheidet. Der Agent erhält ein integriertes Tool go_to_step, das die Schritte auflistet, zu denen er wechseln darf, wobei jedes when den Grund für die Auswahl angibt.
• condition: eine Regel für erfasste Werte, und Code entscheidet. Das Modell kann sie weder überspringen noch umgehen.
• "always": true: ohne Prüfung fortfahren. Code entscheidet zuerst: Sobald ein Schritt betreten wird oder seine erforderlichen Werte erfasst wurden, gewinnt der erste passende condition- oder always-Übergang, bevor das Modell ein when auswählen kann. Platzieren Sie always daher nach den Bedingungen als Fallback oder allein, um einen Schritt direkt mit dem nächsten zu verknüpfen. Ein Schritt mit always wartet niemals auf eine when-Auswahl.

Eine condition lautet {"value": <collected name or dotted path>, "op": <op>, "target": <literal>}:

eq, ne, in und not_in vergleichen Text nach dem Entfernen von Leerzeichen ohne Beachtung der Groß- und Kleinschreibung. Zahlen werden als Zahlen und Daten als YYYY-MM-DD-Zeichenfolgen verglichen. Ein Wert, der nie erfasst wurde, führt bei jedem Operator zu „falsch“, außer bei missing.

Schreiben Sie when und global_when als Bedingung, etwa „Der Anrufer möchte einen Termin buchen“, nicht als etwas, das gesagt werden soll. Der Agent sieht sie als interne Routing-Hinweise und wird angewiesen, sie niemals vorzulesen oder zu erwähnen, dass er Schritte wechselt.

Wenn das Modell go_to_step aufruft:

1. Jeder required-Wert im Schritt muss vorhanden sein. Fehlt einer, wird dem Modell mitgeteilt, welcher fehlt, und es fragt den Anrufer danach.
2. Die Werte werden gespeichert.
3. condition- und always-Übergänge werden der Reihe nach geprüft. Die erste Übereinstimmung gewinnt.
4. Andernfalls wechselt der Agent zu dem Schritt, den das Modell ausgewählt hat.
5. Wenn nichts zutrifft und das Modell keinen Schritt genannt hat, bleibt der Agent, wo er ist.

Ein Sprung zu einem globalen Schritt ist die Ausnahme: Der Anrufer hat das Thema gewechselt, daher erfolgt der Sprung auch dann, wenn im aktuellen Schritt noch erforderliche Werte fehlen, und bevor die Bedingungen dieses Schritts geprüft werden.

condition- und always-Übergänge werden außerdem jedes Mal geprüft, wenn ein Schritt betreten wird. Dadurch wird eine Abfolge von codegesteuerten Schritten in einem Durchgang ausgeführt. Die Kette endet:

• bei einem Schritt, den sie in diesem Durchgang bereits besucht hat;
• nach 8 Sprüngen;
• bei einem Schritt, für den noch erforderliche Werte erfasst werden müssen, es sei denn, der Schritt hat ein on_enter_tool (ein Webhook-Schritt routet immer anhand seines Ergebnisses).

Nur die say-Zeile des Schritts, an dem die Kette endet, wird gesprochen.

Ein Schritt ohne Übergänge ist final. Der Agent schließt ihn dort ab und beendet oder übergibt den Anruf mit seinen normalen integrierten Aktionen.

Werte erfassen#

Listen Sie in collect auf, was ein Schritt benötigt. Das Modell übergibt die Werte, wenn es go_to_step aufruft, und sie bleiben für den Rest des Anrufs verfügbar.

Erfasste Werte sind Anrufinhalte. Sie erscheinen beim Anruf neben dem Transkript und unterliegen denselben Regeln für Aufbewahrung, Löschung und Schwärzung. Wenn die Anrufaufzeichnung des Agenten deaktiviert ist, werden erfasste Werte weder gespeichert noch in Webhooks gesendet; die Schritt-Zeitleiste bleibt jedoch erhalten. Siehe Wo Sie dies in einem Anruf sehen.

Say-Zeilen#

say wird genau so gesprochen, wie es geschrieben ist, wenn der Agent den Schritt betritt. Das Modell fährt dann in derselben Antwort im neuen Schritt fort und weiß, dass die Zeile gerade gesprochen wurde, sodass es sie nicht wiederholt. Verwenden Sie say für Begrüßungen, erforderliche Hinweise und feste Formulierungen, und überlassen Sie den Rest der Antwort dem Modell.

Das say des Startschritts ist die Eröffnungszeile des Agenten, wenn er zuerst spricht, nach einer etwaigen Einwilligungsansage. Wenn der Anrufer zuerst spricht, eröffnet es die erste Antwort des Agenten an eine Person, niemals an ein IVR oder eine Voicemail-Begrüßung.

Das say eines Schritts wird nicht erneut gesprochen, wenn der Anruf über __previous__ oder eine Rückgabe zu ihm zurückkehrt. Schreiben Sie es so, wie es klingen soll: Schreiben Sie alles aus, was die Stimme falsch lesen könnte. Say-Zeilen unterstützen die Anrufvariablen {{var}}, jedoch keine erfassten Werte.

Webhook-Schritte#

Setzen Sie on_enter_tool auf eines der Tools des Agenten, damit es ausgeführt wird, sobald der Schritt betreten wird, ohne auf das Modell zu warten. Seine Argumente sind die erfassten Werte, deren Namen mit den Parameternamen des Tools übereinstimmen. Das Ergebnis wird als erfasster Wert mit dem Namen <tool>_result gespeichert, auf 4 KB gekürzt, und die Übergänge condition und always des Schritts werden sofort geprüft, sodass die Abfrage den Anruf anhand ihres eigenen Ergebnisses weiterleiten kann.

Der gespeicherte Wert hat zwei Felder:

Leiten Sie anhand eines Body-Felds mit lookup_account_result.response.<field> und anhand des Statuscodes mit lookup_account_result.status weiter.

Die Abfrage läuft bis zu 8 Sekunden oder bis zum eigenen Timeout des Tools, falls dieser kürzer ist. Dauert sie länger als 3 Sekunden, sagt der Agent eine kurze Zeile, damit der Anrufer nicht in Stille gelassen wird. Wenn Ihr Endpunkt einen Status von 400 oder höher zurückgibt oder nicht rechtzeitig antwortet, teilt der Agent dem Anrufer mit, dass er das gerade nicht prüfen konnte, und fährt mit dem fort, was er tun kann.

Globale Schritte#

Ein Schritt mit global_when kann von jedem Schritt aus erreicht werden, wenn diese Beschreibung zutrifft. Wie bei when entscheidet das Modell. Verwenden Sie dies für Themen, die ein Anrufer jederzeit ansprechen kann: Fragen zur Abrechnung, eine Anfrage nach einem Menschen, eine Beschwerde.

Ein Übergang mit "to": "__previous__" in einem globalen Schritt führt den Anruf zu dem Schritt zurück, der zuvor aktiv war, sodass der Anrufer dort weitermacht, wo er aufgehört hat. Der Schritt wird fortgesetzt: Sein on_enter_tool wird nicht erneut ausgeführt, sein say wird nicht wiederholt, und der Agent fährt damit fort, ohne von vorn zu beginnen.

Übergaben#

handoffs listet andere Agenten in Ihrer Organisation auf, die den Anruf übernehmen können:

[{"agent_id": 413, "when": "The caller asks about billing or a refund"}]

Der Agent erhält ein integriertes Tool hand_off mit diesen Agenten und Gründen. Wie bei Übergängen ist jedes when eine interne Routing-Notiz und wird niemals vorgelesen.

Bei einer Übergabe sagt der Agent in seiner eigenen Stimme einen kurzen Satz, der dem Anrufer mitteilt, wohin er weitergeleitet wird, zum Beispiel „Gern, ich verbinde Sie mit unserem Abrechnungsteam“. Anschließend übernehmen Prompt, Schritte, Tools und Stimme des Zielagenten, und der Anruf wird mit demselben Transkript fortgesetzt. Der neue Agent stellt sich kurz vor und beantwortet die letzte Anfrage des Anrufers; er kündigt keine Weiterleitung an. Die Wissensdatenbank des Ziels ist ab diesem Zeitpunkt verfügbar.

Wenn ein Anruf einen Agenten zum ersten Mal erreicht, beginnt er im start_step dieses Agenten: Das on_enter_tool des Schritts wird ausgeführt und dessen say wird gesprochen. Wird der Anruf an einen bereits besuchten Agenten zurückübergeben, setzt dieser Agent den Schritt fort, in dem er sich befand, ohne on_enter_tool auszuführen, dessen say zu wiederholen oder sich erneut vorzustellen. Erfasste Werte werden von jedem Agenten im Anruf geteilt.

• Ein Ziel muss ein Agent in derselben Organisation sein, und ein Agent kann nicht an sich selbst übergeben.
• Alles auf Anrufebene bleibt bei dem Agenten, der den Anruf angenommen hat: Produkt, Sprachen, wer zuerst spricht, Voicemail, Einwilligungsansage und jede andere Anrufeinstellung.
• Ziele können weiter- und zurückübergeben. Ein Anruf kann bis zu 8 Agenten erreichen.
• Ein Testanruf verwendet den Entwurf des Agenten, den Sie testen. Die Agenten, an die er übergibt, verwenden ihre bereitgestellten Versionen.
• Wenn zwei Agenten ein Tool mit demselben Namen und unterschiedlichen Definitionen haben, wird für den Anruf nur eines beibehalten, und das des annehmenden Agenten hat immer Vorrang. Der Builder warnt Sie beim Speichern.
• Ein Agent kann Übergaben ohne Schritte haben. Sein gesamter Prompt wird unverändert verwendet.

go_to_step und hand_off sind bei Agenten mit Schritten oder Übergaben reserviert, daher können Ihre eigenen Tools diese Namen nicht verwenden.

Wo Sie dies in einem Anruf sehen#

Öffnen Sie den Anruf im Anrufverlauf. Eine Schritt-Zeitleiste neben dem Transkript zeigt jeden Schritt, den der Anruf erreicht hat, und warum; die erfassten Werte werden zusammen damit aufgelistet.

Das Anrufobjekt und der Webhook zum Anrufabschluss (telephony.complete / web.complete) enthalten dieselben Daten als steps_trace und collected_values. Beide fehlen bei Anrufen ohne Schritte.

"steps_trace": [
  {"t_ms": 0, "agent": "a412", "step": "greet", "via": "start"},
  {"t_ms": 51230, "agent": "a412", "step": "verify", "via": "model"},
  {"t_ms": 98410, "agent": "a412", "step": "minor", "via": "condition"}
],
"collected_values": {"full_name": "Dana Reyes", "dob": "2010-04-02", "age": 15}

agent ist a, gefolgt von der Agenten-ID. via gibt an, wodurch der Anruf verschoben wurde:

Wo Schritte ausgeführt werden#

Schritte werden nativ auf Spark, Bolt und jedem Storm-Produkt ausgeführt, bei eingehenden, ausgehenden und Kampagnenanrufen, Testanrufen sowie Web- und Widget-Anrufen.

Überall sonst funktioniert der Agent weiterhin, nur ohne diese Struktur: Er verwendet einen abgeflachten Prompt, der die gemeinsamen Anweisungen und jeden Schritt der Reihe nach zusammenführt. Das umfasst:

• die experimentellen Bolt-Produkte;
• Realtime-Sitzungen, einschließlich Sitzungen für einen gespeicherten Agenten;
• Inline-Konfigurationen, die von einem Webhook für eine dynamische Anrufkonfiguration zurückgegeben werden. Ein Webhook, der eine agent_id zurückgibt, verwendet die Schritte dieses Agenten.

Grenzen#

Ein Speichervorgang, der gegen eine Regel verstößt, gibt 400 mit dem Pfad des fehlerhaften Felds zurück, z. B. steps.steps[2].transitions[0].to. Tool-Namen in tools und on_enter_tool müssen Tools sein, die dem Agenten zugeordnet sind.

Sprachen pro Schritt, skriptbasierte Schritte, die das Modell überspringen, und erfasste Werte innerhalb von Say-Zeilen werden nicht unterstützt.

Importierte Agenten#

Das Importieren aus Retell, Bland, Vapi oder ElevenLabs übernimmt Mehrprompt-Agenten, Abläufe, Pfade und Workflows als Schritte sowie Teams und Agentenübergaben als Übergaben zwischen den importierten Agenten. Die Überprüfungsseite zeigt beides vor dem Import an.

Beispiel: Aufnahme in einer Zahnarztpraxis#

Drei Schritte in dieser Reihenfolge: Begrüßung, Erfassung der Patientendaten, Buchung.

{
  "prompt": "You are Ava, the front desk assistant at Acme Dental. Be warm and brief. Ask one question at a time.",
  "steps": {
    "start_step": "greet",
    "steps": [
      {
        "id": "greet",
        "name": "Greeting",
        "instructions": "Greet the caller and ask how you can help.",
        "say": "Thanks for calling Acme Dental, this is Ava. How can I help you today?",
        "tools": null,
        "collect": [],
        "transitions": [
          {"to": "details", "when": "The caller wants to book an appointment"}
        ]
      },
      {
        "id": "details",
        "name": "Patient details",
        "instructions": "Ask for the caller's full name, date of birth and the reason for the visit. Read the date of birth back and ask the caller to confirm it.",
        "tools": null,
        "collect": [
          {"name": "full_name", "type": "string", "description": "Caller's full name", "required": true},
          {"name": "dob", "type": "date", "description": "Date of birth", "required": true},
          {"name": "reason", "type": "string", "description": "Reason for the visit", "required": true},
          {"name": "new_patient", "type": "boolean", "description": "First visit to the practice", "required": false}
        ],
        "transitions": [
          {"to": "book", "when": "The caller has confirmed their details"}
        ]
      },
      {
        "id": "book",
        "name": "Book",
        "instructions": "Offer the two earliest open slots from book_slot and book the one the caller picks. Confirm the date and time, then say goodbye and end the call.",
        "tools": ["book_slot"],
        "collect": [],
        "transitions": []
      }
    ]
  }
}

Stellen Sie ihn mit PATCH /v1/agents/{agent_id} in der Staging-Umgebung bereit, testen Sie ihn mit Sprechen und veröffentlichen Sie ihn anschließend. Der Schritt details kann erst zur Buchung übergeben, wenn Name, Geburtsdatum und Grund erfasst wurden; new_patient ist optional.

Beispiel: ein altersbeschränkter Zweig#

Das Modell kann mit allen sprechen, aber der Code entscheidet, wer gebucht wird. Erfassen Sie das Alter und leiten Sie danach weiter, bevor die eigene Auswahl des Modells berücksichtigt wird.

{
  "id": "verify",
  "name": "Verify age",
  "instructions": "Ask for the caller's age.",
  "tools": null,
  "collect": [
    {"name": "age", "type": "number", "description": "Caller's age in years", "required": true}
  ],
  "transitions": [
    {"to": "guardian", "condition": {"value": "age", "op": "lt", "target": 18}},
    {"to": "book", "when": "The caller has given their age"}
  ]
}

Ein Anrufer, der fünfzehn sagt, wird zu guardian weitergeleitet, unabhängig davon, was das Modell entscheidet. Alle anderen werden zu book weitergeleitet. Beide sind an anderer Stelle im Graphen gewöhnliche Schritte.

Beispiel: Webhook-Schritt zur Kontosuche#

Der Anrufer gibt eine Kontonummer an, die Suche wird beim Eintritt in den nächsten Schritt ausgeführt, und ihr Ergebnis bestimmt die Route. Die Schritte not_found, collections und support werden der Kürze halber ausgelassen.

[
  {
    "id": "identify",
    "name": "Identify",
    "instructions": "Ask for the caller's account number and read it back digit by digit.",
    "tools": null,
    "collect": [
      {"name": "account_number", "type": "string", "description": "Account number", "required": true}
    ],
    "transitions": [
      {"to": "lookup", "when": "The caller has confirmed their account number"}
    ]
  },
  {
    "id": "lookup",
    "name": "Look up account",
    "instructions": "Tell the caller what you found on their account and ask how you can help.",
    "tools": ["lookup_account"],
    "collect": [],
    "on_enter_tool": "lookup_account",
    "transitions": [
      {"to": "not_found", "condition": {"value": "lookup_account_result.response.found", "op": "eq", "target": false}},
      {"to": "collections", "condition": {"value": "lookup_account_result.response.account_status", "op": "in", "target": ["past_due", "suspended"]}},
      {"to": "support", "when": "The caller needs help with an active account"}
    ]
  }
]

lookup_account erhält account_number, weil sein Parameter diesen Namen hat. Wenn der Response-Body "found": false enthält, geht der Anruf zu not_found. Wenn sein account_status past_due oder suspended ist, geht er zu collections. Ein aktives Konto bleibt in lookup, wo das Modell hilft und anschließend zu support weiterleitet. Um eine fehlgeschlagene Suche an einen eigenen Schritt zu senden, fügen Sie zuerst Bedingungen für den Status hinzu: Eine Fehlerantwort speichert ihren Statuscode, daher wird sie von {"value": "lookup_account_result.status", "op": "gte", "target": 400} erfasst, und ein Timeout oder keine Antwort speichert "error", daher wird dies von {"value": "lookup_account_result.status", "op": "eq", "target": "error"} erfasst.

Beispiel: Empfang zu Abrechnung#

Zwei Agenten. Der Empfang (Agent 412) beantwortet jeden Anruf und übergibt Fragen zur Abrechnung an einen Abrechnungsagenten (Agent 413) mit eigenem Prompt, eigenen Tools und eigener Stimme.

Beim Empfang:

{
  "handoffs": [
    {"agent_id": 413, "when": "The caller asks about a bill, a payment or a refund"}
  ]
}

Beim Abrechnungsagenten, damit dieser den Anrufer zurückgeben kann:

{
  "handoffs": [
    {"agent_id": 412, "when": "The billing question is resolved and the caller needs something else"}
  ]
}

Der Empfang sagt einen kurzen Satz wie „Ich verbinde Sie mit unserem Abrechnungsteam“, und der Abrechnungsagent stellt sich vor und setzt das Gespräch dort fort, wo der Empfang es verlassen hat. Wenn die Abrechnung zurückübergibt, setzt der Empfang dort fort, wo er war, ohne den Anrufer erneut zu begrüßen. Das Produkt des Anrufs, die Sprachen, die Einwilligungsansage und andere Anrufeinstellungen bleiben beim Empfang, weil dieser den Anruf beantwortet hat.

Wenn die Abrechnung nur eigene Anweisungen und keinen eigenen Agenten benötigt, verwenden Sie stattdessen einen globalen Schritt beim Empfang. Wenn die Frage beantwortet ist, kehrt der Anruf zu dem Schritt zurück, in dem sich der Anrufer befand:

{
  "id": "billing",
  "name": "Billing questions",
  "instructions": "Answer questions about bills and payments. Offer to send a payment link by email.",
  "tools": null,
  "collect": [],
  "transitions": [
    {"to": "__previous__", "when": "The billing question is answered"}
  ],
  "global_when": "The caller asks about a bill or payment at any point"
}

Nächste Schritte#