--- title: "Agendi sammud ja üleandmised" description: "Jaga agent sammudeks, millel on oma juhised, tööriistad ja kogutud väärtused, ning anna kõned kõne ajal agentide vahel üle." --- Üks viip annab mudelile kogu töö korraga. **Sammud** annavad sellele korraga ühe kõne etapi: igal sammul on oma juhised, oma tööriistad, valikuline sõna-sõnalt öeldav lause ning väärtused, mis tuleb enne edasiliikumist koguda. **Üleandmised** võimaldavad mõnel teisel sinu organisatsiooni agendil kõne keskel üle võtta, säilitades transkriptsiooni, et helistaja ei peaks end kunagi kordama. Iga agent algab ühe viibana. Miski selle juures ei muutu, kuni lisad samme või üleandmisi. ## Sammud või üks viip? | Kasuta samme, kui | Hoia alles üks viip, kui | | --- | --- | | Kõnel on etapid, mis peavad toimuma kindlas järjekorras: esmalt kinnita, seejärel broneeri. | Vestlus on avatud lõpuga: KKK, vastuvõtt, üldine tugi. | | Väärtus tuleb koguda enne, kui agent edasi liigub. | Midagi ei pea koguma kindlas järjekorras. | | Reegel ei tohi kunagi painduda, näiteks „alla 18-aastased helistajad suunatakse eestkostja juurde“. | Mudeli hinnang on iga haru jaoks piisavalt hea. | | Otsing tuleb teha kõnes kindlas kohas. | Tööriistu saab kutsuda alati, kui helistaja seda küsib. | | Osa kõnest kuulub teisele agendile, kellel on oma viip ja hääl. | Üks persoon haldab kõike. | Sammud ei ole skriptitud telefonipuu. Sammus juhib mudel vestlust samamoodi nagu ühe viibaga. Samm määrab, millega ta tegeleb, milliseid tööriistu ta saab kasutada ja mida tal on enne lahkumist vaja. ## Kuidas sammudega agent üles ehitatakse Kui agendil on sammud, sisaldab selle `prompt` **ühiseid juhiseid**: personat ja reegleid, mis kehtivad igas sammus. Iga samm lisab nende peale oma juhised. Igal voorul näeb mudel ühiseid juhiseid, praeguse sammu nime ja juhiseid ning seni kogutud väärtusi. Koostajas vaheta agent **Üks viip** režiimist **Sammud** režiimi. Saad iga sammu kohta kaardi selle nime, juhiste, öeldava lause, tööriistade, kogutud väärtuste ja üleminekutega, üleandmiste valija ning sammude kirjutuskaitstud voodiagrammi. Ühele viibale tagasi vahetamisel pakutakse lamendatud viipa, mis ühendab ühised juhised ja kõik sammud. API kaudu on `steps` ja `handoffs` väljad [agendil](/api-reference/agents). Nagu iga agendi väli, lisab `PATCH` need mustandisse; `POST /v1/agents/{agent_id}/deploy` avaldab need. Väärtuse `"steps": null` saatmine lülitab agendi tagasi ühele viibale. Testkõned ja **Räägi** kasutavad mustandit. [Kaaspiloot](/et/guides/ask-the-copilot) saab luua samme kirjelduse põhjal („lisa samm, mis kontrollib enne broneerimist sünnikuupäeva“) ja muuta üht sammu teisi puudutamata. ### Sammu väljad | Väli | Tähendus | | --- | --- | | `id` | Nõutud. Väiketähed, numbrid ja alakriipsud, algab tähega, kuni 40 märki. Agendis kordumatu. | | `name` | Nõutud kuvatav nimi, 1 kuni 80 märki. | | `instructions` | Nõutud, kuni 20 000 märki. Toetab `{{var}}` [kõnemuutujaid](/et/guides/call-variables), nagu `prompt`. | | `say` | Valikuline sõna-sõnalt öeldav lause sammu sisenemisel, kuni 1000 märki. Toetab `{{var}}`. | | `tools` | `null` annab sammule kõik agendiga seotud tööriistad. Loend piirab sammu nimetatud tööriistadega. Sisseehitatud toimingud, näiteks `end_call` ja `transfer_call`, järgivad igas sammus agendi seadeid. | | `collect` | Kuni 20 väärtust, mida samm kogub. Igal neist on `name`, `type`, `description` ja `required` (vaikimisi `true`). | | `on_enter_tool` | Valikuline tööriista nimi, mida kutsutakse sammu sisenemisel automaatselt. Vaata [veebikonksu samme](#webhook-steps). | | `transitions` | Järjestatud loend kohtadest, kuhu samm saab järgmisena liikuda. Vaata [üleminekuid](#transitions). | | `global_when` | Valikuline. Muudab sammu saavutatavaks igast sammust. Vaata [globaalseid samme](#global-steps). | | `voice` | Valikuline hääle ID selle sammu jaoks. Ignoreeritakse, kui agent kasutab kohandatud häälekonfiguratsiooni. | Graaf ise on `{"start_step": "", "steps": [...]}`. Kõne algab sammust `start_step`. ## Üleminekud Igal üleminekul on `to`, sammu ID ja täpselt üks järgmistest: - **`when`**: loomulikus keeles ja **mudel otsustab**. Agendil on sisseehitatud tööriist `go_to_step`, mis loetleb sammud, kuhu ta võib liikuda, ning iga `when` on põhjus selle valimiseks. - **`condition`**: kogutud väärtuste reegel ja **kood otsustab**. Mudel ei saa seda vahele jätta ega sellest rääkides mööda hiilida. - **`"always": true`**: liigu edasi ilma kontrollita. Kood otsustab esimesena: kohe, kui sammu sisenetakse või selle nõutud väärtused on kogutud, rakendub esimene sobiv `condition`- või `always`-üleminek, enne kui mudel saab valida `when`. Seega paiguta `always` tingimuste järele nende varuvariandina või eraldi, et ühendada samm otse järgmisega. `always`-iga samm ei oota kunagi `when`-valikut. `condition` on `{"value": , "op": , "target": }`: | `op` | Tõene, kui väärtus | | --- | --- | | `eq`, `ne` | võrdub või ei võrdu väärtusega `target` | | `lt`, `lte`, `gt`, `gte` | on väiksem kui, maksimaalselt, suurem kui või vähemalt `target` | | `in`, `not_in` | on või ei ole üks loendis `target` olevatest väärtustest | | `exists`, `missing` | on või ei ole kogutud (ilma `target`-ita) | `eq`, `ne`, `in` ja `not_in` võrdlevad teksti pärast tühikute eemaldamist tõstutundetult. Arve võrreldakse arvudena ja kuupäevi stringidena kujul `YYYY-MM-DD`. Väärtus, mida pole kunagi kogutud, muudab iga operaatori vääraks, välja arvatud `missing`. Kirjuta `when` ja `global_when` tingimusena, näiteks „Helistaja soovib broneerida aja“, mitte öeldava tekstina. Agent näeb neid sisemiste marsruutimisjuhistena ning talle öeldakse, et ta ei tohi neid kunagi ette lugeda ega mainida, et ta samme muudab. Kui mudel kutsub välja `go_to_step`: 1. Kõik sammu `required`-väärtused peavad olemas olema. Kui üks puudub, öeldakse mudelile, milline neist, ning ta küsib seda helistajalt. 2. Väärtused salvestatakse. 3. `condition`- ja `always`-üleminekuid kontrollitakse järjekorras. Rakendub esimene vaste. 4. Vastasel juhul liigub agent mudeli valitud sammu. 5. Kui miski ei vasta ja mudel ei nimetanud ühtegi sammu, jääb agent sinna, kus ta on. Hüpe [globaalsesse sammu](#global-steps) on erand: helistaja muutis teemat, seega toimub hüpe ka siis, kui praegusel sammul on veel nõutud väärtusi puudu, ning enne selle sammu tingimuste kontrollimist. `condition`- ja `always`-üleminekuid kontrollitakse ka iga kord, kui sammu sisenetakse, seega käivitub koodi otsustatud sammude jada korraga. Ahel peatub: - sammul, mida on selle käivituse jooksul juba külastatud; - pärast 8 hüpet; - sammul, millel on veel koguda nõutud väärtusi, välja arvatud juhul, kui sammul on `on_enter_tool` (veebikonksu samm suunab alati selle tulemuse põhjal). Ette loetakse ainult ahela peatumise sammu rida `say`. Ilma üleminekuteta samm on **lõplik**. Agent lõpetab seal ning lõpetab või edastab kõne tavapäraste sisseehitatud toimingutega. ## Väärtuste kogumine Loetle sammu jaoks vajalikud väärtused väljal `collect`. Mudel edastab väärtused, kui ta kutsub välja `go_to_step`, ning need jäävad kättesaadavaks kogu ülejäänud kõne ajaks. | `type` | Sisaldab | | --- | --- | | `string` | Mis tahes tekst | | `number` | Arv | | `boolean` | `true` või `false` | | `date` | Kuupäev kujul `YYYY-MM-DD` | Kogutud väärtused on kõne sisu. Need kuvatakse kõne juures transkriptsiooni kõrval ning neile kehtivad samad säilitamise, kustutamise ja varjamise reeglid. Kui agendi kõnesalvestus on välja lülitatud, ei salvestata kogutud väärtusi ega saadeta neid veebikonksudesse; sammu ajajoon säilib siiski. Vaata [Kus seda kõne juures näha](#where-to-see-it-on-a-call). ## Ütle read `say` öeldakse täpselt nii, nagu see on kirjutatud, kui agent sammu siseneb. Seejärel jätkab mudel samas vastuses uues sammus, teades, et rida just öeldi, ega korda seda. Kasuta `say` tervituste, kohustuslike teavituste ja kindla sõnastuse jaoks ning jäta ülejäänud vastus mudeli hooleks. Algussammu `say` on agendi avarida, kui see räägib esimesena, pärast võimalikku nõusolekuteadet. Kui helistaja räägib esimesena, alustab see agendi esimest inimesele suunatud vastust, mitte kunagi IVR-i või kõneposti tervitust. Sammu `say` ei öelda uuesti, kui kõne naaseb sellesse `__previous__` kaudu või tagasiandmise teel. Kirjuta see nii, nagu see peab kõlama: kirjuta välja kõik, mida hääl võiks valesti lugeda. Ütlusread toetavad `{{var}}` kõnemuutujaid, kuid mitte kogutud väärtusi. ## Veebikonksu sammud Määra `on_enter_tool` ühele agendi tööriistadest ja see käivitatakse kohe sammu sisenemisel, ilma mudelit ootamata. Selle argumendid on kogutud väärtused, mille nimed ühtivad tööriista parameetrite nimedega. Tulemus salvestatakse kogutud väärtusena nimega `_result`, kärbituna 4 KB-ni, ning sammu `condition` ja `always` üleminekuid kontrollitakse kohe, nii et päring saab kõne suunata ainult oma tulemuse põhjal. Salvestatud väärtusel on kaks välja: | Väli | Sisaldab | | --- | --- | | `status` | HTTP olekukoodi, mille sinu lõpp-punkt tagastas. | | `response` | Vastuse keha. | Suuna vastuse keha välja põhjal `lookup_account_result.response.` abil ja olekukoodi põhjal `lookup_account_result.status` abil. Päring käivitatakse kuni 8 sekundiks või tööriista enda ajalõpuni, kui see on lühem. Kui see kestab üle 3 sekundi, ütleb agent lühikese rea, et helistaja ei jääks vaikusesse. Kui sinu lõpp-punkt tagastab olekukoodi 400 või suurema või ei vasta õigel ajal, ütleb agent helistajale, et seda ei saanud praegu kontrollida, ning jätkab sellega, mida ta saab teha. ## Globaalsed sammud Sammu, millel on `global_when`, saab jõuda mis tahes sammust alati, kui see kirjeldus kehtib. Mudel otsustab seda samamoodi nagu `when` puhul. Kasuta seda teemade jaoks, mida helistaja võib tõstatada igal ajal: arveldusküsimused, soov rääkida inimesega, kaebus. Globaalset sammu sisaldav üleminek väärtusega `"to": "__previous__"` tagastab kõne sammu juurde, mis oli enne seda aktiivne, nii et helistaja jätkab sealt, kus pooleli jäi. Samm jätkub: selle `on_enter_tool` ei käivitu uuesti, selle `say` ei kordu ja agent jätkab seda otsast alustamata. ## Üleandmised `handoffs` loetleb sinu organisatsiooni teised agendid, kes saavad kõne üle võtta: ```json [{"agent_id": 413, "when": "The caller asks about billing or a refund"}] ``` Agendil on nende agentide ja põhjustega sisseehitatud tööriist `hand_off`. Nagu üleminekute puhul, on iga `when` sisemine suunamismärkus, mida ei loeta kunagi ette. Üleandmisel ütleb agent oma häälega ühe lühikese lause, mis ütleb helistajale, kuhu ta suunatakse, näiteks „Muidugi, suunan teid meie arveldusmeeskonna juurde“. Seejärel võtavad üle sihtagendi viip, sammud, tööriistad ja hääl ning kõne jätkub sama transkriptiga. Uus agent tutvustab end lühidalt ja vastab helistaja viimasele päringule; ta ei teata ülekandmisest. Sihtagendi teadmistebaas on sellest hetkest alates saadaval. Kui kõne jõuab agendini esimest korda, algab see agendi `start_step`-ist: sammu `on_enter_tool` käivitatakse ja selle `say` öeldakse välja. Kui kõne antakse tagasi agendile, keda see juba külastas, jätkab agent sammust, kus ta oli, ilma `on_enter_tool` käivitamata, selle `say` kordamata või end uuesti tutvustamata. Kogutud väärtused on jagatud kõigi kõnes osalevate agentide vahel. - Sihtagent peab kuuluma samasse organisatsiooni ning agent ei saa kõnet iseendale üle anda. - Kõik kõnetaseme seaded jäävad vastanud agendi juurde: toode, keeled, kes räägib esimesena, kõnepost, nõusolekuteade ja kõik muud kõneseaded. - Sihtagendid saavad kõne edasi anda ja tagasi anda. Üks kõne võib jõuda kuni 8 agendini. - Testkõne kasutab testitava agendi mustandit. Agendid, kellele see kõne üle annab, kasutavad oma juurutatud versioone. - Kui kahel agendil on sama nimega, kuid erineva määratlusega tööriist, säilitatakse kõne jaoks ainult üks ning alati jääb peale vastanud agendi oma. Koostaja hoiatab sind salvestamisel. - Agendil võivad olla üleandmised ka ilma sammudeta. Kasutatakse kogu selle viipa muutmata kujul. `go_to_step` ja `hand_off` on reserveeritud sammude või üleandmistega agentidele, seega ei saa sinu enda tööriistad neid nimesid kasutada. ## Kus seda kõnes näha Ava kõne jaotises **Kõneajalugu**. Transkripti kõrval olev sammude ajajoon näitab iga sammu, kuhu kõne jõudis, ja põhjust; koos sellega kuvatakse ka kogutud väärtused. [Kõneobjekt](/api-reference/calls#retrieve-a-call) ja kõne lõpetamise veebikonks ([`telephony.complete` / `web.complete`](/et/webhooks/call-complete)) sisaldavad samu andmeid väljade `steps_trace` ja `collected_values` kujul. Mõlemad puuduvad sammudeta kõnedel. ```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` on `a`, millele järgneb agendi ID. `via` näitab, mis kõnet edasi liigutas: | `via` | Tähendus | | --- | --- | | `start` | Kõne algas sellest sammust. | | `model` | Mudel valis sammu `go_to_step`, `when` või `global_when` kaudu. | | `condition` | Üks üleminekutest `condition` või `always` vastas tingimustele. | | `on_enter` | Veebikonksu sammu tulemuse põhjal vastas üleminek tingimustele. | | `handoff` | Teine agent võttis üle. | ## Kus sammud töötavad Sammud töötavad algselt **Sparkis**, **Boltis** ja kõigis **Stormi** toodetes, sissetulevatel, väljaminevatel ja kampaaniakõnedel, testkõnedel ning veebi- ja vidinakõnedel. Kõikjal mujal töötab agent endiselt, kuid ilma struktuurita: see kasutab lamendatud viipa, mis ühendab ühised juhised ja kõik sammud järjekorras. See hõlmab järgmist: - eksperimentaalsed Bolt tooted; - [Realtime](/et/guides/use-with-openai-realtime) seansid, sealhulgas salvestatud agendi seansid; - sisestatud konfiguratsioonid, mille tagastab [dünaamilise kõnekonfiguratsiooni](/et/guides/dynamic-call-config) veebikonks. Veebikonks, mis tagastab `agent_id`, kasutab selle agendi samme. ## Piirangud | Piirang | Väärtus | | --- | --- | | Sammu agendi kohta | 100 | | Kogutud väärtusi sammu kohta | 20 | | Üleandmise sihtkohti agendi kohta | 8 | | Ühe kõnega saavutatavaid agente | 8 | | `steps` JSON-i suurus | 200 KB | | Sammu `instructions` | 20 000 märki | | `say` rida | 1 000 märki | | Salvestatud `on_enter_tool` tulemus | 4 KB | Reeglit rikkuv salvestamine tagastab `400` koos vigase välja teega, näiteks `steps.steps[2].transitions[0].to`. Vahendite nimed väljadel `tools` ja `on_enter_tool` peavad olema agendile lisatud vahendid. Sammupõhiseid keeli, mudelit vahele jätvaid skriptitud samme ja say-ridade sees olevaid kogutud väärtusi ei toetata. ## Imporditud agendid [Importimine](/et/guides/import-agents) Retellist, Blandist, Vapist või ElevenLabsist toob mitme viibaga agendid, vood, teed ja töövood üle sammudena ning meeskonnad ja agentide ülekandmised imporditud agentide vaheliste üleandmistena. Ülevaateleht näitab mõlemat enne importimist. ## Näide: hambaravivisiidi andmete kogumine Kolm sammu järjekorras: tervita, kogu patsiendi andmed, broneeri. ```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": [] } ] } } ``` Valmista see ette käsuga `PATCH /v1/agents/{agent_id}`, proovi seda **Räägi** abil ja seejärel juuruta. Samm `details` ei saa broneerimisele üle anda enne, kui nimi, sünniaeg ja põhjus on kogutud; `new_patient` on valikuline. ## Näide: vanusepiiranguga haru Mudel saab rääkida kõigiga, kuid kood otsustab, kellele broneering tehakse. Kogu vanus ja suuna selle põhjal enne, kui arvestatakse mudeli enda valikut. ```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"} ] } ``` Helistaja, kes ütleb viisteist, suunatakse `guardian`-i, olenemata sellest, mida mudel otsustab. Kõik teised suunatakse `book`-i. Mõlemad on graafikus mujal tavalised sammud. ## Näide: konto otsingu webhooki samm Helistaja annab konto numbri, järgmisse sammu sisenemisel käivitatakse otsing ning selle tulemus määrab marsruudi. Sammud `not_found`, `collections` ja `support` on lühiduse huvides välja jäetud. ```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` saab `account_number`, kuna selle parameetril on sama nimi. Kui vastuse kehas on `"found": false`, suunatakse kõne sammu `not_found`. Kui selle `account_status` on `past_due` või `suspended`, suunatakse see sammu `collections`. Aktiivne konto jääb sammu `lookup`, kus mudel aitab ning liigub edasi sammu `support`. Ebaõnnestunud otsingu suunamiseks eraldi sammu lisa esmalt tingimused staatusele: veavastus salvestab oma olekukoodi, seega püüab selle kinni `{"value": "lookup_account_result.status", "op": "gte", "target": 400}`, ning ajalõpp või vastuse puudumine salvestab `"error"`, seega püüab selle kinni `{"value": "lookup_account_result.status", "op": "eq", "target": "error"}`. ## Näide: vastuvõtust arveldusele Kaks agenti. Vastuvõtt (agent `412`) vastab igale kõnele ja suunab arveldusega seotud küsimused arveldusagendile (agent `413`), kellel on oma viip, tööriistad ja hääl. Vastuvõtus: ```json { "handoffs": [ {"agent_id": 413, "when": "The caller asks about a bill, a payment or a refund"} ] } ``` Arveldusagendis, et see saaks helistaja tagasi suunata: ```json { "handoffs": [ {"agent_id": 412, "when": "The billing question is resolved and the caller needs something else"} ] } ``` Vastuvõtt ütleb lühikese fraasi, näiteks „Ühendan teid meie arveldustiimiga“, ning arveldusagent tutvustab end ja jätkab vestlust sealt, kus vastuvõtt selle pooleli jättis. Kui arveldus suunab kõne tagasi, jätkab vastuvõtt sealt, kus see pooleli jäi, ilma helistajat uuesti tervitamata. Kõne toode, keeled, nõusolekuteade ja muud kõneseaded jäävad vastuvõtu juurde, sest see vastas kõnele. Kui arveldus vajab ainult oma juhiseid, mitte eraldi agenti, kasuta selle asemel vastuvõtus globaalset sammu. Kui küsimusele on vastatud, naaseb kõne sammu juurde, milles helistaja parajasti oli: ```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" } ``` ## Järgmised sammud Kirjuta ühised juhised ja sammujuhised, mis toimivad telefonikõnes hästi. Loo tööriistad, mida sinu sammud ja veebikonksu sammud kutsuvad. Käivita enne juurutamist samad stsenaariumid iga haru vastu. Kõik agendi väljad, mustandid ja juurutamine.