Przejdź do nawigacji

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ę z elevenlabs.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:

PythonJavaScriptDodaje
converse(id, prompt, **options)converse(id, prompt, options?)Węzeł subagenta. Agent prowadzi rozmowę z prompt dodanym do jego instrukcji.
tool(id, tool_ids, **options)tool(id, toolIds, options?)Węzeł narzędzia dyspozytorskiego, który uruchamia podane narzędzia. Zdefiniuj je za pomocą narzędzi jako kodu.
transfer(id, destination, **options)transfer(id, destination, options?)Transfer na numer telefonu, URI SIP lub do innego agenta.
end(id="end")end(options?)Węzeł końcowy. Każde end() bez ID używa jednego wspólnego węzła "end".

Metody routingu określają, która krawędź prowadzi do następnego węzła:

PythonJavaScriptTworzy
when(condition)when(condition)Krawędź warunkową. Ciąg znaków to warunek LLM, a Expr to wyrażenie.
on_success() / on_failure()onSuccess() / onFailure()Krawędź z węzła narzędzia, wybieraną po powodzeniu lub niepowodzeniu wywołania narzędzia.
on_result(success=..., failure=...)onResult({ success, failure })Obie krawędzie wyniku narzędzia naraz.
go_to(node)goTo(node)Krawędź do istniejącego węzła, do łączenia ścieżek i pętli.
up()up()Bez krawędzi. Zwraca węzeł, z którego połączono bieżący, aby kontynuować łączenie z niego. Zobacz Zapisz workflow jako jeden łańcuch.

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:

from elevenlabs import ElevenLabs
from elevenlabs.agent_workflows import Destination, Expr, Workflow
elevenlabs = ElevenLabs()
wf = Workflow()
triage = wf.converse("triage", "Greet the caller and find out why they're calling")
identify = triage.when("Caller wants to check an order").converse(
"identify", "Ask for the order number and the email on the account"
)
lookup = identify.when("Caller gave an order number").tool("lookup_order", ["tool_get_order"])
lookup.on_result(
success=lambda ok: ok.converse("resolve", "Explain the order status")
.when("Caller is satisfied")
.end(),
failure=lambda failed: failed.go_to(identify),
)
triage.when(Expr.variable("tier").eq("gold")).transfer("vip", Destination.agent("agent_vip"))
triage.when("Caller wants a human").transfer("human", Destination.phone("+15551234567"))
elevenlabs.conversational_ai.agents.update("agent_id", workflow=wf.build())

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_order każ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:

wf = Workflow()
(
wf.converse("triage", "Find out why the customer is calling")
.when("Caller gave an order number")
.tool("lookup_order", ["tool_get_order"])
.on_result(
success=lambda ok: ok.converse("resolve", "Explain the order status").when("Customer is satisfied").end(),
failure=lambda failed: failed.go_to("triage"),
)
.up()
.when(Expr.variable("tier").eq("gold"))
.transfer("vip", Destination.agent("agent_vip_desk"))
)
elevenlabs.conversational_ai.agents.update("agent_id", workflow=wf.build())

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:

WęzełPythonJavaScript
converselabel, tool_ids, knowledge_base, conversation_config, entry_behaviorlabel, toolIds, knowledgeBase, conversationConfig, entryBehavior
toolschema_overridesschemaOverrides
transfertransfer_type, custom_sip_headers, post_dial_digits, delay_ms, transfer_message, …transferType, customSipHeaders, postDialDigits, delayMs, transferMessage, …
endidid

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.

triage = wf.converse(
"triage",
"Greet the caller and find out why they're calling",
label="Triage",
tool_ids=["tool_crm_search"],
entry_behavior="generate_immediately",
)
triage.when("Caller is a VIP").transfer(
"vip_desk",
Destination.agent("agent_vip_concierge"),
transfer_message="Connecting you to our VIP team",
delay_ms=500,
)
identify.when("Caller refuses to share details").end(id="abandoned")

Cele transferu

PythonJavaScriptTransfer do
Destination.phone(number)Destination.phone(number)Numer telefonu
Destination.phone_variable(name)Destination.phoneVariable(name)Numer telefonu w zmiennej dynamicznej
Destination.sip(uri)Destination.sip(uri)URI SIP
Destination.sip_variable(name)Destination.sipVariable(name)URI SIP w zmiennej dynamicznej
Destination.agent(agent_id)Destination.agent(agentId)Inny agent

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żyj Condition.expr(expr, label=...), aby oznaczyć wyrażenie etykietą.
  • Expr jest 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.

from elevenlabs.agent_workflows import Condition, Expr
is_vip = Expr.any_of(
Expr.variable("tier").eq("gold"),
Expr.all_of(Expr.variable("orders").gte(10), Expr.variable("churn_risk").eq(True)),
)
triage.when(Condition.expr(is_vip, label="VIP")).transfer("vip_desk", Destination.agent("agent_vip"))
big_refund = Expr.variable("unit_price").mul(Expr.variable("quantity")).gt(500)
resolve.when(big_refund).transfer("finance", Destination.phone("+15551234567"))
score = Expr.llm("How satisfied the caller sounds, from 1 to 5", type="integer")
resolve.when(score.lte(2)).converse("recovery", "Apologize and offer a discount code")

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:

faq = triage.when("Caller has a general question", back="Question answered").converse(
"faq", "Answer using the FAQ knowledge base"
)

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.

PythonJavaScriptDziałanie
wf.node(id)wf.node(id)Zwraca uchwyt istniejącego węzła, aby go edytować lub z niego łączyć.
node.update(**fields)node.update(fields)Zmienia prompt węzła, narzędzia, cel lub opcje.
wf.insert_between(source, target, fn)wf.insertBetween(source, target, fn)Wstawia nowe węzły w istniejącą krawędź, zachowując jej warunek.
wf.remove(id)wf.remove(id)Usuwa węzeł i wszystkie krawędzie do niego lub z niego.

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.

agent = elevenlabs.conversational_ai.agents.get("agent_id")
wf = Workflow.from_agent(agent)
wf.node("resolve").update(prompt="Explain the status, then offer a discount code")
verify = wf.insert_between(
"identify",
"lookup_order",
lambda start: start.converse("verify", "Verify the caller's identity with a one-time code"),
)
if verify is not None:
verify.when("Caller can't verify").end(id="unverified")
wf.remove("vip")
elevenlabs.conversational_ai.agents.update("agent_id", workflow=wf.build())

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.

from pathlib import Path
from elevenlabs.agent_workflows import Workflow
Path("workflows/support.json").write_text(wf.to_json_string())
stored = Workflow.from_json(Path("workflows/support.json").read_text())
from_cli = Workflow.from_json(Path("agent_configs/support.json").read_text())

Typowa konfiguracja:

1

Utwórz plik początkowy

Wczytaj agenta przez from_agent() / fromAgent() i zapisz go albo pobierz przez elevenlabs agents pull.

2

Edytuj

Zmień JSON bezpośrednio albo wczytaj go przez from_json() / fromJSON() i edytuj za pomocą buildera w skrypcie.

3

Waliduj w CI

Uruchamiaj Workflow.from_json(file).build() / Workflow.fromJSON(file).build() dla każdego pull requestu i dodawaj elevenlabs agents workflow diagram <file> --format mermaid-md jako komentarz, aby recenzenci mogli zobaczyć graf.

4

Wdróż po scaleniu

Prześlij zbudowane workflow przez agents.update().

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:

elevenlabs agents workflow diagram workflows/support.json

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:

elevenlabs agents workflow diagram workflows/support.json --format mermaid-md

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.

from elevenlabs.agent_workflows import WorkflowValidationError
try:
workflow = wf.build(on_warning=lambda issue: print("warning:", issue.message))
except WorkflowValidationError as err:
for issue in err.issues:
print(issue.code, issue.message)

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:

elevenlabs.conversational_ai.agents.update(
"agent_id",
request_options={"additional_body_parameters": {"workflow": wf.to_json()}},
)