Ustrukturyzowane procedury

Omówienie

Ustrukturyzowana procedura to procedura wykonująca stałą sekwencję kroków. Procedura swobodna 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.

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.

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.

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.

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.

{
  "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.

{
  "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": "..." }.

{
  "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.

{
  "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:

{
  "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.

{
  "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:

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

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ę.

{
  "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.

Zarządzanie ustrukturyzowaną procedurą

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.

Wybór typów kroków

Struktura procedury

Praca z narzędziami

Pisanie instrukcji

Łączenie procedur

Ogólne wskazówki dotyczące łączenia procedur odnoszą się też do procedur strukturalnych; zobacz Łączenie procedur 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, aby poznać ograniczenia dotyczące wszystkich procedur, w tym limit rozmiaru treści i różnice między procedurami strukturalnymi a swobodnymi.