Agentstappen en overdrachten

Splits een agent op in stappen met eigen instructies, tools en verzamelde waarden, en draag oproepen tijdens het gesprek over tussen agenten.

Eén prompt geeft het model meteen de hele taak. Stappen geven het één fase van het gesprek tegelijk: elke stap heeft eigen instructies, eigen tools, een optionele regel die woordelijk wordt uitgesproken en waarden die moeten worden verzameld voordat de volgende stap begint. Overdrachten laten een andere agent in je organisatie het gesprek halverwege overnemen, met behoud van het transcript, zodat de beller zich nooit hoeft te herhalen.

Elke agent begint met één prompt. Daar verandert niets aan totdat je stappen of overdrachten toevoegt.

Stappen of één prompt?#

Stappen zijn geen gescript telefoonsysteem. Binnen een stap voert het model het gesprek zoals bij één prompt. De stap bepaalt waaraan het werkt, welke tools het kan gebruiken en wat het nodig heeft voordat het kan vertrekken.

Hoe een agent met stappen wordt opgebouwd#

Wanneer een agent stappen heeft, bevat de prompt de gedeelde instructies: de persona en regels die in elke stap gelden. Elke stap voegt daar eigen instructies aan toe. Bij elke beurt ziet het model de gedeelde instructies, de naam en instructies van de huidige stap en de tot nu toe verzamelde waarden.

Schakel in de builder de agent van Eén prompt naar Stappen. Je krijgt een kaart per stap met de naam, instructies, uit te spreken regel, tools, verzamelde waarden en overgangen, een overdrachtenkiezer en een alleen-lezen stroomdiagram van de stappen. Als je terugschakelt naar één prompt, krijg je een samengevoegde prompt die de gedeelde instructies en elke stap combineert.

Via de API zijn steps en handoffs velden van de agent. Zoals elk agentveld zet een PATCH ze klaar in het concept; POST /v1/agents/{agent_id}/deploy maakt ze actief. Door "steps": null te verzenden, schakel je de agent terug naar één prompt. Testoproepen en Praten gebruiken het concept.

Stapvelden#

De grafiek zelf is {"start_step": "<step id>", "steps": [...]}. Het gesprek begint in start_step.

Overgangen#

Elke overgang heeft to, een stap-ID, en precies één van:

• when: gewone taal, en het model beslist. De agent krijgt een ingebouwde tool go_to_step met een lijst van de stappen waarnaar deze kan gaan, waarbij elke when de reden aangeeft om die stap te kiezen.
• condition: een regel voor verzamelde waarden, en code beslist. Het model kan deze niet overslaan of eromheen praten.
• "always": true: ga verder zonder controle. Code beslist eerst: zodra een stap wordt geopend, of wanneer de vereiste waarden ervan zijn verzameld, heeft de eerste overeenkomende overgang condition of always voorrang, voordat het model een when kan kiezen. Plaats always daarom na de voorwaarden als terugvaloptie, of gebruik deze alleen om een stap direct aan de volgende te koppelen. Een stap met always wacht nooit op een keuze via when.

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

eq, ne, in en not_in vergelijken tekst hoofdletterongevoelig nadat spaties zijn verwijderd. Getallen worden als getallen vergeleken en datums als YYYY-MM-DD-tekenreeksen. Een waarde die nooit is verzameld, maakt elke op onwaar, behalve missing.

Schrijf when en global_when als een voorwaarde, zoals "De beller wil een afspraak maken", niet als iets dat je moet zeggen. De agent ziet deze als interne routeringsnotities en krijgt de instructie ze nooit voor te lezen of te vermelden dat deze van stap verandert.

Wanneer het model go_to_step aanroept:

1. Elke required-waarde in de stap moet aanwezig zijn. Als er één ontbreekt, krijgt het model te horen welke dat is en vraagt het de beller ernaar.
2. De waarden worden opgeslagen.
3. Overgangen condition en always worden op volgorde gecontroleerd. De eerste overeenkomst heeft voorrang.
4. Anders gaat de agent naar de stap die het model heeft gekozen.
5. Als niets overeenkomt en het model geen stap heeft genoemd, blijft de agent waar deze is.

Een sprong naar een globale stap is de uitzondering: de beller is van onderwerp veranderd, dus de sprong gaat door, ook wanneer in de huidige stap nog vereiste waarden ontbreken, en voordat de voorwaarden van die stap worden gecontroleerd.

Overgangen condition en always worden ook gecontroleerd telkens wanneer een stap wordt geopend, zodat een reeks stappen die door code wordt bepaald in één keer wordt uitgevoerd. De keten stopt:

• bij een stap die tijdens deze uitvoering al is bezocht;
• na 8 sprongen;
• bij een stap die nog vereiste waarden moet verzamelen, tenzij de stap een on_enter_tool heeft (een webhookstap routeert altijd op basis van het resultaat).

Alleen de regel say van de stap waar de keten stopt, wordt uitgesproken.

Een stap zonder overgangen is eindstandig. De agent rondt daar af en beëindigt of verbindt het gesprek door met de normale ingebouwde acties.

Waarden verzamelen#

Vermeld wat een stap nodig heeft in collect. Het model geeft de waarden door wanneer het go_to_step aanroept, en ze blijven beschikbaar voor de rest van het gesprek.

Verzamelde waarden zijn gespreksinhoud. Ze verschijnen bij het gesprek naast het transcript en volgen dezelfde regels voor bewaring, verwijdering en redactie. Wanneer de gespreksopname van de agent is uitgeschakeld, worden verzamelde waarden niet opgeslagen en ook niet in webhooks verzonden; de staptijdlijn blijft wel beschikbaar. Zie Waar je dit bij een gesprek ziet.

Say-regels#

say wordt precies uitgesproken zoals geschreven wanneer de agent de stap ingaat. Het model gaat vervolgens in hetzelfde antwoord verder in de nieuwe stap, wetende dat de regel zojuist is uitgesproken, en herhaalt die dus niet. Gebruik say voor begroetingen, verplichte mededelingen en vaste formuleringen, en laat de rest van het antwoord aan het model over.

De say van de startstap is de openingsregel van de agent wanneer deze als eerste spreekt, na eventuele toestemmingsmededelingen. Wanneer de beller als eerste spreekt, opent deze de eerste reactie van de agent aan een persoon, nooit aan een IVR of voicemailbegroeting.

De say van een stap wordt niet opnieuw uitgesproken wanneer het gesprek ernaar terugkeert via __previous__ of een terugverwijzing. Schrijf het zoals het moet klinken: spel alles uit wat de spraak verkeerd zou kunnen lezen. Say-regels ondersteunen {{var}}-oproepvariabelen, maar geen verzamelde waarden.

Webhookstappen#

Stel on_enter_tool in op een van de tools van de agent en deze wordt uitgevoerd zodra de stap wordt geopend, zonder op het model te wachten. De argumenten zijn de verzamelde waarden waarvan de namen overeenkomen met de parameternamen van de tool. Het resultaat wordt opgeslagen als een verzamelde waarde met de naam <tool>_result, afgekapt op 4 KB, en de overgangen condition en always van de stap worden meteen gecontroleerd, zodat de opzoekactie het gesprek op basis van het eigen resultaat kan routeren.

De opgeslagen waarde heeft twee velden:

Routeer op een veld in de hoofdtekst met lookup_account_result.response.<field>, en op de statuscode met lookup_account_result.status.

De opzoekactie wordt maximaal 8 seconden uitgevoerd, of de eigen time-out van de tool als die korter is. Als dit langer dan 3 seconden duurt, zegt de agent een korte regel zodat de beller niet in stilte blijft wachten. Als je endpoint een status van 400 of hoger retourneert, of niet op tijd antwoordt, vertelt de agent de beller dat die dat op dit moment niet kon controleren en gaat verder met wat wel mogelijk is.

Globale stappen#

Een stap met global_when kan vanuit elke stap worden bereikt wanneer die beschrijving van toepassing is. Het model beslist, net als bij when. Gebruik dit voor onderwerpen die een beller op elk moment kan aansnijden: vragen over facturering, een verzoek om een medewerker, een klacht.

Een overgang met "to": "__previous__" in een globale stap brengt het gesprek terug naar de stap die daarvoor actief was, zodat de beller verdergaat waar die was gebleven. De stap wordt hervat: de on_enter_tool wordt niet opnieuw uitgevoerd, de say wordt niet herhaald en de agent gaat ermee verder zonder opnieuw te beginnen.

Doorverbindingen#

handoffs vermeldt andere agenten in je organisatie die de oproep kunnen overnemen:

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

De agent krijgt een ingebouwde tool hand_off met die agenten en redenen. Net als bij overgangen is elke when een interne routeringsnotitie die nooit wordt voorgelezen.

Bij een doorverbinding zegt de agent één korte zin waarin de beller wordt verteld waar die naartoe gaat, zoals "Natuurlijk, ik verbind u door met ons facturatieteam", met zijn eigen stem. Vervolgens nemen de prompt, stappen, tools en stem van de doelagent het over en gaat de oproep verder met hetzelfde transcript. De nieuwe agent stelt zich kort voor en beantwoordt het laatste verzoek van de beller; deze kondigt geen doorverbinding aan. De kennisbank van de doelagent is vanaf dat moment beschikbaar.

Wanneer een oproep voor het eerst bij een agent terechtkomt, begint deze bij de start_step van die agent: de on_enter_tool van de stap wordt uitgevoerd en de say wordt uitgesproken. Wanneer de oproep wordt terugverbonden naar een agent die deze al heeft bezocht, hervat die agent de stap waarin deze zich bevond, zonder on_enter_tool uit te voeren, de say te herhalen of zich opnieuw voor te stellen. Verzamelde waarden worden gedeeld door elke agent in de oproep.

• Een doelagent moet een agent in dezelfde organisatie zijn en een agent kan niet naar zichzelf doorverbinden.
• Alles op oproepniveau blijft bij de agent die de oproep heeft beantwoord: product, talen, wie als eerste spreekt, voicemail, toestemmingsmelding en elke andere oproepinstelling.
• Doelagenten kunnen verder en terug doorverbinden. Eén oproep kan maximaal 8 agenten bereiken.
• Een testoproep voert de conceptversie uit van de agent die je test. De agenten waarnaar deze doorverbindt, voeren hun geïmplementeerde versies uit.
• Als twee agenten een tool met dezelfde naam en verschillende definities hebben, wordt er slechts één behouden voor de oproep en heeft die van de beantwoordende agent altijd voorrang. De builder waarschuwt je wanneer je opslaat.
• Een agent kan doorverbindingen zonder stappen hebben. De volledige prompt wordt ongewijzigd gebruikt.

go_to_step en hand_off zijn gereserveerd voor agenten met stappen of doorverbindingen, dus je eigen tools kunnen die namen niet gebruiken.

Waar je dit in een oproep ziet#

Open de oproep in Oproepgeschiedenis. Een tijdlijn met stappen naast het transcript toont elke stap die de oproep heeft doorlopen en waarom, en de verzamelde waarden worden erbij vermeld.

Het oproepobject en de webhook voor voltooide oproepen (telephony.complete / web.complete) bevatten dezelfde gegevens als steps_trace en collected_values. Beide ontbreken bij oproepen zonder stappen.

"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 is a gevolgd door de agent-ID. via geeft aan waardoor de oproep werd verplaatst:

Waar stappen worden uitgevoerd#

Stappen worden standaard uitgevoerd op Spark, Bolt en elk Storm-product, bij inkomende, uitgaande en campagneoproepen, testoproepen en web- en widgetoproepen.

Overal elders werkt de agent nog steeds, maar zonder de structuur: deze voert een samengevoegde prompt uit die de gedeelde instructies en elke stap op volgorde combineert. Dit omvat:

• de experimentele Bolt-producten;
• Realtime-sessies, inclusief sessies voor een opgeslagen agent;
• inline configuraties die worden geretourneerd door een webhook voor dynamische oproepconfiguratie. Een webhook die een agent_id retourneert, gebruikt de stappen van die agent.

Limieten#

Een opslag die een regel schendt, retourneert 400 met het pad van het onjuiste veld, zoals steps.steps[2].transitions[0].to. Toolnamen in tools en on_enter_tool moeten tools zijn die aan de agent zijn gekoppeld.

Talen per stap, gescripte stappen die het model overslaan en verzamelde waarden binnen say-regels worden niet ondersteund.

Geïmporteerde agenten#

Importeren vanuit Retell, Bland, Vapi of ElevenLabs zet agents met meerdere prompts, flows, paden en workflows over als stappen, en squads en agentoverdrachten als handoffs tussen de geïmporteerde agenten. De beoordelingspagina toont beide voordat je importeert.

Voorbeeld: tandheelkundige intake#

Drie stappen op volgorde: begroeten, de gegevens van de patiënt verzamelen, inplannen.

{
  "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": []
      }
    ]
  }
}

Zet het klaar met PATCH /v1/agents/{agent_id}, probeer het met Praten en implementeer het vervolgens. De stap details kan pas overdragen naar het inplannen wanneer de naam, geboortedatum en reden zijn verzameld; new_patient is optioneel.

Voorbeeld: een vertakking met leeftijdsgrens#

Het model kan met iedereen praten, maar code bepaalt wie wordt ingepland. Verzamel de leeftijd en routeer daarop voordat de eigen keuze van het model wordt overwogen.

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

Een beller die vijftien zegt, gaat naar guardian, ongeacht wat het model beslist. Iedereen anders gaat naar book. Beide zijn gewone stappen elders in de grafiek.

Voorbeeld: webhookstap voor accountopzoeking#

De beller geeft een accountnummer door, de opzoeking wordt uitgevoerd bij het openen van de volgende stap, en het resultaat bepaalt de route. De stappen not_found, collections en support zijn voor de beknoptheid weggelaten.

[
  {
    "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 ontvangt account_number omdat de parameter die naam heeft. Als de responsbody "found": false bevat, gaat de oproep naar not_found. Als de account_status past_due of suspended is, gaat deze naar collections. Een actief account blijft in lookup, waar het model helpt en doorgaat naar support. Voeg voorwaarden voor de status eerst toe om een mislukte opzoeking naar een eigen stap te sturen: een foutrespons slaat de statuscode op, dus {"value": "lookup_account_result.status", "op": "gte", "target": 400} vangt die op, en een time-out of geen antwoord slaat "error" op, dus {"value": "lookup_account_result.status", "op": "eq", "target": "error"} vangt dat op.

Voorbeeld: van receptie naar facturering#

Twee agents. De receptie (agent 412) beantwoordt elke oproep en draagt vragen over facturering over aan een factureringsagent (agent 413) met een eigen prompt, tools en stem.

Op de receptie:

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

Op de factureringsagent, zodat deze de beller kan terugsturen:

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

De receptie zegt een korte zin zoals "Ik verbind u door met ons factureringsteam", en de factureringsagent stelt zich voor en pakt het gesprek op waar de receptie het heeft gelaten. Wanneer facturering terugdraagt, hervat de receptie waar deze was gebleven, zonder de beller opnieuw te begroeten. Het product, de talen, de toestemmingsmelding en andere oproepinstellingen van de oproep blijven bij de receptie, omdat die de oproep heeft beantwoord.

Als facturering alleen eigen instructies nodig heeft en geen eigen agent, gebruik je in plaats daarvan een globale stap op de receptie. Wanneer de vraag is beantwoord, gaat de oproep terug naar de stap waarin de beller zich bevond:

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

Volgende stappen#