Procedury strukturalne

Przegląd

Procedura strukturalna to procedura, która wykonuje stałą sekwencję kroków. Procedura swobodna to wskazówki w języku naturalnym, które agent interpretuje i dostosowuje do sytuacji. Procedura strukturalna to uporządkowana lista kroków określonego typu, które agent wykonuje w kolejności za każdym razem, gdy procedura ma zastosowanie.

Użyj procedury strukturalnej, gdy konkretne kroki muszą przebiegać tak samo w 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, procedura strukturalna ma wyzwalacz opisujący, kiedy ma zastosowanie. Gdy rozmowa pasuje do wyzwalacza, agent wykonuje kroki procedury w kolejności, a następnie wraca do reszty rozmowy.

Kiedy używać procedury strukturalnej

Użyj procedury strukturalnej, gdy konkretne kroki muszą zawsze przebiegać tak samo, ale nadal chcesz szybko tworzyć je jako proste kroki. Porównanie z procedurami swobodnymi, workflow i promptem systemowym znajdziesz w sekcji Kiedy używać procedur.

Elementy procedury strukturalnej

Procedura strukturalna 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-a, 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 pieniędzy 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. Wyzwalacz działa tak samo jak w każdej procedurze; zobacz Tworzenie wyzwalaczy.

Kroki

Treść procedury to uporządkowana lista kroków określonego typu. Istnieje wiele typów kroków, które łączysz, aby opisać zadanie.

Dokumentacja kroków API

content procedury strukturalnej to dokument zakodowany w JSON zawierający tablicę steps. Każdy krok jest obiektem określonym przez jego type.

Ask

Krok Ask instruuje agenta, aby 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."
}

Tell

Krok Tell instruuje agenta, aby wygenerował jedną wiadomość własnymi słowami. W przeciwieństwie do Ask nie czeka na odpowiedź użytkownika przed kontynuowaniem.

• Typ API: tell
• instruction: Wymagany, niepusty ciąg znaków.

{
  "type": "tell",
  "instruction": "Explain that the refund normally takes five to ten business days."
}

Say

Krok Say wypowiada podany tekst dokładnie tak, jak został zapisany.

• Typ API: say
• message: Wymagany, niepusty ciąg znaków.

{
  "type": "say",
  "message": "Your refund has been submitted."
}

If, else if i else

Krok If zawiera jedną lub więcej uporządkowanych gałęzi warunkowych. Uruchamiana jest pierwsza pasująca gałąź. Opcjonalna tablica fallback działa jak gałąź else.

• Typ API: branch
• branches: Wymagana, niepusta lista gałęzi warunkowych.
• fallback: Opcjonalna lista kroków else.
• 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ą oceniane w kolejności.
2. Uruchamiana jest pierwsza pasująca gałąź.
3. Jeśli żaden warunek nie pasuje, uruchamiane jest fallback.
4. Po zakończeniu gałęzi procedura wraca do głównej sekwencji.

Powyższy przykład używa warunku w języku naturalnym. Warunki mogą też korzystać z wyrażeń workflow:

{
  "type": "expression",
  "expression": {
    "type": "eq_operator",
    "left": {
      "type": "dynamic_variable",
      "name": "plan_tier"
    },
    "right": {
      "type": "string_literal",
      "value": "annual"
    }
  }
}

Wszystkie gałęzie w jednym kroku If muszą używać tego samego typu warunku: llm albo expression.

Krok If może być pierwszym krokiem procedury. Jednak:

• Kroki If nie mogą być zagnieżdżane.
• Nie można umieścić dwóch kroków If kolejno po sobie.
• Warunek wyrażenia nie może występować bezpośrednio po kroku Ask. Użyj warunku LLM, aby ocenić swobodną odpowiedź tekstową użytkownika.

Tool

Krok Tool wywołuje konkretne narzędzie.

• Typ API: tool_call
• tool_id: Wymagany, niepusty identyfikator narzędzia.
• tool_name: Wymagana nazwa narzędzia.
• instruction: Opcjonalna instrukcja opisująca sposób wywołania narzędzia.
• on_failure: Opcjonalny moduł obsługi błędów.

{
  "type": "tool_call",
  "tool_id": "tool_abc123",
  "tool_name": "lookup_order",
  "instruction": "Look up the order using the order ID provided by the user."
}

Bez on_failure nieudane wywołanie narzędzia zatrzymuje procedurę. Dodaj on_failure, aby obsłużyć konkretne błędy, ponowić działanie narzędzia lub kontynuować kroki awaryjne.

• branches: Opcjonalna lista uporządkowanych warunków. Uruchamiana jest pierwsza pasująca gałąź.
• fallback: Wymagana, niepusta lista kroków. Uruchamia się, gdy żadna gałąź nie pasuje.

{
  "type": "tool_call",
  "tool_id": "tool_abc123",
  "tool_name": "lookup_order",
  "on_failure": {
    "fallback": [
      {
        "type": "tell",
        "instruction": "Explain that the order could not be retrieved and offer to connect the user with support."
      }
    ]
  }
}

Gałęzie obsługi błędów mogą zawierać kroki Ask, Tell, Say, Sub-procedure, System tool i Retry. Nie mogą zawierać kroków Tool ani If. Wszystkie gałęzie warunkowe w jednej obsłudze błędów muszą używać tego samego typu warunku.

Retry

Krok Retry ponawia krok Tool, którego obsługa błędów go zawiera.

• Typ API: retry
• max_retries: Opcjonalna liczba całkowita od 1 do 3. Domyślnie: 1.
• Wartość określa liczbę ponowień po pierwotnym wywołaniu narzędzia.
• Retry jest prawidłowe tylko w on_failure.
• Retry musi być ostatnim krokiem w swojej gałęzi obsługi błędów, ponieważ kolejne kroki byłyby nieosiągalne.
• Jeśli wszystkie próby się nie powiodą, procedura zostanie zatrzymana.

{
  "type": "retry",
  "max_retries": 2
}

Sub-procedure

Krok Sub-procedure uruchamia inną procedurę strukturalną. Po jej zakończeniu wykonanie wraca do kroku po kroku Sub-procedure.

• Typ API: sub_procedure
• procedure_id: Wymagany, niepusty identyfikator procedury.
• Cel musi istnieć w tym samym agencie.
• Cel musi być procedurą strukturalną.
• Procedura nie może wywoływać samej siebie.

{
  "type": "sub_procedure",
  "procedure_id": "agtprc_6qbpwdq8n01bxhk44bgjy6f10ck3"
}

System tool

Krok System tool 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 kończy działanie, musi być ostatnim krokiem w sekwencji lub gałęzi, w której się znajduje.

{
  "type": "system_tool",
  "system_tool_name": "end_call"
}

Pełny przykład API

Ten przykład obsługuje anulowanie zamówienia na podstawie statusu wysyłki. Ponawia nieudane wywołanie narzędzia, uruchamia inną procedurę strukturalną, a następnie kończy rozmowę.

{
  "trigger": "When the user asks to cancel an order and request a refund.",
  "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.",
              "on_failure": {
                "fallback": [
                  {
                    "type": "retry",
                    "max_retries": 2
                  }
                ]
              }
            }
          ]
        }
      ],
      "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."
    },
    {
      "type": "system_tool",
      "system_tool_name": "end_call"
    }
  ]
}

Jak działa procedura strukturalna

Gdy prośba użytkownika podczas rozmowy pasuje do wyzwalacza procedury, agent wchodzi do procedury i wykonuje jej kroki w kolejności, zawsze tak samo. W trakcie procedury agent skupia się na tych krokach; gdy dotrze do końca, wraca do miejsca, w którym przerwał rozmowę.

Jeśli krok Tool się nie powiedzie i nie definiuje on_failure, procedura zatrzyma się bez wykonania pozostałych kroków. Gdy skonfigurowano on_failure, procedura uruchamia pierwszą pasującą gałąź błędu lub wymagany fallback. Obsłużony błąd prowadzi do następnego kroku procedury, chyba że wybrany moduł obsługi ponawia narzędzie, kończy rozmowę lub uruchamia inną ścieżkę końcową.

Zarządzanie ustrukturyzowaną procedurą

Dobre praktyki

Tworzenie kroków

Łączenie procedur

Ogólne wskazówki dotyczące łączenia procedur dotyczą też procedur ustrukturyzowanych — zobacz Łączenie procedur na stronie Procedury swobodne.

Jeden wzorzec dotyczy wyłącznie łączenia typów: procedura swobodna może odwoływać się do ustrukturyzowanej. Obsługę otwartych przypadków zachowaj w procedurze swobodnej, a części, które muszą działać za każdym razem tak samo, takie jak weryfikacja tożsamości lub eskalacja, przekaż procedurze ustrukturyzowanej.

Ograniczenia

• Kroki If nie mogą być zagnieżdżone ani umieszczone jeden po drugim.

Obsługa dostawców modeli

Ustrukturyzowane procedury wymuszają wewnętrzne wywołania narzędzi przy przechodzeniu do podprocedury i kończeniu procedury. Główne rodziny modeli OpenAI, Anthropic, Gemini i Grok obsługują wymuszony wybór narzędzia. Inne modele lub własni dostawcy mogą tego nie gwarantować, co może sprawić, że przejścia do podprocedur lub kończenie procedur będą mniej niezawodne. Korzystając 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 oraz różnice między procedurami ustrukturyzowanymi a swobodnymi.