--- title: "Pașii și transferurile între agenți" description: "Împărțiți un agent în pași cu propriile instrucțiuni, instrumente și valori colectate și transferați apelurile între agenți în timpul apelului." --- Un singur prompt oferă modelului întreaga sarcină deodată. **Pașii** îi oferă câte o etapă a apelului: fiecare pas are propriile instrucțiuni, propriile instrumente, o linie opțională rostită cuvânt cu cuvânt și valori pe care trebuie să le colecteze înainte de a continua. **Predările** permit unui alt agent din organizația dumneavoastră să preia apelul în timpul conversației, cu transcrierea intactă, astfel încât apelantul să nu fie nevoit să se repete. Fiecare agent începe cu un singur prompt. Nimic nu se schimbă până când nu adăugați pași sau predări. ## Pași sau un singur prompt? | Utilizați pași când | Păstrați un singur prompt când | | --- | --- | | Apelul are etape care trebuie să se desfășoare în ordine: verificați, apoi programați. | Conversația este deschisă: întrebări frecvente, recepție, asistență generală. | | O valoare trebuie capturată înainte ca agentul să continue. | Nu trebuie colectat nimic într-o ordine fixă. | | O regulă nu trebuie încălcată niciodată, cum ar fi „apelanții sub 18 ani sunt direcționați către un tutore”. | Judecata modelului este suficient de bună pentru fiecare ramură. | | O căutare trebuie executată într-un moment fix al apelului. | Instrumentele pot fi apelate oricând solicită apelantul. | | O parte a apelului aparține unui alt agent, cu propriul prompt și propria voce. | O singură persoană gestionează totul. | Pașii nu sunt un arbore telefonic cu scenariu fix. În cadrul unui pas, modelul gestionează conversația la fel ca atunci când folosește un singur prompt. Pasul decide la ce lucrează, ce instrumente poate utiliza și de ce are nevoie înainte de a putea ieși din el. ## Cum este construit un agent cu pași Când un agent are pași, câmpul său `prompt` conține **instrucțiunile comune**: persoana și regulile care se aplică în fiecare pas. Fiecare pas adaugă propriile instrucțiuni peste acestea. La fiecare tură, modelul vede instrucțiunile comune, numele și instrucțiunile pasului curent, precum și valorile colectate până acum. În constructor, comutați agentul de la **Prompt unic** la **Pași**. Veți primi câte un card pentru fiecare pas, cu numele, instrucțiunile, linia de spus, instrumentele, valorile colectate și tranzițiile sale, un selector de predări și un grafic de flux numai pentru citire al pașilor. Revenirea la un singur prompt oferă un prompt aplatizat care îmbină instrucțiunile comune și fiecare pas. Prin API, `steps` și `handoffs` sunt câmpuri ale [agentului](/api-reference/agents). Ca orice câmp al agentului, un `PATCH` le pregătește în versiunea de lucru; `POST /v1/agents/{agent_id}/deploy` le publică. Trimiterea `"steps": null` comută agentul înapoi la un singur prompt. Apelurile de test și **Vorbiți** folosesc versiunea de lucru. [Copilotul](/ro/guides/ask-the-copilot) poate crea pași dintr-o descriere („adăugați un pas care verifică data nașterii înainte de programare”) și poate edita un pas fără a le modifica pe celelalte. ### Câmpurile unui pas | Câmp | Semnificație | | --- | --- | | `id` | Obligatoriu. Litere mici, cifre și linii de subliniere, începând cu o literă, până la 40 de caractere. Unic în cadrul agentului. | | `name` | Nume de afișare obligatoriu, între 1 și 80 de caractere. | | `instructions` | Obligatoriu, până la 20.000 de caractere. Acceptă [variabile de apel](/ro/guides/call-variables) `{{var}}`, la fel ca `prompt`. | | `say` | Linie opțională rostită cuvânt cu cuvânt la intrarea în pas, până la 1.000 de caractere. Acceptă `{{var}}`. | | `tools` | `null` oferă pasului toate instrumentele atașate agentului. O listă limitează pasul la acele instrumente, după nume. Acțiunile integrate, precum `end_call` și `transfer_call`, respectă setările agentului în fiecare pas. | | `collect` | Până la 20 de valori pe care pasul le colectează. Fiecare are un `name`, un `type`, un `description` și `required` (implicit `true`). | | `on_enter_tool` | Nume opțional al instrumentului, apelat automat la intrarea în pas. Consultați [Pași webhook](#webhook-steps). | | `transitions` | Listă ordonată cu locurile în care pasul poate continua. Consultați [Tranziții](#transitions). | | `global_when` | Opțional. Face pasul accesibil din orice pas. Consultați [Pași globali](#global-steps). | | `voice` | ID vocal opțional pentru acest pas. Ignorat atunci când agentul utilizează o configurație vocală personalizată. | Graficul în sine este `{"start_step": "", "steps": [...]}`. Apelul începe în `start_step`. ## Tranziții Fiecare tranziție are `to`, un ID de pas, și exact unul dintre următoarele: - **`when`**: limbaj natural, iar **modelul decide**. Agentul primește un instrument încorporat `go_to_step` care listează pașii către care se poate deplasa, fiecare `when` reprezentând motivul pentru a-l alege. - **`condition`**: o regulă aplicată valorilor colectate, iar **codul decide**. Modelul nu o poate omite și nu poate negocia pentru a o evita. - **`"always": true`**: continuați fără verificare. Codul decide mai întâi: de îndată ce se intră într-un pas sau după ce sunt colectate valorile sale obligatorii, prima tranziție `condition` sau `always` corespunzătoare are prioritate, înainte ca modelul să poată alege un `when`. Prin urmare, plasați `always` după condiții ca alternativă de rezervă sau singură pentru a lega un pas direct de următorul. Un pas cu `always` nu așteaptă niciodată o alegere `when`. O `condition` este `{"value": , "op": , "target": }`: | `op` | Adevărat când valoarea | | --- | --- | | `eq`, `ne` | este egală cu sau diferită de `target` | | `lt`, `lte`, `gt`, `gte` | este mai mică decât, cel mult, mai mare decât sau cel puțin `target` | | `in`, `not_in` | este sau nu este una dintre valorile din lista `target` | | `exists`, `missing` | a fost sau nu a fost colectată (fără `target`) | `eq`, `ne`, `in` și `not_in` compară textul fără a ține cont de majuscule după eliminarea spațiilor. Numerele sunt comparate ca numere, iar datele ca șiruri `YYYY-MM-DD`. O valoare care nu a fost niciodată colectată face ca fiecare op să fie fals, cu excepția `missing`. Scrieți `when` și `global_when` ca o condiție, de exemplu „Apelantul dorește să programeze o întâlnire”, nu ca ceva de spus. Agentul le vede ca note interne de rutare și primește instrucțiuni să nu le citească niciodată cu voce tare și să nu menționeze că schimbă pașii. Când modelul apelează `go_to_step`: 1. Fiecare valoare `required` din pas trebuie să fie prezentă. Dacă lipsește una, modelului i se spune care este aceasta și îi solicită apelantului valoarea. 2. Valorile sunt stocate. 3. Tranzițiile `condition` și `always` sunt verificate în ordine. Prima corespunzătoare are prioritate. 4. În caz contrar, agentul trece la pasul ales de model. 5. Dacă nimic nu corespunde și modelul nu a numit niciun pas, agentul rămâne unde se află. Un salt la un [pas global](#global-steps) reprezintă excepția: apelantul a schimbat subiectul, astfel că se continuă chiar și atunci când pasul curent are în continuare valori obligatorii lipsă și înainte ca condițiile acelui pas să fie verificate. Tranzițiile `condition` și `always` sunt verificate și de fiecare dată când se intră într-un pas, astfel încât o serie de pași deciși de cod se desfășoară dintr-o singură dată. Lanțul se oprește: - la un pas pe care l-a vizitat deja în această execuție; - după 8 salturi; - la un pas care mai are valori obligatorii de colectat, cu excepția cazului în care pasul are un `on_enter_tool` (un pas webhook este întotdeauna rutat pe baza rezultatului său). Este rostită doar linia `say` a pasului în care se oprește lanțul. Un pas fără tranziții este **terminal**. Agentul finalizează acolo și încheie sau transferă apelul folosind acțiunile sale încorporate obișnuite. ## Colectarea valorilor Enumerați în `collect` ce are nevoie un pas. Modelul transmite valorile atunci când apelează `go_to_step`, iar acestea rămân disponibile pentru restul apelului. | `type` | Conține | | --- | --- | | `string` | Orice text | | `number` | Un număr | | `boolean` | `true` sau `false` | | `date` | O dată în formatul `YYYY-MM-DD` | Valorile colectate reprezintă conținut al apelului. Acestea apar în apel lângă transcriere și respectă aceleași reguli de păstrare, ștergere și redactare. Când înregistrarea apelului agentului este dezactivată, valorile colectate nu sunt nici stocate, nici trimise în webhookuri; cronologia pașilor rămâne totuși disponibilă. Consultați [Unde le puteți vedea într-un apel](#where-to-see-it-on-a-call). ## Replici say `say` este rostit exact așa cum este scris atunci când agentul intră în pas. Modelul continuă apoi în noul pas, în același răspuns, știind că replica tocmai a fost rostită, astfel încât nu o repetă. Utilizați `say` pentru saluturi, informări obligatorii și formulări fixe, iar restul răspunsului lăsați-l modelului. `say` al pasului de început este replica de deschidere a agentului atunci când acesta vorbește primul, după orice anunț privind consimțământul. Atunci când apelantul vorbește primul, aceasta deschide primul răspuns al agentului către o persoană, niciodată către un IVR sau un mesaj de întâmpinare al căsuței vocale. `say` al unui pas nu este rostit din nou atunci când apelul revine la acesta prin `__previous__` sau printr-un transfer înapoi. Scrieți-l așa cum ar trebui să sune: scrieți integral orice ar putea fi citit greșit de voce. Replicile say acceptă variabile de apel `{{var}}`, dar nu și valori colectate. ## Pași webhook Setați `on_enter_tool` la unul dintre instrumentele agentului, iar acesta rulează imediat ce este accesat pasul, fără a aștepta modelul. Argumentele sale sunt valorile colectate ale căror nume corespund numelor parametrilor instrumentului. Rezultatul este stocat ca valoare colectată denumită `_result`, trunchiată la 4 KB, iar tranzițiile `condition` și `always` ale pasului sunt verificate imediat, astfel încât interogarea poate direcționa apelul pe baza propriului rezultat. Valoarea stocată are două câmpuri: | Câmp | Conține | | --- | --- | | `status` | Codul de stare HTTP returnat de endpointul dumneavoastră. | | `response` | Corpul răspunsului. | Direcționați pe baza unui câmp din corp cu `lookup_account_result.response.` și pe baza codului de stare cu `lookup_account_result.status`. Interogarea rulează timp de până la 8 secunde sau până la expirarea propriului timp-limită al instrumentului, dacă acesta este mai scurt. Dacă durează mai mult de 3 secunde, agentul rostește o replică scurtă, astfel încât apelantul să nu fie lăsat în liniște. Dacă endpointul dumneavoastră returnează o stare de 400 sau mai mare ori nu răspunde la timp, agentul îi spune apelantului că nu a putut verifica acest lucru momentan și continuă cu ceea ce poate face. ## Pași globali Un pas cu `global_when` poate fi accesat din orice pas ori de câte ori se aplică acea descriere. Modelul decide, la fel ca pentru `when`. Utilizați-l pentru subiecte pe care un apelant le poate ridica în orice moment: întrebări despre facturare, o solicitare de a vorbi cu o persoană, o reclamație. O tranziție cu `"to": "__previous__"` într-un pas global readuce apelul la pasul care era activ înainte, astfel încât apelantul continuă de unde a rămas. Pasul se reia: `on_enter_tool` nu rulează din nou, `say` nu este repetat, iar agentul îl continuă fără a o lua de la început. ## Transferuri `handoffs` listează alți agenți din organizația dumneavoastră care pot prelua apelul: ```json [{"agent_id": 413, "when": "The caller asks about billing or a refund"}] ``` Agentul primește un instrument `hand_off` integrat cu acei agenți și motivele aferente. Ca și în cazul tranzițiilor, fiecare `when` este o notă internă de rutare, care nu este citită niciodată cu voce tare. Când transferă apelul, agentul spune o propoziție scurtă pentru a-i comunica apelantului unde va fi direcționat, cum ar fi „Desigur, vă transfer către echipa noastră de facturare”, folosind propria voce. Apoi, promptul, pașii, instrumentele și vocea agentului țintă preiau controlul, iar apelul continuă cu aceeași transcriere. Noul agent se prezintă pe scurt și răspunde la ultima solicitare a apelantului; nu anunță un transfer. Baza de cunoștințe a agentului țintă devine disponibilă din acel moment. Prima dată când un apel ajunge la un agent, acesta începe în `start_step` al agentului respectiv: se execută `on_enter_tool` al pasului și este rostit `say` al acestuia. Când apelul este transferat înapoi către un agent pe care l-a vizitat deja, acel agent reia pasul în care se afla, fără să execute `on_enter_tool`, să repete `say` sau să se prezinte din nou. Valorile colectate sunt partajate de fiecare agent din apel. - Un agent țintă trebuie să facă parte din aceeași organizație, iar un agent nu poate transfera apelul către el însuși. - Tot ce ține de nivelul apelului rămâne la agentul care a răspuns: produsul, limbile, cine vorbește primul, mesageria vocală, anunțul privind consimțământul și toate celelalte setări ale apelului. - Agenții țintă pot transfera apelul mai departe sau înapoi. Un apel poate ajunge la cel mult 8 agenți. - Un apel de test rulează versiunea nepublicată a agentului pe care îl testați. Agenții către care transferă rulează versiunile lor publicate. - Dacă doi agenți au un instrument cu același nume și definiții diferite, doar unul este păstrat pentru apel, iar cel al agentului care răspunde are întotdeauna prioritate. Builderul vă avertizează când salvați. - Un agent poate avea transferuri fără pași. Întregul său prompt este utilizat ca atare. `go_to_step` și `hand_off` sunt rezervate pentru agenții cu pași sau transferuri, astfel încât propriile dumneavoastră instrumente nu pot utiliza aceste nume. ## Unde îl vedeți într-un apel Deschideți apelul în **Istoricul apelurilor**. O cronologie a pașilor de lângă transcriere arată fiecare pas în care a intrat apelul și motivul, iar valorile colectate sunt listate alături. [Obiectul apelului](/api-reference/calls#retrieve-a-call) și webhookul de finalizare a apelului ([`telephony.complete` / `web.complete`](/ro/webhooks/call-complete)) includ aceleași date ca `steps_trace` și `collected_values`. Ambele lipsesc din apelurile fără pași. ```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` este `a` urmat de ID-ul agentului. `via` indică ce a mutat apelul: | `via` | Semnificație | | --- | --- | | `start` | Apelul a început în acest pas. | | `model` | Modelul a ales pasul prin `go_to_step`, un `when` sau un `global_when`. | | `condition` | O tranziție `condition` sau `always` s-a potrivit. | | `on_enter` | O tranziție s-a potrivit pe rezultatul unui pas webhook. | | `handoff` | Un alt agent a preluat apelul. | ## Unde rulează pașii Pașii rulează nativ pe **Spark**, **Bolt** și pe fiecare produs **Storm**, pentru apeluri primite, efectuate și de campanie, apeluri de test, precum și apeluri web și din widgeturi. În toate celelalte situații, agentul funcționează în continuare, doar fără structură: rulează un prompt aplatizat care combină instrucțiunile partajate și fiecare pas, în ordine. Aceasta include: - produsele Bolt experimentale; - sesiunile [Realtime](/ro/guides/use-with-openai-realtime), inclusiv sesiunile pentru un agent salvat; - configurațiile inline returnate de un webhook pentru o [configurație dinamică a apelului](/ro/guides/dynamic-call-config). Un webhook care returnează un `agent_id` utilizează pașii agentului respectiv. ## Limite | Limită | Valoare | | --- | --- | | Pași per agent | 100 | | Valori colectate per pas | 20 | | Ținte de transfer per agent | 8 | | Agenți accesibili într-un apel | 8 | | Dimensiunea JSON-ului `steps` | 200 KB | | `instructions` ale pasului | 20.000 de caractere | | Linie `say` | 1.000 de caractere | | Rezultat `on_enter_tool` stocat | 4 KB | O salvare care încalcă o regulă returnează `400` cu calea câmpului nevalid, cum ar fi `steps.steps[2].transitions[0].to`. Numele instrumentelor din `tools` și `on_enter_tool` trebuie să fie instrumente atașate agentului. Limbile per pas, pașii programați care omit modelul și valorile colectate în liniile say nu sunt acceptate. ## Agenți importați [Importarea](/ro/guides/import-agents) din Retell, Bland, Vapi sau ElevenLabs aduce agenți cu prompturi multiple, fluxuri, căi și fluxuri de lucru ca pași, iar grupurile și transferurile de agenți ca transferuri între agenții importați. Pagina de revizuire le afișează pe ambele înainte de import. ## Exemplu: preluare pentru cabinet stomatologic Trei pași în ordine: salut, colectarea detaliilor pacientului, programare. ```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": [] } ] } } ``` Pregătiți-l cu `PATCH /v1/agents/{agent_id}`, încercați-l cu **Vorbește**, apoi implementați-l. Pasul `details` nu poate transfera către programare până când nu sunt colectate numele, data nașterii și motivul; `new_patient` este opțional. ## Exemplu: o ramură condiționată de vârstă Modelul poate vorbi cu oricine, dar codul decide cine primește o programare. Colectați vârsta, apoi direcționați pe baza acesteia înainte de a lua în considerare alegerea proprie a modelului. ```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"} ] } ``` Un apelant care spune cincisprezece ajunge la `guardian`, indiferent ce decide modelul. Toți ceilalți ajung la `book`. Ambele sunt pași obișnuiți în altă parte a grafului. ## Exemplu: pas webhook pentru căutarea contului Apelantul oferă un număr de cont, căutarea se execută la intrarea în pasul următor, iar rezultatul acesteia selectează ruta. Pașii `not_found`, `collections` și `support` sunt omişi pentru concizie. ```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` primește `account_number` deoarece parametrul său are acest nume. Dacă corpul răspunsului conține `"found": false`, apelul ajunge la `not_found`. Dacă `account_status` este `past_due` sau `suspended`, ajunge la `collections`. Un cont activ rămâne în `lookup`, unde modelul oferă ajutor și trece la `support`. Pentru a trimite o căutare eșuată la propriul pas, adăugați mai întâi condiții pentru stare: un răspuns de eroare stochează codul de stare, astfel încât `{"value": "lookup_account_result.status", "op": "gte", "target": 400}` îl detectează, iar un timeout sau lipsa unui răspuns stochează `"error"`, astfel încât `{"value": "lookup_account_result.status", "op": "eq", "target": "error"}` detectează această situație. ## Exemplu: de la recepție la facturare Doi agenți. Recepția (agentul `412`) răspunde la fiecare apel și transferă întrebările despre facturare către un agent de facturare (agentul `413`) cu propriul prompt, propriile instrumente și propria voce. La recepție: ```json { "handoffs": [ {"agent_id": 413, "when": "The caller asks about a bill, a payment or a refund"} ] } ``` La agentul de facturare, pentru a putea transfera apelantul înapoi: ```json { "handoffs": [ {"agent_id": 412, "when": "The billing question is resolved and the caller needs something else"} ] } ``` Recepția spune o frază scurtă, precum „Vă fac legătura cu echipa noastră de facturare”, iar agentul de facturare se prezintă și continuă conversația din punctul în care a rămas recepția. Când facturarea transferă apelul înapoi, recepția reia de unde a rămas, fără să salute din nou apelantul. Produsul apelului, limbile, anunțul privind consimțământul și celelalte setări ale apelului rămân la recepție, deoarece aceasta a răspuns. Dacă facturarea are nevoie doar de propriile instrucțiuni, nu și de propriul agent, utilizați în schimb un pas global la recepție. Când se răspunde la întrebare, apelul revine la orice pas în care se afla apelantul: ```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" } ``` ## Pașii următori Scrieți instrucțiuni comune și instrucțiuni pentru pași care funcționează bine la telefon. Creați instrumentele apelate de pașii dvs. și de pașii webhook. Rulați aceleași scenarii pentru fiecare ramură înainte de implementare. Fiecare câmp al agentului, schițare și implementare.