---
title: "Agentstappen en overdrachten"
description: "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?
| Gebruik stappen wanneer | Behoud één prompt wanneer |
| --- | --- |
| Het gesprek fases heeft die in volgorde moeten plaatsvinden: eerst verifiëren, daarna boeken. | Het gesprek open is: veelgestelde vragen, receptie, algemene ondersteuning. |
| Er een waarde moet worden vastgelegd voordat de agent verdergaat. | Er niets in een vaste volgorde hoeft te worden verzameld. |
| Een regel nooit mag worden gebogen, zoals "bellers jonger dan 18 gaan naar een voogd". | Het oordeel van het model goed genoeg is voor elke vertakking. |
| Een opzoekactie op een vast punt in het gesprek moet worden uitgevoerd. | Tools kunnen worden aangeroepen wanneer de beller erom vraagt. |
| Een deel van het gesprek bij een andere agent hoort, met een eigen prompt en stem. | Eén persona alles afhandelt. |
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](/api-reference/agents). 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.
De [copilot](/nl/guides/ask-the-copilot) kan stappen maken op basis van een
beschrijving ("voeg een stap toe die de geboortedatum verifieert voordat er wordt geboekt") en één stap
bewerken zonder de andere aan te raken.
### Stapvelden
| Veld | Betekenis |
| --- | --- |
| `id` | Vereist. Kleine letters, cijfers en underscores, beginnend met een letter, maximaal 40 tekens. Uniek binnen de agent. |
| `name` | Vereiste weergavenaam, 1 tot 80 tekens. |
| `instructions` | Vereist, maximaal 20.000 tekens. Ondersteunt `{{var}}` [oproepvariabelen](/nl/guides/call-variables), net als `prompt`. |
| `say` | Optionele regel die woordelijk wordt uitgesproken wanneer de stap wordt geopend, maximaal 1.000 tekens. Ondersteunt `{{var}}`. |
| `tools` | `null` geeft de stap elke tool die aan de agent is gekoppeld. Een lijst beperkt de stap tot die tools, op naam. Ingebouwde acties zoals `end_call` en `transfer_call` volgen in elke stap de instellingen van de agent. |
| `collect` | Maximaal 20 waarden die de stap verzamelt. Elke waarde heeft een `name`, een `type`, een `description` en `required` (standaard `true`). |
| `on_enter_tool` | Optionele toolnaam die automatisch wordt aangeroepen wanneer de stap wordt geopend. Zie [Webhookstappen](#webhook-steps). |
| `transitions` | Geordende lijst met mogelijke volgende stappen. Zie [Overgangen](#transitions). |
| `global_when` | Optioneel. Maakt de stap bereikbaar vanuit elke stap. Zie [Globale stappen](#global-steps). |
| `voice` | Optionele stem-id voor deze stap. Genegeerd wanneer de agent een aangepaste stemconfiguratie gebruikt. |
De grafiek zelf is `{"start_step": "", "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": , "op": , "target": }`:
| `op` | Waar wanneer de waarde |
| --- | --- |
| `eq`, `ne` | gelijk is aan, of niet gelijk is aan, `target` |
| `lt`, `lte`, `gt`, `gte` | kleiner is dan, maximaal, groter is dan, of minimaal `target` is |
| `in`, `not_in` | wel, of niet, een van de waarden in de lijst `target` is |
| `exists`, `missing` | wel, of niet, is verzameld (geen `target`) |
`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](#global-steps) 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.
| `type` | Bevat |
| --- | --- |
| `string` | Willekeurige tekst |
| `number` | Een getal |
| `boolean` | `true` of `false` |
| `date` | Een datum als `YYYY-MM-DD` |
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](#where-to-see-it-on-a-call).
## 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 `_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:
| Veld | Bevat |
| --- | --- |
| `status` | De HTTP-statuscode die je endpoint heeft geretourneerd. |
| `response` | De hoofdtekst van het antwoord. |
Routeer op een veld in de hoofdtekst met `lookup_account_result.response.`, 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:
```json
[{"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](/api-reference/calls#retrieve-a-call) en de webhook voor
voltooide oproepen ([`telephony.complete` / `web.complete`](/nl/webhooks/call-complete))
bevatten dezelfde gegevens als `steps_trace` en `collected_values`. Beide
ontbreken bij oproepen zonder stappen.
```json
"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:
| `via` | Betekenis |
| --- | --- |
| `start` | De oproep begon in deze stap. |
| `model` | Het model koos de stap via `go_to_step`, een `when` of een `global_when`. |
| `condition` | Een overgang met `condition` of `always` kwam overeen. |
| `on_enter` | Een overgang kwam overeen met het resultaat van een webhookstap. |
| `handoff` | Een andere agent nam het over. |
## 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](/nl/guides/use-with-openai-realtime)-sessies, inclusief sessies voor
een opgeslagen agent;
- inline configuraties die worden geretourneerd door een webhook voor
[dynamische oproepconfiguratie](/nl/guides/dynamic-call-config). Een webhook die
een `agent_id` retourneert, gebruikt de stappen van die agent.
## Limieten
| Limiet | Waarde |
| --- | --- |
| Stappen per agent | 100 |
| Verzamelde waarden per stap | 20 |
| Overdrachtsdoelen per agent | 8 |
| Agenten bereikbaar in één gesprek | 8 |
| Grootte van de `steps`-JSON | 200 KB |
| Stap-`instructions` | 20.000 tekens |
| `say`-regel | 1.000 tekens |
| Opgeslagen resultaat van `on_enter_tool` | 4 KB |
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](/nl/guides/import-agents) 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.
```json
{
"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.
```json
{
"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.
```json
[
{
"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:
```json
{
"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:
```json
{
"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:
```json
{
"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
Schrijf gedeelde instructies en stapinstructies die goed werken aan de telefoon.
Maak de tools die je stappen en webhookstappen aanroepen.
Voer dezelfde scenario's uit voor elke vertakking voordat je implementeert.
Elk agentveld, concept en implementatie.