Workflow jako kod
Twórz, edytuj i wersjonuj workflow agentów za pomocą SDK dla Pythona i JavaScriptu
Omówienie
Workflow jest przechowywany jako graf węzłów i krawędzi. Ręczne pisanie takiego grafu wymaga samodzielnego zachowania spójności identyfikatorów krawędzi, list edge_order i obiektów warunków. Konstruktor Workflow w SDK dla Pythona i JavaScriptu pozwala opisać ten sam graf za pomocą łączonych wywołań metod. Następnie tworzy wartość workflow, którą akceptują już agents.create() i agents.update().
Użyj go, aby:
- Tworzyć workflow w kodzie i przeglądać go jak każdą inną zmianę w kodzie.
- Wczytać workflow agenta, zmienić jeden węzeł i przesłać go z powrotem bez naruszania reszty grafu.
- Przechowywać workflow jako JSON w kontroli wersji i sprawdzać je w CI.
Konstruktor działa całkowicie w SDK. Nie wywołuje żadnych nowych endpointów API, a wszystko, co utworzy, można otworzyć i edytować w wizualnym edytorze panelu.
Wymagania
- Python: pakiet
elevenlabs. Konstruktor importuje się zelevenlabs.agent_workflows. - JavaScript: pakiet
@elevenlabs/elevenlabs-js. Konstruktor jest eksportowany z katalogu głównego pakietu.
Zbuduj workflow
Obiekt Workflow reprezentuje węzeł startowy. Każdy czasownik dodaje węzeł i go zwraca, więc możesz z niego połączyć kolejny krok:
Metody routingu określają, która krawędź prowadzi do następnego węzła:
Czasowniki wywołane bezpośrednio na workflow tworzą odgałęzienie od węzła startowego z bezwarunkową krawędzią. Ten przykład kieruje dzwoniących do wyszukiwania zamówienia, ponawia identyfikację, jeśli wyszukiwanie się nie powiedzie, i przekierowuje klientów VIP lub zdenerwowanych dzwoniących:
build() sprawdza cały graf i zwraca model żądania. Dodatkowo:
- Nadaje węzłowi startowemu ID
start_node, wymagane przez API. - Generuje ID krawędzi w formacie
source__target. - Uzupełnia
edge_orderkażdego węzła w kolejności dodawania krawędzi. - Nadaje pozycję każdemu węzłowi bez pozycji, aby graf był ułożony od lewej do prawej w edytorze wizualnym.
Zapisz workflow jako jeden łańcuch
up() zwraca węzeł, z którego połączono bieżący, więc możesz opisać całe workflow jednym wyrażeniem zamiast trzymać każdy węzeł w zmiennej. W pojedynczym łańcuchu użyj go_to() / goTo() z ID węzła, bo nie ma zmiennej do przekazania:
Dla uchwytu węzła z wf.node(id) metoda up() zwraca węzeł, z którego prowadzi pierwsza krawędź do niego. Dla węzła startowego zwraca węzeł startowy.
Opcje węzłów
Opcjonalne ustawienia przekazujesz jako argumenty nazwane w Pythonie, a w JavaScript jako końcowy obiekt opcji. Ich nazwy odpowiadają polom węzła w API:
Każdy czasownik przyjmuje też position, jeśli chcesz samodzielnie ustawić pozycję węzła. Workflow(prevent_subagent_loops=True) w Pythonie lub new Workflow({ preventSubagentLoops: true }) w JavaScript zapobiega ponownemu wejściu rozmowy do odwiedzonego już subagenta.
Cele transferu
Warunki
when() przyjmuje zwykły ciąg znaków, Condition lub Expr:
- Ciąg znaków to warunek LLM: LLM decyduje, czy jest spełniony.
Condition.llm(text, label=...)działa tak samo, ale z etykietą wyświetlaną na krawędzi w edytorze wizualnym. UżyjCondition.expr(expr, label=...), aby oznaczyć wyrażenie etykietą.Exprjest oceniane na podstawie zmiennych dynamicznych, bez wywoływania LLM.
Buduj wyrażenia z Expr.variable(name) i Expr.literal(value). Porównuj je za pomocą eq, neq, gt, gte, lt i lte, a działania arytmetyczne wykonuj przez add, sub, mul i div. Łącz je przez all_of / allOf, any_of / anyOf oraz if_else / ifElse. Zwykłe wartości są automatycznie opakowywane w Expr.literal(). Expr.llm(description) prosi LLM o wyodrębnienie wartości z rozmowy; przekaż type i enum, aby otrzymać ciąg znaków, liczbę lub jedną wartość z ustalonego zbioru zamiast wartości logicznej.
Pętle i krawędzie wsteczne
API pozwala na jedną krawędź między dowolnymi dwoma węzłami, w obu kierunkach. Aby rozmowa mogła wrócić tą samą drogą, nadaj krawędzi warunek wsteczny za pomocą back:
go_to() / goTo() obsługuje ten typowy przypadek za ciebie. Gdy węzeł docelowy ma już krawędź prowadzącą tutaj, nowa krawędź staje się warunkiem wstecznym tej krawędzi. W pierwszym przykładzie failed.go_to(identify) jest wysyłane jako warunek wsteczny krawędzi identify → lookup_order. Każda inna druga krawędź między tymi samymi dwoma węzłami oraz każda krawędź z węzła do niego samego nie przejdzie walidacji.
Edytuj istniejącego agenta
Workflow.from_agent() / Workflow.fromAgent() wczytuje workflow agenta zwróconego przez agents.get(). ID węzłów, ID krawędzi, pozycje w edytorze i kolejność krawędzi zostają zachowane, więc przesłanie go z powrotem zmieni tylko to, co zmienisz.
insert_between() / insertBetween() przekazuje twojej funkcji odgałęzienie z warunkiem zastępowanej krawędzi. Funkcja zwraca ostatni dodany węzeł, który zostaje potem połączony z pierwotnym celem. Metoda zwraca ten węzeł albo None / undefined, jeśli między tymi dwoma węzłami nie ma krawędzi.
Przechowuj workflow w kontroli wersji
to_json_string() / toJSONString() zapisuje workflow w formacie przesyłanym przez API: klucze snake_case, sortowane na każdym poziomie, z wcięciami po 2 spacje. To ten sam format, którego używają REST API i CLI, a oba SDK zapisują bajt w bajt identyczne pliki dla tego samego workflow, więc różnice pozostają małe. Workflow.from_json() / Workflow.fromJSON() wczytuje go z powrotem, a także przyjmuje pełną konfigurację agenta z kluczem workflow, na przykład plik z katalogu agent_configs/ CLI.
Typowa konfiguracja:
Utwórz plik początkowy
Wczytaj agenta przez from_agent() / fromAgent() i zapisz go albo pobierz przez elevenlabs agents pull.
Edytuj
Zmień JSON bezpośrednio albo wczytaj go przez from_json() / fromJSON() i edytuj za pomocą
buildera w skrypcie.
Wizualizuj workflow
CLI rysuje plik workflow jako schemat blokowy, więc możesz sprawdzić, co zbudował kod, bez otwierania panelu. Przyjmuje zwykły plik workflow zapisany przez to_json_string() / toJSONString() lub konfigurację agenta z kluczem workflow:
Domyślnie rysuje w terminalu pola i strzałki, z każdym warunkiem krawędzi oznaczonym numerem na krawędzi i opisanym w legendzie poniżej. Użyj --format mermaid, aby zamiast tego wypisać kod źródłowy Mermaid, albo --format mermaid-md, aby opakować go w blok kodu, który GitHub renderuje, na przykład w komentarzu do pull requestu:
Polecenie odczytuje tylko pliki lokalne, więc nie potrzebuje klucza API i może działać w CI.
Walidacja
Połączone wywołania same w sobie nigdy nie kończą się błędem. build(), to_json() / toJSON() oraz to_json_string() / toJSONString() sprawdzają cały graf i zgłaszają pojedynczy WorkflowValidationError, którego lista issues zawiera każdy problem, wraz z code, message oraz dotyczącym go node_id / nodeId.
Błędy obejmują:
- Dwie krawędzie między tą samą parą węzłów lub krawędź z węzła do niego samego.
- Krawędź do węzła startowego lub z węzła końcowego.
- Krawędź z węzła narzędzia, która nie jest krawędzią powodzenia ani niepowodzenia, lub krawędź powodzenia albo niepowodzenia z innego rodzaju węzła.
- Dwa węzły z tym samym ID lub krawędź do nieistniejącego węzła.
Węzły nieosiągalne z węzła startowego są zgłaszane jako ostrzeżenia przez on_warning / onWarning i nie zatrzymują budowania.
Typy węzłów nowsze niż twoje SDK
Workflow wczytane z API lub pliku może zawierać typy węzłów, których twoja wersja SDK jeszcze nie zna. Przechodzą one bez zmian przez from_json() / fromJSON() oraz to_json_string() / toJSONString(), a build() zgłasza każdy z nich jako ostrzeżenie. Typowany model żądania nie może ich przenosić, więc zaktualizuj SDK lub wyślij format przesyłany bezpośrednio: