> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt. # Ustrukturyzowane procedury ## Omówienie Ustrukturyzowana procedura to [procedura](/docs/pl/eleven-agents/customization/procedures) wykonująca stałą sekwencję kroków. [Procedura swobodna](/docs/pl/eleven-agents/customization/procedures/free-form-procedures) to wskazówki w języku naturalnym, które agent interpretuje i dostosowuje do sytuacji. Ustrukturyzowana procedura to uporządkowana lista kroków określonych typem, którą agent wykonuje po kolei zawsze, gdy ma zastosowanie. Użyj ustrukturyzowanej procedury, gdy konkretne kroki muszą przebiegać tak samo przy każdej rozmowie: podczas weryfikacji tożsamości dzwoniącego, eskalacji zgłoszenia lub przyjmowania płatności. Tworzysz ją jako krótką listę kroków w prostym języku. Jak każda procedura, ustrukturyzowana procedura ma wyzwalacz opisujący, kiedy ma zastosowanie. Gdy rozmowa pasuje do wyzwalacza, agent wykonuje kroki procedury po kolei, a potem wraca do reszty rozmowy. ![Edytor ustrukturyzowanej procedury ](/docs/_fern-img/bc996f67b2afad8f1de5abe8febcf8af3766b4f098627b0ae60e0456b3c2703b.webp) ## Kiedy używać ustrukturyzowanej procedury Użyj ustrukturyzowanej procedury, gdy konkretne kroki muszą za każdym razem przebiegać tak samo, ale nadal chcesz szybko tworzyć ją w prostych krokach. Ustrukturyzowane procedury łatwiej napisać niż workflow, ale oferują mniej możliwości. Porównanie z procedurami swobodnymi, workflow i promptem systemowym znajdziesz w artykule [Kiedy używać procedur](/docs/pl/eleven-agents/customization/procedures#when-to-use-procedures). ## Elementy ustrukturyzowanej procedury Ustrukturyzowana procedura ma trzy części: nazwę, wyzwalacz i uporządkowaną listę kroków. ### Nazwa Krótka etykieta identyfikująca procedurę w panelu. Nazwa nigdy nie jest wysyłana do LLM, więc nie wpływa na zachowanie agenta. ### Wyzwalacz Opis w prostym języku określający, kiedy agent powinien uruchomić tę procedurę, na przykład *Gdy użytkownik prosi o zwrot środków za zamówienie*. Agent porównuje intencję użytkownika z wyzwalaczem każdej procedury i uruchamia pasującą, dlatego wyzwalacze powinny być konkretne i różne. Agent widzi tylko tekst wyzwalacza, nigdy nazwę ani identyfikator procedury. Wyzwalacz działa tak samo jak w każdej procedurze; zobacz [Tworzenie wyzwalaczy](/docs/pl/eleven-agents/customization/procedures/free-form-procedures#writing-triggers). Pozostaw wyzwalacz pusty, aby procedura była podprocedurą uruchamianą tylko wtedy, gdy wywoła ją inna procedura. ### Kroki Treść procedury to uporządkowana lista kroków określonych typem. Dostępnych jest kilka typów kroków, które łączysz, aby opisać zadanie. | Krok | Działanie | | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Zapytaj** | Prosi użytkownika o informacje i czeka. Pyta, aż użytkownik odpowie. To jedyny krok, który czeka na użytkownika. | | **Przekaż** | Agent przekazuje coś własnymi słowami, a potem przechodzi do kolejnego kroku. | | **Powiedz** | Agent wypowiada dokładną wiadomość słowo w słowo, a potem przechodzi do kolejnego kroku. Krok Powiedz może mieć osobno skonfigurowane tłumaczenie dla każdego języka obsługiwanego przez agenta. | | **Narzędzie** | Wywołuje konkretne narzędzie. Możesz w prostym języku poinstruować LLM, jak wywołać narzędzie, lub jawnie ustawić wartości parametrów, gdy wymagana jest maksymalna deterministyczność. Możesz też określić kroki uruchamiane po nieudanym wywołaniu narzędzia. | | **Jeśli** | Sprawdza po kolei co najmniej jeden warunek i wykonuje kroki pierwszego dopasowania. Opcjonalne W przeciwnym razie uruchamia się, gdy nic nie pasuje. | | **Podprocedura** | Uruchamia inną ustrukturyzowaną procedurę. Po zakończeniu jej kroków sterowanie wraca do kolejnego kroku tej procedury (wywołującej). | | **Narzędzie systemowe** | Wykonuje wbudowaną akcję systemową. Obecnie obsługiwane jest tylko zakończenie rozmowy. | | **Ponów** | Ponownie uruchamia obsługę błędu kroku Narzędzie, w tym wywołanie narzędzia, maksymalnie trzy razy. Dostępne tylko w obsłudze błędu kroku Narzędzie. | ![Menu typu kroku ustrukturyzowanej procedury ](/docs/_fern-img/14976a6b9979d21fd7c77541a49e7475f8aa0764af4940746d3390804e7c4598.webp) Nie każdy krok może występować wszędzie. W gałęzi Jeśli możesz użyć każdego kroku poza kolejnym Jeśli lub Ponów. W obsłudze błędu kroku Narzędzie możesz użyć każdego kroku poza Jeśli lub kolejnym Narzędzie. ## Dokumentacja kroków API `content` ustrukturyzowanej procedury to dokument zakodowany w JSON zawierający tablicę `steps`. Każdy krok to obiekt identyfikowany przez `type`. Wyzwalacz to osobne pole najwyższego poziomu procedury, a nie część `content`. Ładunki API i SDK używają `type: "deterministic"` dla samej procedury. ### Zapytaj Krok Zapytaj nakazuje agentowi poprosić o informacje i czekać, aż użytkownik poda odpowiednią odpowiedź. * Typ API: `ask` * `instruction`: Wymagany, niepusty ciąg znaków. ```json focus={1-4} { "type": "ask", "instruction": "Ask the user for their order ID." } ``` ### Przekaż Krok Przekaż nakazuje agentowi wygenerować pojedynczą wiadomość własnymi słowami. Nie czeka na odpowiedź użytkownika przed przejściem dalej. * Typ API: `tell` * `instruction`: Wymagany, niepusty ciąg znaków. ```json focus={1-4} { "type": "tell", "instruction": "Explain that the refund normally takes five to ten business days." } ``` ### Powiedz Krok Powiedz wypowiada podany tekst dokładnie tak, jak został zapisany, a następnie przechodzi dalej. Podaj `message_translations`, aby przekazać agentowi dokładną wiadomość dla każdego dodatkowego obsługiwanego języka, z kluczem będącym kodem języka. * Typ API: `say` * `message`: Wymagany, niepusty ciąg znaków. * `message_translations`: Opcjonalny obiekt mapujący kod języka na `{ "value": "..." }`. ```json focus={1-7} { "type": "say", "message": "Your refund has been submitted.", "message_translations": { "es": { "value": "Su reembolso ha sido enviado." } } } ``` ### Jeśli, w przeciwnym razie jeśli i w przeciwnym razie Krok Jeśli zawiera co najmniej jedną uporządkowaną gałąź warunkową. Uruchamia się pierwsza pasująca gałąź. Opcjonalna tablica `fallback` to gałąź W przeciwnym razie. * Typ API: `branch` * `branches`: Wymagana, niepusta lista gałęzi warunkowych. * `fallback`: Opcjonalna lista kroków W przeciwnym razie. * Każda gałąź wymaga `condition` i niepustej listy `steps`. ```json focus={1-23} { "type": "branch", "branches": [ { "condition": { "type": "llm", "condition": "The user is on an annual plan." }, "steps": [ { "type": "say", "message": "Your annual plan is eligible for a prorated refund." } ] } ], "fallback": [ { "type": "tell", "instruction": "Explain that the account's plan could not be determined." } ] } ``` Działa to jak if/else-if/else: 1. Warunki są sprawdzane po kolei. 2. Uruchamia się pierwsza pasująca gałąź. 3. Jeśli żaden warunek nie pasuje, uruchamia się `fallback`. 4. Po zakończeniu gałęzi procedura wraca do głównej sekwencji. Powyższy przykład używa warunku tekstowego, który model ocenia w języku naturalnym. Warunki mogą też być wyrażeniami opartymi na zmiennych dynamicznych: ```json focus={1-14} { "type": "expression", "expression": { "type": "eq_operator", "left": { "type": "dynamic_variable", "name": "plan_tier" }, "right": { "type": "string_literal", "value": "annual" } } } ``` Warunek wyrażeniowy sprawdza zmienne dynamiczne, które są wypełniane wynikami narzędzia lub ustawiane na początku rozmowy. Nie może odczytać ostatniej odpowiedzi użytkownika. Aby rozgałęzić działanie na podstawie wypowiedzi użytkownika, użyj warunku tekstowego. Wszystkie gałęzie w jednym kroku Jeśli muszą używać tego samego typu warunku: `llm` albo `expression`. ### Narzędzie Krok Narzędzie wywołuje konkretne narzędzie. * Typ API: `tool_call` * `tool_id`: Wymagany, niepusty identyfikator narzędzia. Narzędzie musi być przypisane do agenta. * `tool_name`: Wymagana nazwa narzędzia zgodna z narzędziem. * `instruction`: Opcjonalna instrukcja opisująca sposób wywołania narzędzia. * `schema_overrides`: Opcjonalne stałe wartości parametrów narzędzia. * `on_failure`: Opcjonalna obsługa błędu. ```json focus={1-6} { "type": "tool_call", "tool_id": "tool_abc123", "tool_name": "lookup_order", "instruction": "Look up the order using the order ID provided by the user." } ``` #### Stałe wartości parametrów Użyj `schema_overrides`, gdy parametr zawsze musi mieć konkretną wartość. Model nie widzi ani nie wybiera nadpisanego parametru. Klucze to ścieżki parametrów w schemacie narzędzia; każda wartość wskazuje źródło: | `source` | Pola | Działanie | | ------------------ | ---------------------- | ------------------------------------------------------------------ | | `constant` | `constant_value` | Zawsze wysyła podaną wartość. | | `dynamic_variable` | `dynamic_variable` | Wysyła bieżącą wartość nazwanej zmiennej dynamicznej. | | `llm` | `prompt` (opcjonalnie) | Pozwala modelowi wybrać wartość z opcjonalnym nadpisaniem promptu. | | `omit` | | Pomija parametr w wywołaniu. | ```json focus={1-9} { "type": "tool_call", "tool_id": "tool_abc123", "tool_name": "update_ticket", "schema_overrides": { "request_body.status": { "source": "constant", "constant_value": "pending" }, "request_body.ticket_id": { "source": "dynamic_variable", "dynamic_variable": "ticket_id" } } } ``` #### Obsługa błędów Bez `on_failure` nieudane wywołanie narzędzia kończy rozmowę. Dodaj `on_failure`, aby zamiast tego uruchomić kroki odzyskiwania. * `fallback`: Wymagana, niepusta lista kroków uruchamianych, gdy narzędzie zawiedzie. * `branches`: Zarezerwowane dla warunkowej obsługi błędów. Pozostaw puste. ```json focus={1-14} { "type": "tool_call", "tool_id": "tool_abc123", "tool_name": "lookup_order", "on_failure": { "branches": [], "fallback": [ { "type": "tell", "instruction": "Explain that the order could not be retrieved and offer to connect the user with support." } ] } } ``` Obsługa błędu może zawierać kroki Zapytaj, Przekaż, Powiedz, Podprocedura, Narzędzie systemowe i Ponów. Nie może zawierać kroków Narzędzie ani Jeśli. Po uruchomieniu obsługi procedura przechodzi do kroku po kroku Narzędzie. ### Ponów Krok Ponów ponownie uruchamia obsługę błędu, w której się znajduje, w tym wywołanie narzędzia. Każda próba ponownie wywołuje narzędzie i, jeśli znów zawiedzie, ponownie uruchamia każdy krok obsługi. Gdy próby się wyczerpią, rozmowa się kończy. * Typ API: `retry` * `max_retries`: Opcjonalna liczba całkowita od 1 do 3. Domyślnie 1. * Wartość liczy próby po pierwotnym wywołaniu narzędzia. * Ponów jest prawidłowe tylko w `on_failure`. * Ponów musi być ostatnim krokiem obsługi błędu, ponieważ późniejsze kroki byłyby nieosiągalne. ```json focus={1-4} { "type": "retry", "max_retries": 2 } ``` ### Podprocedura Krok Podprocedura uruchamia inną ustrukturyzowaną procedurę. Po zakończeniu kroków tej procedury wykonanie wraca do kroku po kroku Podprocedura. * Typ API: `sub_procedure` * `procedure_id`: Wymagany, niepusty identyfikator procedury. * Cel musi istnieć w tym samym agencie. * Cel musi być ustrukturyzowaną procedurą. * Procedura nie może wywoływać samej siebie. ```json focus={1-4} { "type": "sub_procedure", "procedure_id": "agtprc_6qbpwdq8n01bxhk44bgjy6f10ck3" } ``` ### Narzędzie systemowe Krok Narzędzie systemowe wykonuje wbudowaną akcję systemową. * Typ API: `system_tool` * `system_tool_name`: Wymagana nazwa narzędzia systemowego. * Obecnie obsługiwane jest tylko `end_call`. W przyszłości mogą zostać dodane kolejne narzędzia systemowe. * Ponieważ `end_call` jest końcowe, musi być ostatnim krokiem w zawierającej je sekwencji, gałęzi lub obsłudze błędu. ```json focus={1-4} { "type": "system_tool", "system_tool_name": "end_call" } ``` ## Reguły walidacji Publikacja agenta lub zapisanie jego wersji roboczej odrzuca ustrukturyzowaną procedurę, która narusza którąkolwiek z tych reguł. Błąd wskazuje problematyczny krok jego ścieżką. * Nie można umieszczać dwóch kroków Jeśli bezpośrednio po sobie. * Kroki Jeśli nie mogą być zagnieżdżone. * Krok Jeśli z warunkami wyrażeniowymi nie może bezpośrednio następować po kroku Zapytaj. * Wszystkie warunki w jednym kroku Jeśli muszą mieć ten sam typ: `llm` albo `expression`. * Ponów może występować tylko w `on_failure` i musi być tam ostatnim krokiem. * `end_call` musi być ostatnim krokiem na liście, na której występuje. * `fallback` obsługi błędu musi zawierać co najmniej jeden krok. * Podprocedura musi wskazywać istniejącą ustrukturyzowaną procedurę w tym samym agencie, a nie samą siebie. * `tool_id` musi być narzędziem agenta, `tool_name` musi się zgadzać, a `schema_overrides` musi odpowiadać schematowi narzędzia. * Lista `steps`, każda `instruction` i każda `message` muszą być niepuste. Informacje o zmianie struktury procedury, która narusza jedną z tych reguł, znajdziesz w [Dobrych praktykach](#best-practices). ## Pełny przykład API Ten przykład obsługuje anulowanie zamówienia na podstawie statusu wysyłki. Ustawia stałą wartość parametru narzędzia, obsługuje nieudane wywołanie narzędzia, wywołuje inną ustrukturyzowaną procedurę, a następnie kończy rozmowę. ```json maxLines=30 { "steps": [ { "type": "ask", "instruction": "Ask the user for their order ID." }, { "type": "branch", "branches": [ { "condition": { "type": "llm", "condition": "The user says the order has already shipped." }, "steps": [ { "type": "tell", "instruction": "Explain that shipped orders must be returned before they can be refunded." } ] }, { "condition": { "type": "llm", "condition": "The user says the order has not shipped." }, "steps": [ { "type": "tool_call", "tool_id": "tool_abc123", "tool_name": "cancel_order", "instruction": "Cancel the order using the order ID provided by the user.", "schema_overrides": { "request_body.notify_customer": { "source": "constant", "constant_value": true } }, "on_failure": { "branches": [], "fallback": [ { "type": "tell", "instruction": "Apologize that the cancellation did not go through and say you will try once more." }, { "type": "retry", "max_retries": 1 } ] } } ] } ], "fallback": [ { "type": "ask", "instruction": "Ask whether the order has already shipped." } ] }, { "type": "sub_procedure", "procedure_id": "agtprc_6qbpwdq8n01bxhk44bgjy6f10ck3" }, { "type": "say", "message": "Thank you for contacting us. Goodbye.", "message_translations": { "es": { "value": "Gracias por contactarnos. Adiós." } } }, { "type": "system_tool", "system_tool_name": "end_call" } ] } ``` ## Jak działa ustrukturyzowana procedura Przekształcenie kroków ustrukturyzowanej procedury do postaci wykonywanej przez agenta nazywa się kompilacją. Platforma kompiluje każdą ustrukturyzowaną procedurę, gdy zapiszesz wersję roboczą agenta lub opublikujesz agenta; autorzy nigdy nie muszą niczego kompilować samodzielnie. Gdy żądanie użytkownika pasuje do wyzwalacza procedury, platforma wchodzi do procedury i wykonuje jej kroki po kolei. W trakcie wykonywania ustrukturyzowanej procedury agent skupia się na każdym kroku osobno. Gdy dotrze do końca, platforma zwraca sterowanie do reszty rozmowy. Krawędzie workflow nie mogą prowadzić do ustrukturyzowanej procedury ani z niej wychodzić. Użyj kroku Podprocedura, aby połączyć ustrukturyzowane procedury. Platforma zarządza wejściem z pasującego wyzwalacza i zakończeniem, w tym zwróceniem sterowania do węzła workflow, w którym procedura się rozpoczęła. Poniższe reguły opisują działanie kroków podczas wykonywania. #### Tylko Zapytaj czeka na użytkownika Każdy krok poza Zapytaj uruchamia się od razu, a sterowanie przechodzi do kolejnego kroku w tej samej turze. Krok Przekaż lub Powiedz przekazuje wiadomość i kontynuuje. Poza Zapytaj nie ma kroku, który wstrzymuje rozmowę, ani kroku kończącego bieżącą turę. Jeśli potrzebujesz danych od użytkownika, użyj kroku Zapytaj. Jeśli rozmowa ma się zakończyć, użyj narzędzia systemowego `end_call`. #### Dotarcie do końca procedury nie kończy tury Gdy ostatni krok się zakończy, procedura dobiega końca, a agent wraca do reszty rozmowy z nadal otwartą turą, więc może powiedzieć więcej. Gdy podprocedura się zakończy, sterowanie wraca do kolejnego kroku procedury, która ją wywołała. #### Kroki Narzędzie rozróżniają tylko sukces i błąd Krok Narzędzie nie może rozgałęziać działania według kodu statusu ani treści odpowiedzi. Jeśli narzędzie się powiedzie, procedura jest kontynuowana. Jeśli zawiedzie, a krok nie ma obsługi błędu, rozmowa się kończy. Jeśli ją ma, uruchamiają się kroki obsługi, a procedura przechodzi do kolejnego kroku. Krok Ponów w obsłudze ponownie uruchamia narzędzie i, jeśli znów zawiedzie, każdy krok obsługi, aż narzędzie się powiedzie lub wyczerpią się próby. Jeśli się wyczerpią, rozmowa się kończy. #### Kroki Jeśli przechodzą dalej, gdy nic nie pasuje Warunki są sprawdzane po kolei i uruchamia się pierwsze dopasowanie. Gałąź W przeciwnym razie uruchamia się, gdy nic nie pasuje. Jeśli nie ma W przeciwnym razie i nic nie pasuje, procedura przechodzi do kroku po Jeśli. Nieobsłużony przypadek nie jest błędem. #### Gałęzie Jeśli nie przekazują stanu dalej Nic, co zostanie ustalone w gałęzi Jeśli, nie jest pamiętane przez późniejsze kroki. Jeśli coś poznanego w gałęzi jest później potrzebne, zapisz to jawnie za pomocą wywołania narzędzia lub zmiennej dynamicznej. #### Kroki Zapytaj, Przekaż i Powiedz nie mają narzędzi Tylko kroki Narzędzie mogą wywoływać narzędzia. Nie musisz informować kroku Zapytaj, Przekaż ani Powiedz, aby nie wywoływał narzędzi — nie może tego zrobić. ## Zarządzanie ustrukturyzowaną procedurą #### Tworzenie w panelu Otwórz agenta w [panelu](https://elevenlabs.io/app/agents), a następnie wybierz **Procedury**. Użyj **+**, aby utworzyć ustrukturyzowaną procedurę. Dodaj wyzwalacz, wybierz typ dla każdego kroku i opublikuj zmiany agenta. Panel waliduje ustrukturyzowane procedury podczas edycji. Jeśli procedura narusza [regułę walidacji](#validation-rules), przycisk **Opublikuj** wyświetla stan błędu, karta **Procedury** pokazuje plakietkę błędu, a podgląd nie uruchomi się, dopóki procedura nie zostanie poprawiona. Wybierz wskaźnik błędu, aby sprawdzić, której procedury i kroku dotyczy problem. ![Edytor ustrukturyzowanej procedury z przyciskiem Opublikuj w stanie błędu i plakietką 1 Error ](/docs/_fern-img/e406c33fac3966fab26d5d07e10d364a475fc4a56fd75aad2e23edbb0d1940d5.webp) ![Okno szczegółów walidacji z listą procedury powodującej błąd oraz kroku, który wymaga wiadomości](/docs/_fern-img/a1cc889b2d0e68ce23725609b531938d0f7c417b1c6f4375103531eaae4ada63.webp) #### Zarządzanie przez CLI [CLI ElevenLabs](/docs/pl/eleven-agents/operate/cli) tworzy i publikuje ustrukturyzowane procedury tymi samymi poleceniami co procedury swobodne. Ustaw `type` na `deterministic` i przekaż kroki jako ciąg znaków zakodowany w JSON w `content`. ```bash CONTENT=$(jq -n '{ trigger: "When the user asks to refund an order", steps: [{ type: "ask", instruction: "Ask for the order ID." }] }') elevenlabs agents procedures create \ --agent-id agent_7101k5zvyjhmfg983brhmhkd98n6 \ --branch-id agtbranch_0901k4aafjxxfxt93gd841r7tv5t \ --json "$(jq -n --arg content "$CONTENT" '{ name: "Refund request", type: "deterministic", trigger: "When the user asks to refund an order", content: $content }')" elevenlabs agents update \ --agent-id agent_7101k5zvyjhmfg983brhmhkd98n6 \ --branch-id agtbranch_0901k4aafjxxfxt93gd841r7tv5t \ --json '{"version_description": "Publish refund procedure"}' ``` Publikacja waliduje każdą ustrukturyzowaną procedurę w gałęzi. Jeśli któraś jest nieprawidłowa, polecenie kończy się kodem różnym od zera i wyświetla błędy według identyfikatora procedury. Popraw wersję roboczą procedury i opublikuj ponownie. #### Zarządzanie przez API Ładunki API i SDK używają `type: "deterministic"` dla ustrukturyzowanych procedur. Ich `content` to dokument zakodowany w JSON. ### Wymagania wstępne * Klucz API ElevenLabs w zmiennej środowiskowej `ELEVENLABS_API_KEY`. * Docelowe `agent_id` i `branch_id`. Operacje na gałęziach opisuje [Wersjonowanie agentów](/docs/pl/eleven-agents/operate/versioning). * Wersja `2.60.0` lub nowsza pakietu Python `elevenlabs` albo pakietu JavaScript `@elevenlabs/elevenlabs-js`. Edycje API są prywatne dla twojego użytkownika w wybranej gałęzi, dopóki nie opublikujesz nowej wersji agenta. ### Utwórz lub zaktualizuj wersję roboczą Utwórz ustrukturyzowaną procedurę przez `POST /procedures` i ustaw `type` na `deterministic`. Zaktualizuj istniejącą procedurę przez `PATCH /procedures/{procedure_id}/draft`, jak pokazano poniżej. Ustaw `trigger` jako pole najwyższego poziomu. Zakoduj dokument kroków w JSON w `content`, zamiast wysyłać zagnieżdżony obiekt. ```python focus={6-18} import json from elevenlabs import ElevenLabs elevenlabs = ElevenLabs() elevenlabs.conversational_ai.agents.procedures.drafts.update( agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6", branch_id="agtbranch_0901k4aafjxxfxt93gd841r7tv5t", procedure_id="agtprc_6qbpwdq8n01bxhk44bgjy6f10ck3", name="Refund request", type="deterministic", trigger="When the user asks to refund an order", content=json.dumps( { "steps": [{"type": "ask", "instruction": "Ask for the order ID."}], } ), ) ``` ```typescript focus={5-17} import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js"; const elevenlabs = new ElevenLabsClient(); await elevenlabs.conversationalAi.agents.procedures.drafts.update( "agent_7101k5zvyjhmfg983brhmhkd98n6", "agtbranch_0901k4aafjxxfxt93gd841r7tv5t", "agtprc_6qbpwdq8n01bxhk44bgjy6f10ck3", { name: "Refund request", type: "deterministic", trigger: "When the user asks to refund an order", content: JSON.stringify({ steps: [{ type: "ask", instruction: "Ask for the order ID." }], }), } ); ``` ```bash focus={1-9} curl -X PATCH "https://api.elevenlabs.io/v1/convai/agents/agent_7101k5zvyjhmfg983brhmhkd98n6/branches/agtbranch_0901k4aafjxxfxt93gd841r7tv5t/procedures/agtprc_6qbpwdq8n01bxhk44bgjy6f10ck3/draft" \ -H "xi-api-key: $ELEVENLABS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Refund request", "type": "deterministic", "trigger": "When the user asks to refund an order", "content": "{\"steps\":[{\"type\":\"ask\",\"instruction\":\"Ask for the order ID.\"}]}" }' ``` Zapisanie wersji roboczej procedury nie waliduje jej kroków. Walidacja uruchamia się podczas publikacji lub gdy zapisujesz wersję roboczą agenta przez `POST /v1/convai/agents/{agent_id}/drafts`. ### Opublikuj zmiany Opublikuj przez [Aktualizuj agenta](/docs/pl/api-reference/agents/update). Publikacja waliduje każdą ustrukturyzowaną procedurę w gałęzi i, jeśli wszystkie przejdą walidację, publikuje procedury w nowej wersji. Żądanie nie potrzebuje pola `workflow`. ```python focus={5-8} from elevenlabs import ElevenLabs elevenlabs = ElevenLabs() elevenlabs.conversational_ai.agents.update( agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6", branch_id="agtbranch_0901k4aafjxxfxt93gd841r7tv5t", ) ``` ```typescript focus={5-7} import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js"; const elevenlabs = new ElevenLabsClient(); await elevenlabs.conversationalAi.agents.update("agent_7101k5zvyjhmfg983brhmhkd98n6", { branchId: "agtbranch_0901k4aafjxxfxt93gd841r7tv5t", }); ``` ```bash focus={1-5} curl -X PATCH \ "https://api.elevenlabs.io/v1/convai/agents/agent_7101k5zvyjhmfg983brhmhkd98n6?branch_id=agtbranch_0901k4aafjxxfxt93gd841r7tv5t" \ -H "xi-api-key: $ELEVENLABS_API_KEY" \ -H "Content-Type: application/json" \ -d '{}' ``` Jeśli ustrukturyzowana procedura jest nieprawidłowa, publikacja zwraca `400` i nic nie zapisuje: ```json { "detail": { "status": "procedure_validation_failed", "message": "Structured procedures failed validation.", "data": { "errors": { "agtprc_6qbpwdq8n01bxhk44bgjy6f10ck3": [ { "path": "steps[0].ask.instruction", "message": "Step 1: Ask step requires an instruction" } ] } } } } ``` `errors` jest indeksowane identyfikatorem procedury. Każdy wpis wskazuje pole i krok powodujące błąd. Popraw wersję roboczą procedury i opublikuj ponownie. Informacje o usuwaniu wersji roboczych i zachowaniu przy odrzucaniu zmian znajdziesz w artykule [Zarządzanie procedurami](/docs/pl/eleven-agents/customization/procedures#manage-procedures), a pełne schematy endpointów w [dokumentacji API procedur](/docs/pl/api-reference/agents/procedures/). ## Dobre praktyki Każdy typ kroku już wymusza własne działanie, więc rzadko musisz je opisywać. Określ cel każdego kroku, a typ kroku zajmie się resztą. Poniższe wskazówki dotyczą przypadków, które warto zrobić dobrze. Aby przetestować procedurę strukturalną, postępuj zgodnie z [Iterowaniem procedury](/docs/pl/eleven-agents/customization/procedures/free-form-procedures#iterating-on-a-procedure). ### Wybór typów kroków #### Zadaj jedno pytanie w każdym kroku Ask Krok Ask czeka na jedną odpowiedź. Jeśli połączysz kilka pytań w jednej instrukcji, agent zwykle pominie część z nich lub je połączy. Użyj jednego Ask dla każdej informacji. #### Używaj Tell do stwierdzeń, a Ask do pytań Krok Tell przekazuje komunikat i przechodzi dalej bez czekania. Tell sformułowany jako pytanie nigdy nie otrzyma odpowiedzi. Jeśli krok wymaga odpowiedzi użytkownika, użyj Ask. #### Dodaj jasny warunek wyjścia do Ask, gdy samo pytanie nie wystarcza Krok Ask przechodzi dalej po otrzymaniu odpowiedniej odpowiedzi. Jeśli z pytania nie wynika jasno, co uznajesz za odpowiedź, zapisz to w instrukcji, na przykład \_Poproś o identyfikator zamówienia; prawidłowy identyfikator ma osiem cyfr \_. #### Wybierz Tell dla swobodnego sformułowania, Say dla dokładnych słów Użyj kroku Tell, gdy agent ma sam ułożyć komunikat, a Say, gdy brzmienie musi być dosłowne lub przetłumaczone. Oba przekazują dokładnie jeden komunikat, więc nie trzeba instruować kroku, by wysłał pojedynczy komunikat. #### Nie każ krokom bez narzędzi unikać narzędzi Kroki Ask, Tell i Say nie mogą wywoływać narzędzi. Dodanie do nich *nie wywołuj żadnych narzędzi* tylko zaśmieca instrukcję i nie zmienia działania. ### Struktura procedury #### Nie wstawiaj wypełniaczy między dwa kroki If Nie można umieścić dwóch kroków If jeden po drugim. Wstawienie niezwiązanego Tell lub Say między nimi, by spełnić tę regułę, sprawia, że agent mówi coś, czego nie powinien. Zamiast tego dodaj drugą decyzję do pierwszego If jako dodatkowe gałęzie Else if lub przenieś ją do podprocedury. #### Umieść zagnieżdżone decyzje w podprocedurze Kroki If nie mogą być zagnieżdżone. Gdy jedna decyzja zależy od drugiej, umieść wewnętrzną decyzję w osobnej procedurze strukturalnej i wywołaj ją krokiem Sub-procedure z gałęzi, która jej potrzebuje. #### Dodaj Else, gdy ważne jest „żadne z powyższych” Krok If bez Else przechodzi do następnego kroku, gdy nic nie pasuje. Jeśli niedopasowany przypadek powinien działać inaczej, dodaj dla niego gałąź Else. #### Zapisuj wszystko, czego potrzebuje późniejszy krok Decyzje podjęte w gałęzi If nie są później pamiętane. Jeśli późniejszy krok zależy od czegoś ustalonego w gałęzi, zapisz to wywołaniem narzędzia lub zmienną dynamiczną w tej gałęzi. #### Umieszczaj warunki wyrażeń po narzędziu, które je wypełnia Warunki wyrażeń sprawdzają zmienne dynamiczne. Umieść krok If, który ich używa, zaraz po kroku Tool, który ustawia te zmienne. Aby rozgałęzić procedurę na podstawie słów użytkownika, użyj warunku tekstowego. #### Wydziel wspólne kroki do podprocedury Gdy kilka procedur strukturalnych ma tę samą sekwencję, na przykład przekazanie sprawy człowiekowi, umieść ją w jednej procedurze strukturalnej z pustym wyzwalaczem i wywołuj ją z każdej z nich. Skopiowane sekwencje z czasem zaczynają się różnić. ### Praca z narzędziami #### Steruj krokiem Tool za pomocą If, nie jego instrukcji Krok Tool zawsze wywołuje swoje narzędzie. Warunek zapisany w instrukcji, taki jak \_pomiń to, jeśli zgłoszenie ma już tag \_, nie może zapobiec wywołaniu. Jeśli wywołanie nie powinno zawsze nastąpić, umieść warunek w kroku If przed krokiem Tool. #### Ustawiaj wartości parametrów zamiast je opisywać Gdy parametr musi zawsze mieć określoną wartość, ustaw ją za pomocą nadpisania `constant` w `schema_overrides`. Instrukcja typu *zawsze ustaw status na pending* prosi model o zastosowanie się do niej; nadpisanie jest wymuszane i nie można go pominąć. #### Dodaj obsługę błędów do każdego kroku Tool Bez `on_failure` każdy błąd narzędzia kończy rozmowę. Dodaj obsługę, która informuje użytkownika, co się stało, i ponawia próbę, przekazuje sprawę dalej lub kontynuuje. #### Ogranicz kroki Tool do wywołania narzędzia Krok Tool tylko uruchamia narzędzie; agent nie może wtedy mówić ani podejmować decyzji. Aby porozmawiać z użytkownikiem lub rozgałęzić procedurę na podstawie wyniku narzędzia, umieść to w osobnym kroku przed lub po kroku Tool. ### Pisanie instrukcji #### Opisuj tylko bieżący krok Procedura kontroluje, co uruchamia się dalej, a agent nie wie o późniejszych krokach podczas wykonywania bieżącego. Niech kolejność kroków zajmie się sekwencją. #### Nie próbuj kończyć tury tekstem Zdania zapisane w instrukcjach kroków, takie jak *to jest ostatnia wiadomość tej tury*, proszą agenta o wymuszenie granicy, której platforma nie obsługuje. Użyj kroku Ask, aby czekać na użytkownika, lub narzędzia systemowego `end_call`, aby zakończyć rozmowę. #### Zasady globalne zachowaj w prompcie systemowym Ton, formatowanie, pożegnania i zasady odmowy należą do [promptu systemowego ](/docs/pl/eleven-agents/best-practices/prompting-guide). Instrukcja kroku powinna określać tylko to, co jest specyficzne dla danego kroku. ### Łączenie procedur Ogólne wskazówki dotyczące łączenia procedur odnoszą się też do procedur strukturalnych; zobacz [Łączenie procedur](/docs/pl/eleven-agents/customization/procedures/free-form-procedures#composing-procedures) na stronie Procedury swobodne. Jeden wzorzec dotyczy konkretnie łączenia typów: procedura swobodna może odwoływać się do procedury strukturalnej. Obsługę otwartych sytuacji zachowaj w procedurze swobodnej, a części, które zawsze muszą działać tak samo, takie jak weryfikacja tożsamości czy przekazanie sprawy dalej, deleguj do procedury strukturalnej. ## Ograniczenia * Kroki If nie mogą być zagnieżdżone ani umieszczone jeden po drugim. * Jedynym obsługiwanym narzędziem systemowym jest `end_call`. * Procedury strukturalne nie mogą odwoływać się do dokumentów bazy wiedzy. * Nie można zakończyć bieżącej tury po ukończeniu procedury; agent utrzymuje turę otwartą i może dalej mówić. * Krawędzie workflow nie mogą prowadzić do procedury strukturalnej ani z niej wychodzić. Użyj kroku Sub-procedure, aby łączyć procedury strukturalne; rozpoczęciem i ukończeniem zarządza platforma. * Uruchomienie procedury zwiększa opóźnienie: agent wykonuje wywołanie narzędzia, aby do niej wejść, a następnie przechodzi przez wygenerowany workflow. ### Obsługa dostawców modeli Procedury strukturalne wymuszają wewnętrzne wywołania narzędzi przy wejściu do podprocedury i ukończeniu procedury. Główne rodziny modeli OpenAI, Anthropic, Gemini i Grok obsługują wymuszony wybór narzędzia. Inne modele lub niestandardowi dostawcy mogą tego nie gwarantować, przez co przejścia do podprocedur lub ukończenie procedury mogą być mniej niezawodne. Przy korzystaniu z innego dostawcy modelu sprawdź obsługę wymuszonego wyboru narzędzia. Zobacz [Procedury](/docs/pl/eleven-agents/customization/procedures#limitations), aby poznać ograniczenia dotyczące wszystkich procedur, w tym limit rozmiaru treści i różnice między procedurami strukturalnymi a swobodnymi.