--- title: "Kroky agenta a předávání" description: "Rozdělte agenta do kroků s vlastními pokyny, nástroji a shromážděnými hodnotami a předávejte hovory mezi agenty během hovoru." --- Jediný prompt zadá modelu celou úlohu najednou. **Kroky** mu poskytují vždy jednu fázi hovoru: každý krok má vlastní instrukce, vlastní nástroje, volitelnou větu, která se pronese doslova, a hodnoty, které musí shromáždit před pokračováním. **Předání** umožňují, aby hovor uprostřed převzal jiný agent ve vaší organizaci, se zachováním přepisu, takže se volající nemusí opakovat. Každý agent začíná jako jediný prompt. Dokud nepřidáte kroky nebo předání, nic se na tom nezmění. ## Kroky, nebo jediný prompt? | Použijte kroky, když | Ponechte jediný prompt, když | | --- | --- | | Hovor má fáze, které musí proběhnout v pořadí: nejdříve ověření, poté rezervace. | Konverzace je otevřená: časté dotazy, recepce, obecná podpora. | | Je nutné zachytit hodnotu, než agent pokračuje. | Není nutné nic shromažďovat v pevně daném pořadí. | | Pravidlo se nesmí nikdy porušit, například „volající mladší 18 let se přepojí na zákonného zástupce“. | Úsudek modelu je dostatečný pro každou větev. | | Vyhledání musí proběhnout v pevně daném okamžiku hovoru. | Nástroje lze volat kdykoli, když o to volající požádá. | | Část hovoru patří jinému agentovi s vlastním promptem a hlasem. | Jedna persona zvládne vše. | Kroky nejsou předem napsaný telefonní strom. V rámci kroku model vede konverzaci stejně jako s jediným promptem. Krok určuje, na čem pracuje, které nástroje může používat a co potřebuje, než jej může opustit. ## Jak se vytváří agent s kroky Když agent používá kroky, jeho `prompt` obsahuje **sdílené instrukce**: personu a pravidla platná v každém kroku. Každý krok k nim přidává vlastní instrukce. Model při každém tahu vidí sdílené instrukce, název a instrukce aktuálního kroku a dosud shromážděné hodnoty. V nástroji pro tvorbu přepněte agenta z **Jediný prompt** na **Kroky**. Získáte kartu pro každý krok s názvem, instrukcemi, větou k pronesení, nástroji, shromážděnými hodnotami a přechody, výběr předání a graf kroků jen pro čtení. Po přepnutí zpět na jediný prompt se nabídne sloučený prompt, který spojí sdílené instrukce a všechny kroky. V rozhraní API jsou `steps` a `handoffs` pole objektu [agent](/api-reference/agents). Stejně jako každé pole agenta je `PATCH` uloží do konceptu; `POST /v1/agents/{agent_id}/deploy` je zveřejní. Odesláním `"steps": null` přepnete agenta zpět na jediný prompt. Testovací hovory a **Hovor** používají koncept. [Copilot](/cs/guides/ask-the-copilot) dokáže vytvořit kroky z popisu („přidejte krok, který před rezervací ověří datum narození“) a upravit jeden krok bez zásahu do ostatních. ### Pole kroku | Pole | Význam | | --- | --- | | `id` | Povinné. Malá písmena, číslice a podtržítka, začíná písmenem, maximálně 40 znaků. Jedinečné v rámci agenta. | | `name` | Povinný zobrazovaný název, 1 až 80 znaků. | | `instructions` | Povinné, maximálně 20 000 znaků. Podporuje [proměnné hovoru](/cs/guides/call-variables) `{{var}}`, stejně jako `prompt`. | | `say` | Volitelná věta pronesená doslova při vstupu do kroku, maximálně 1 000 znaků. Podporuje `{{var}}`. | | `tools` | `null` poskytne kroku každý nástroj připojený k agentovi. Seznam omezí krok na tyto nástroje podle názvu. Vestavěné akce, například `end_call` a `transfer_call`, se v každém kroku řídí nastavením agenta. | | `collect` | Až 20 hodnot, které krok shromažďuje. Každá má `name`, `type`, `description` a `required` (výchozí hodnota `true`). | | `on_enter_tool` | Volitelný název nástroje, který se automaticky volá při vstupu do kroku. Viz [Kroky webhooku](#webhook-steps). | | `transitions` | Seřazený seznam míst, kam může krok pokračovat. Viz [Přechody](#transitions). | | `global_when` | Volitelné. Zpřístupní krok z libovolného kroku. Viz [Globální kroky](#global-steps). | | `voice` | Volitelné ID hlasu pro tento krok. Ignoruje se, když agent používá vlastní konfiguraci hlasu. | Samotný graf je `{"start_step": "", "steps": [...]}`. Hovor začíná v `start_step`. ## Přechody Každý přechod má `to`, ID kroku a právě jednu z následujících možností: - **`when`**: přirozený jazyk a **rozhoduje model**. Agent má k dispozici vestavěný nástroj `go_to_step`, který uvádí kroky, do nichž se může přesunout, přičemž každé `when` představuje důvod, proč jej zvolit. - **`condition`**: pravidlo pro shromážděné hodnoty a **rozhoduje kód**. Model jej nemůže přeskočit ani obejít konverzací. - **`"always": true`**: pokračování bez kontroly. Nejprve rozhoduje kód: jakmile je krok spuštěn nebo jsou shromážděny jeho požadované hodnoty, použije se první odpovídající přechod `condition` nebo `always` dříve, než model může vybrat `when`. Proto umístěte `always` za podmínky jako jejich záložní možnost nebo samostatně pro přímé propojení kroku s následujícím krokem. Krok s `always` nikdy nečeká na volbu `when`. `condition` má tvar `{"value": , "op": , "target": }`: | `op` | Je pravda, když hodnota | | --- | --- | | `eq`, `ne` | se rovná nebo nerovná `target` | | `lt`, `lte`, `gt`, `gte` | je menší než, nejvýše, větší než nebo alespoň `target` | | `in`, `not_in` | je nebo není jednou z hodnot v seznamu `target` | | `exists`, `missing` | byla nebo nebyla shromážděna (bez `target`) | `eq`, `ne`, `in` a `not_in` porovnávají text bez rozlišení velikosti písmen po odstranění mezer. Čísla se porovnávají jako čísla a data jako řetězce `YYYY-MM-DD`. Hodnota, která nebyla nikdy shromážděna, způsobí, že je každý operátor nepravdivý s výjimkou `missing`. Pište `when` a `global_when` jako podmínku, například „Volající chce rezervovat schůzku“, nikoli jako něco, co má agent říct. Agent je vidí jako interní poznámky pro směrování a je instruován, aby je nikdy nečetl nahlas ani nezmiňoval, že mění kroky. Když model zavolá `go_to_step`: 1. Musí být přítomna každá hodnota `required` v kroku. Pokud některá chybí, model se dozví, která to je, a požádá o ni volajícího. 2. Hodnoty se uloží. 3. Přechody `condition` a `always` se kontrolují v pořadí. Použije se první shoda. 4. Jinak se agent přesune do kroku, který model zvolil. 5. Pokud nic neodpovídá a model neuvedl žádný krok, agent zůstane v aktuálním kroku. Výjimkou je přechod do [globálního kroku](#global-steps): volající změnil téma, proto k němu dojde i tehdy, když v aktuálním kroku stále chybí požadované hodnoty, a před kontrolou podmínek tohoto kroku. Přechody `condition` a `always` se také kontrolují při každém vstupu do kroku, takže se posloupnost kroků řízených kódem provede najednou. Řetězec se zastaví: - u kroku, který již v tomto průchodu navštívil; - po 8 přechodech; - u kroku, který stále vyžaduje shromáždit hodnoty, pokud krok nemá `on_enter_tool` (krok webhooku vždy směruje podle svého výsledku). Vysloví se pouze řádek `say` kroku, ve kterém se řetězec zastaví. Krok bez přechodů je **konečný**. Agent jej dokončí a hovor ukončí nebo přepojí pomocí svých běžných vestavěných akcí. ## Shromažďování hodnot V položce `collect` uveďte, co krok potřebuje. Model předá hodnoty při volání `go_to_step` a zůstanou k dispozici po zbytek hovoru. | `type` | Obsahuje | | --- | --- | | `string` | Libovolný text | | `number` | Číslo | | `boolean` | `true` nebo `false` | | `date` | Datum ve formátu `YYYY-MM-DD` | Shromážděné hodnoty jsou obsahem hovoru. Zobrazují se u hovoru vedle přepisu a řídí se stejnými pravidly pro uchovávání, mazání a redakci. Když je nahrávání hovoru agentem vypnuté, shromážděné hodnoty se neukládají ani neodesílají ve webehoocích; časová osa kroků zůstává zachována. Viz [Kde je zobrazit u hovoru](#where-to-see-it-on-a-call). ## Řádky say `say` se vysloví přesně tak, jak je napsáno, když agent vstoupí do kroku. Model poté ve stejné odpovědi pokračuje v novém kroku a ví, že řádek právě zazněl, takže jej neopakuje. Používejte `say` pro pozdravy, povinná sdělení a pevně dané formulace a zbytek odpovědi nechte na modelu. `say` počátečního kroku je úvodní věta agenta, když promluví jako první, po případném oznámení o souhlasu. Když volající promluví jako první, otevře první odpověď agenta člověku, nikdy IVR ani uvítací zprávě hlasové schránky. `say` kroku se znovu nevysloví, když se hovor do kroku vrátí přes `__previous__` nebo předání zpět. Pište jej tak, jak má znít: vše, co by hlas mohl chybně přečíst, vypište slovy. Řádky say podporují proměnné hovoru `{{var}}`, nikoli však shromážděné hodnoty. ## Kroky webhooku Nastavte `on_enter_tool` na jeden z nástrojů agenta a spustí se ihned po vstupu do kroku, aniž by čekal na model. Jeho argumenty jsou shromážděné hodnoty, jejichž názvy odpovídají názvům parametrů nástroje. Výsledek se uloží jako shromážděná hodnota s názvem `_result`, zkrácená na 4 KB, a přechody `condition` a `always` kroku se ihned zkontrolují, takže vyhledání může hovor směrovat podle vlastního výsledku. Uložená hodnota má dvě pole: | Pole | Obsahuje | | --- | --- | | `status` | Stavový kód HTTP vrácený vaším endpointem. | | `response` | Tělo odpovědi. | Směrujte podle pole těla pomocí `lookup_account_result.response.` a podle stavového kódu pomocí `lookup_account_result.status`. Vyhledání běží až 8 sekund nebo po dobu vlastního časového limitu nástroje, je-li kratší. Pokud trvá déle než 3 sekundy, agent řekne krátkou větu, aby volající nezůstal v tichu. Pokud váš endpoint vrátí stav 400 nebo vyšší nebo neodpoví včas, agent volajícímu sdělí, že to právě nemohl ověřit, a pokračuje v tom, co může udělat. ## Globální kroky Krok s `global_when` lze dosáhnout z libovolného kroku, kdykoli platí tento popis. Model rozhoduje stejně jako u `when`. Používejte jej pro témata, která může volající otevřít kdykoli: dotazy k vyúčtování, žádost o člověka, stížnost. Přechod s `"to": "__previous__"` v globálním kroku vrátí hovor do kroku, který byl aktivní před ním, takže volající naváže tam, kde skončil. Krok se obnoví: jeho `on_enter_tool` se znovu nespustí, jeho `say` se neopakuje a agent v něm pokračuje, aniž by začínal znovu. ## Předání `handoffs` uvádí další agenty ve vaší organizaci, kteří mohou převzít hovor: ```json [{"agent_id": 413, "when": "The caller asks about billing or a refund"}] ``` Agent získá integrovaný nástroj `hand_off` s těmito agenty a důvody. Stejně jako u přechodů je každé `when` interní poznámka pro směrování, která se nikdy nepřečítá nahlas. Při předání agent řekne jednu krátkou větu, která volajícímu sdělí, kam bude přesměrován, například „Jistě, přepojím vás na naše fakturační oddělení“, svým vlastním hlasem. Poté převezme výzva, kroky, nástroje a hlas cílového agenta a hovor pokračuje se stejným přepisem. Nový agent se krátce představí a odpoví na poslední požadavek volajícího; neoznamuje přepojení. Od té chvíle je k dispozici znalostní báze cílového agenta. Když hovor poprvé dosáhne agenta, začne v jeho `start_step`: spustí se `on_enter_tool` kroku a pronese se jeho `say`. Když je hovor předán zpět agentovi, kterého již navštívil, tento agent pokračuje v kroku, ve kterém byl, aniž by spustil `on_enter_tool`, zopakoval své `say` nebo se znovu představil. Shromážděné hodnoty sdílejí všichni agenti v hovoru. - Cílem musí být agent ve stejné organizaci a agent nemůže předat hovor sám sobě. - Vše na úrovni hovoru zůstává u agenta, který hovor přijal: produkt, jazyky, kdo mluví jako první, hlasová schránka, oznámení souhlasu a všechna další nastavení hovoru. - Cíloví agenti mohou hovor předávat dále i zpět. Jeden hovor může dosáhnout až 8 agentů. - Testovací hovor spustí koncept agenta, kterého testujete. Agenti, jimž hovor předá, spustí své nasazené verze. - Pokud mají dva agenti nástroj se stejným názvem a odlišnými definicemi, pro hovor se zachová pouze jeden a vždy má přednost nástroj agenta, který hovor přijal. Nástroj pro sestavení vás upozorní při ukládání. - Agent může mít předání i bez kroků. Použije se celá jeho výzva beze změny. `go_to_step` a `hand_off` jsou vyhrazené pro agenty s kroky nebo předáními, proto vaše vlastní nástroje nemohou používat tyto názvy. ## Kde je v hovoru uvidíte Otevřete hovor v **Historii hovorů**. Časová osa kroků vedle přepisu zobrazuje každý krok, do kterého hovor vstoupil, a proč; spolu s ní jsou uvedeny shromážděné hodnoty. [Objekt hovoru](/api-reference/calls#retrieve-a-call) a webhook po dokončení hovoru ([`telephony.complete` / `web.complete`](/cs/webhooks/call-complete)) nesou stejná data jako `steps_trace` a `collected_values`. U hovorů bez kroků obě chybí. ```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` je `a`, za kterým následuje ID agenta. `via` uvádí, co hovor přesunulo: | `via` | Význam | | --- | --- | | `start` | Hovor začal v tomto kroku. | | `model` | Model vybral krok prostřednictvím `go_to_step`, `when` nebo `global_when`. | | `condition` | Shodoval se přechod `condition` nebo `always`. | | `on_enter` | Přechod se shodoval s výsledkem kroku webhooku. | | `handoff` | Hovor převzal jiný agent. | ## Kde se kroky spouštějí Kroky se nativně spouštějí na produktech **Spark**, **Bolt** a všech produktech **Storm**, u příchozích, odchozích a kampaníních hovorů, testovacích hovorů i webových hovorů a hovorů z widgetu. Všude jinde agent stále funguje, pouze bez struktury: spouští sloučenou výzvu, která v pořadí kombinuje sdílené instrukce a všechny kroky. To zahrnuje: - experimentální produkty Bolt; - relace [Realtime](/cs/guides/use-with-openai-realtime), včetně relací pro uloženého agenta; - vložené konfigurace vrácené webhookem [dynamické konfigurace hovoru](/cs/guides/dynamic-call-config). Webhook, který vrátí `agent_id`, používá kroky daného agenta. ## Limity | Limit | Hodnota | | --- | --- | | Kroky na agenta | 100 | | Shromážděné hodnoty na krok | 20 | | Cíle předání na agenta | 8 | | Agenti dosažitelní během jednoho hovoru | 8 | | Velikost JSON `steps` | 200 KB | | `instructions` kroku | 20 000 znaků | | Řádek `say` | 1 000 znaků | | Uložený výsledek `on_enter_tool` | 4 KB | Uložení, které porušuje pravidlo, vrátí `400` s cestou k chybnému poli, například `steps.steps[2].transitions[0].to`. Názvy nástrojů v `tools` a `on_enter_tool` musí být nástroje připojené k agentovi. Jazyky pro jednotlivé kroky, skriptované kroky, které vynechávají model, a shromážděné hodnoty uvnitř řádků say nejsou podporovány. ## Importovaní agenti [Import](/cs/guides/import-agents) z Retell, Bland, Vapi nebo ElevenLabs převede agenty s více prompty, toky, cesty a pracovní postupy jako kroky a týmy a předání agentů jako předání mezi importovanými agenty. Stránka kontroly zobrazuje obojí před importem. ## Příklad: příjem pacienta v zubní ordinaci Tři kroky v pořadí: přivítání, shromáždění údajů o pacientovi, rezervace. ```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": [] } ] } } ``` Připravte jej pomocí `PATCH /v1/agents/{agent_id}`, vyzkoušejte jej pomocí **Mluvit** a poté nasaďte. Krok `details` nemůže předat rezervaci, dokud nejsou shromážděny jméno, datum narození a důvod; `new_patient` je volitelný. ## Příklad: větev s omezením podle věku Model může mluvit s kýmkoli, ale kód rozhoduje, kdo získá termín. Shromážděte věk a poté podle něj směrujte, než se zohlední vlastní volba modelu. ```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"} ] } ``` Volající, který řekne patnáct, přejde do `guardian` bez ohledu na to, co model rozhodne. Všichni ostatní přejdou do `book`. Oba jsou běžné kroky jinde v grafu. ## Příklad: krok webhooku pro vyhledání účtu Volající sdělí číslo účtu, vyhledávání se spustí při vstupu do dalšího kroku a jeho výsledek vybere trasu. Kroky `not_found`, `collections` a `support` jsou pro stručnost vynechány. ```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` přijme `account_number`, protože jeho parametr má tento název. Pokud tělo odpovědi obsahuje `"found": false`, hovor přejde do `not_found`. Pokud je jeho `account_status` `past_due` nebo `suspended`, přejde do `collections`. Aktivní účet zůstane v `lookup`, kde model pomůže a pokračuje do `support`. Chcete-li neúspěšné vyhledání odeslat do vlastního kroku, nejprve přidejte podmínky pro stav: odpověď s chybou uloží svůj stavový kód, takže ji zachytí `{"value": "lookup_account_result.status", "op": "gte", "target": 400}`, a při vypršení časového limitu nebo bez odpovědi se uloží `"error"`, takže tento případ zachytí `{"value": "lookup_account_result.status", "op": "eq", "target": "error"}`. ## Příklad: recepce k fakturaci Dva agenti. Recepce (agent `412`) přijímá každý hovor a předává dotazy k fakturaci agentovi pro fakturaci (agent `413`) s vlastním promptem, nástroji a hlasem. Na recepci: ```json { "handoffs": [ {"agent_id": 413, "when": "The caller asks about a bill, a payment or a refund"} ] } ``` U agenta pro fakturaci, aby mohl volajícího předat zpět: ```json { "handoffs": [ {"agent_id": 412, "when": "The billing question is resolved and the caller needs something else"} ] } ``` Recepce řekne krátkou větu, například „Spojím vás s naším týmem pro fakturaci“, a agent pro fakturaci se představí a naváže na konverzaci tam, kde recepce skončila. Když fakturace předá hovor zpět, recepce pokračuje tam, kde byla, aniž by volajícího znovu zdravila. Produkt hovoru, jazyky, oznámení o souhlasu a další nastavení hovoru zůstávají u recepce, protože hovor přijala. Pokud fakturace potřebuje pouze vlastní instrukce, nikoli vlastního agenta, použijte místo toho globální krok na recepci. Po zodpovězení dotazu se hovor vrátí do kroku, ve kterém se volající nacházel: ```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" } ``` ## Další kroky Napište sdílené pokyny a pokyny pro kroky, které fungují i po telefonu. Vytvořte nástroje, které volají vaše kroky a kroky webhooků. Před nasazením spusťte stejné scénáře pro každou větev. Všechna pole agentů, koncepty a nasazení.