> This is a page from the ElevenLabs documentation. For an index of the documentation, fetch https://elevenlabs.io/docs/llms.txt.

# Workflows als Code

## Überblick

Ein [Workflow](/docs/de/eleven-agents/customization/agent-workflows) wird als Graph aus Nodes und Edges gespeichert. Wenn Sie diesen Graphen manuell schreiben, müssen Sie Edge-IDs, `edge_order`-Listen und Bedingungsobjekte selbst konsistent halten. Mit dem `Workflow`-Builder in den Python- und JavaScript-SDKs können Sie denselben Graphen durch verkettete Methodenaufrufe beschreiben. Anschließend erzeugt er den Wert für `workflow`, den `agents.create()` und `agents.update()` bereits akzeptieren.

Verwenden Sie ihn, um:

* einen Workflow im Code zu erstellen und ihn wie jede andere Codeänderung zu prüfen.
* den Workflow eines Agenten zu laden, einen Node zu ändern und ihn zurückzuübertragen, ohne den Rest des Graphen zu beeinträchtigen.
* Workflows als JSON in der Versionskontrolle zu speichern und sie in CI zu validieren.

> **Note**
>
> Der Builder wird vollständig im SDK ausgeführt. Er ruft keine neuen API-Endpunkte auf, und alles, was er erstellt,
> kann im visuellen Editor des Dashboards geöffnet und bearbeitet werden.

## Anforderungen

* Python: das Paket `elevenlabs`. Der Builder wird aus `elevenlabs.agent_workflows` importiert.
* JavaScript: das Paket `@elevenlabs/elevenlabs-js`. Der Builder wird aus dem Paketstamm exportiert.

## Workflow erstellen

Das `Workflow`-Objekt steht für den Startknoten. Jedes Verb fügt einen Knoten hinzu und gibt ihn zurück. So können Sie den nächsten Schritt daran anhängen:

| Python                                 | JavaScript                            | Fügt hinzu                                                                                                                                                          |
| -------------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `converse(id, prompt, **options)`      | `converse(id, prompt, options?)`      | Einen Subagent-Knoten. Der Agent führt ein Gespräch mit `prompt`, das seinen Anweisungen hinzugefügt wird.                                                          |
| `tool(id, tool_ids, **options)`        | `tool(id, toolIds, options?)`         | Einen Dispatch-Tool-Knoten, der die angegebenen Tools ausführt. Definieren Sie sie mit [Tools als Code](/docs/de/eleven-agents/customization/agents-as-code/tools). |
| `transfer(id, destination, **options)` | `transfer(id, destination, options?)` | Eine Weiterleitung an eine Telefonnummer, eine SIP-URI oder einen anderen Agenten.                                                                                  |
| `end(id="end")`                        | `end(options?)`                       | Einen Endknoten. Jedes `end()` ohne ID verwendet denselben Knoten `"end"`.                                                                                          |

Die Routing-Methoden bestimmen, welche Kante zum nächsten Knoten führt:

| Python                                | JavaScript                       | Erstellt                                                                                                                                                                                       |
| ------------------------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `when(condition)`                     | `when(condition)`                | Eine bedingte Kante. Ein String ist eine LLM-Bedingung; ein `Expr` ist ein Ausdruck.                                                                                                           |
| `on_success()` / `on_failure()`       | `onSuccess()` / `onFailure()`    | Eine Kante von einem Tool-Knoten, die verwendet wird, wenn der Tool-Aufruf erfolgreich ist oder fehlschlägt.                                                                                   |
| `on_result(success=..., failure=...)` | `onResult({ success, failure })` | Beide Tool-Ergebniskanten gleichzeitig.                                                                                                                                                        |
| `go_to(node)`                         | `goTo(node)`                     | Eine Kante zu einem bereits vorhandenen Knoten, für Zusammenführungen und Schleifen.                                                                                                           |
| `up()`                                | `up()`                           | Keine Kante. Gibt den Knoten zurück, von dem der aktuelle verkettet wurde, um die Verkettung von dort fortzusetzen. Siehe [Workflow als eine Kette schreiben](#write-a-workflow-as-one-chain). |

Direkt im Workflow aufgerufene Verben verzweigen mit einer bedingungslosen Kante vom Startknoten. Dieses Beispiel leitet Anrufer zu einer Bestellabfrage, wiederholt die Identifizierung, wenn die Abfrage fehlschlägt, und leitet VIP- oder frustrierte Anrufer weiter:

```python
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())

```

```typescript
import { Destination, ElevenLabsClient, Expr, Workflow } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient();

const wf = new Workflow();

const triage = wf.converse("triage", "Greet the caller and find out why they're calling");
const identify = triage
  .when("Caller wants to check an order")
  .converse("identify", "Ask for the order number and the email on the account");

const lookup = identify
  .when("Caller gave an order number")
  .tool("lookup_order", ["tool_get_order"]);
lookup.onResult({
  success: (ok) =>
    ok.converse("resolve", "Explain the order status").when("Caller is satisfied").end(),
  failure: (failed) => failed.goTo(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"));

await elevenlabs.conversationalAi.agents.update("agent_id", { workflow: wf.build() });
```

`build()` validiert den gesamten Graphen und gibt das Request-Modell zurück. Es:

* Gibt dem Startknoten die von der API erforderliche ID `start_node`.
* Generiert Kanten-IDs im Format `source__target`.
* Füllt für jeden Knoten `edge_order` in der Reihenfolge aus, in der Sie die Kanten hinzugefügt haben.
* Positioniert jeden Knoten ohne Position, sodass der Graph im visuellen Editor von links nach rechts angeordnet ist.

### Workflow als eine Kette schreiben

`up()` gibt den Knoten zurück, von dem der aktuelle verkettet wurde. So können Sie einen ganzen Workflow in einem Ausdruck beschreiben, statt jeden Knoten in einer Variablen zu speichern. Verwenden Sie innerhalb einer einzelnen Kette `go_to()` / `goTo()` mit einer Knoten-ID, da keine Variable übergeben werden kann:

```python

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())

```

```typescript
const wf = new Workflow();
wf.converse("triage", "Find out why the customer is calling")
  .when("Caller gave an order number")
  .tool("lookup_order", ["tool_get_order"])
  .onResult({
    success: (ok) =>
      ok.converse("resolve", "Explain the order status").when("Customer is satisfied").end(),
    failure: (failed) => failed.goTo("triage"),
  })
  .up()
  .when(Expr.variable("tier").eq("gold"))
  .transfer("vip", Destination.agent("agent_vip_desk"));

await elevenlabs.conversationalAi.agents.update("agent_id", { workflow: wf.build() });
```

Für ein Knoten-Handle von `wf.node(id)` gibt `up()` den Knoten zurück, von dem die erste eingehende Kante stammt. Für den Startknoten gibt es den Startknoten zurück.

### Knotenoptionen

Optionale Einstellungen werden in Python als Keyword-Argumente und in JavaScript als abschließendes Optionsobjekt angegeben. Ihre Namen entsprechen den Feldern des Knotens in der API:

| Knoten     | Python                                                                                         | JavaScript                                                                              |
| ---------- | ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `converse` | `label`, `tool_ids`, `knowledge_base`, `conversation_config`, `entry_behavior`                 | `label`, `toolIds`, `knowledgeBase`, `conversationConfig`, `entryBehavior`              |
| `tool`     | `schema_overrides`                                                                             | `schemaOverrides`                                                                       |
| `transfer` | `transfer_type`, `custom_sip_headers`, `post_dial_digits`, `delay_ms`, `transfer_message`, ... | `transferType`, `customSipHeaders`, `postDialDigits`, `delayMs`, `transferMessage`, ... |
| `end`      | `id`                                                                                           | `id`                                                                                    |

Jedes Verb akzeptiert außerdem `position`, wenn Sie den Knoten selbst platzieren möchten. `Workflow(prevent_subagent_loops=True)` in Python oder `new Workflow({ preventSubagentLoops: true })` in JavaScript verhindert, dass das Gespräch erneut einen bereits besuchten Subagenten betritt.

```python
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")
```

```typescript
const triage = wf.converse("triage", "Greet the caller and find out why they're calling", {
  label: "Triage",
  toolIds: ["tool_crm_search"],
  entryBehavior: "generate_immediately",
});

triage.when("Caller is a VIP").transfer("vip_desk", Destination.agent("agent_vip_concierge"), {
  transferMessage: "Connecting you to our VIP team",
  delayMs: 500,
});

identify.when("Caller refuses to share details").end({ id: "abandoned" });
```

### Weiterleitungsziele

| Python                             | JavaScript                        | Leitet weiter an                                              |
| ---------------------------------- | --------------------------------- | ------------------------------------------------------------- |
| `Destination.phone(number)`        | `Destination.phone(number)`       | Eine Telefonnummer                                            |
| `Destination.phone_variable(name)` | `Destination.phoneVariable(name)` | Eine in einer dynamischen Variable gespeicherte Telefonnummer |
| `Destination.sip(uri)`             | `Destination.sip(uri)`            | Eine SIP-URI                                                  |
| `Destination.sip_variable(name)`   | `Destination.sipVariable(name)`   | Eine in einer dynamischen Variable gespeicherte SIP-URI       |
| `Destination.agent(agent_id)`      | `Destination.agent(agentId)`      | Einen anderen Agenten                                         |

## Bedingungen

`when()` akzeptiert einen einfachen String, ein `Condition` oder ein `Expr`:

* Ein String ist eine LLM-Bedingung: Das LLM entscheidet, ob sie zutrifft.
* `Condition.llm(text, label=...)` ist dasselbe, mit einem Label, das im visuellen Editor auf der Kante angezeigt wird. Verwenden Sie `Condition.expr(expr, label=...)`, um einen Ausdruck zu beschriften.
* Ein `Expr` wird anhand von [dynamischen Variablen](/docs/de/eleven-agents/customization/personalization/dynamic-variables) ausgewertet, ohne das LLM aufzurufen.

Erstellen Sie Ausdrücke mit `Expr.variable(name)` und `Expr.literal(value)`. Vergleichen Sie sie mit `eq`, `neq`, `gt`, `gte`, `lt` und `lte`, und führen Sie mit `add`, `sub`, `mul` und `div` Rechenoperationen aus. Kombinieren Sie sie mit `all_of` / `allOf`, `any_of` / `anyOf` und `if_else` / `ifElse`. Einfache Werte werden automatisch in `Expr.literal()` eingeschlossen. `Expr.llm(description)` fordert das LLM auf, einen Wert aus dem Gespräch zu extrahieren. Übergeben Sie `type` und `enum`, um statt eines booleschen Werts einen String, eine Zahl oder einen Wert aus einer festen Menge zu erhalten.

```python
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")
```

```typescript
import { Condition, Expr } from "@elevenlabs/elevenlabs-js";

const isVip = Expr.anyOf(
  Expr.variable("tier").eq("gold"),
  Expr.allOf(Expr.variable("orders").gte(10), Expr.variable("churn_risk").eq(true))
);

triage
  .when(Condition.expr(isVip, { label: "VIP" }))
  .transfer("vip_desk", Destination.agent("agent_vip"));

const bigRefund = Expr.variable("unit_price").mul(Expr.variable("quantity")).gt(500);
resolve.when(bigRefund).transfer("finance", Destination.phone("+15551234567"));

const 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");
```

## Schleifen und rückwärts gerichtete Kanten

Die API erlaubt eine Kante zwischen zwei beliebigen Knoten, in beide Richtungen. Damit das Gespräch auf demselben Weg zurückkehren kann, geben Sie der Kante mit `back` eine Rückwärtsbedingung:

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

```typescript
const faq = triage
  .when("Caller has a general question", { back: "Question answered" })
  .converse("faq", "Answer using the FAQ knowledge base");
```

`go_to()` / `goTo()` übernimmt den häufigen Fall für Sie. Wenn der Zielknoten bereits eine hierher führende Kante hat, wird die neue Kante zur Rückwärtsbedingung dieser Kante. Im ersten Beispiel wird `failed.go_to(identify)` als Rückwärtsbedingung der Kante `identify` → `lookup_order` gesendet. Jede andere zweite Kante zwischen denselben zwei Knoten sowie jede Kante eines Knotens zu sich selbst schlägt bei der Validierung fehl.

## Vorhandenen Agenten bearbeiten

`Workflow.from_agent()` / `Workflow.fromAgent()` lädt den Workflow eines von `agents.get()` zurückgegebenen Agenten. Knoten-IDs, Kanten-IDs, Editor-Positionen und Kantenreihenfolge bleiben erhalten. Beim Zurückschreiben ändern sich daher nur Ihre Änderungen.

| Python                                  | JavaScript                             | Funktioniert wie folgt                                                                           |
| --------------------------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `wf.node(id)`                           | `wf.node(id)`                          | Gibt ein Handle für einen vorhandenen Knoten zurück, um ihn zu bearbeiten oder daran anzuhängen. |
| `node.update(**fields)`                 | `node.update(fields)`                  | Ändert Prompt, Tools, Ziel oder Optionen eines Knotens.                                          |
| `wf.insert_between(source, target, fn)` | `wf.insertBetween(source, target, fn)` | Fügt neue Knoten in eine vorhandene Kante ein und behält deren Bedingung bei.                    |
| `wf.remove(id)`                         | `wf.remove(id)`                        | Entfernt einen Knoten und jede ein- oder ausgehende Kante.                                       |

`insert_between()` / `insertBetween()` übergibt Ihrer Funktion einen Branch, der die Bedingung der ersetzten Kante trägt. Die Funktion gibt den zuletzt hinzugefügten Knoten zurück, der dann mit dem ursprünglichen Ziel verbunden wird. Die Methode gibt diesen Knoten zurück oder `None` / `undefined`, wenn zwischen den beiden Knoten keine Kante besteht.

```python

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())
```

```typescript
const agent = await elevenlabs.conversationalAi.agents.get("agent_id");
const wf = Workflow.fromAgent(agent);

wf.node("resolve").update({ prompt: "Explain the status, then offer a discount code" });

const verify = wf.insertBetween("identify", "lookup_order", (start) =>
  start.converse("verify", "Verify the caller's identity with a one-time code")
);

verify?.when("Caller can't verify").end({ id: "unverified" });

wf.remove("vip");

await elevenlabs.conversationalAi.agents.update("agent_id", { workflow: wf.build() });
```

## Workflows in der Versionsverwaltung speichern

`to_json_string()` / `toJSONString()` schreibt den Workflow im Wire-Format der API: snake_case-Schlüssel, auf jeder Ebene sortiert, mit Einrückung von 2 Leerzeichen. Es hat dieselbe Struktur wie die REST API und die [CLI](/docs/de/eleven-agents/operate/cli), und beide SDKs schreiben für denselben Workflow Byte für Byte identische Dateien. Dadurch bleiben Diffs klein. `Workflow.from_json()` / `Workflow.fromJSON()` liest es wieder ein und akzeptiert auch eine vollständige Agentenkonfiguration mit einem `workflow`-Schlüssel, etwa eine Datei im Verzeichnis `agent_configs/` der CLI.

```python
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())
```

```typescript
import { Workflow } from "@elevenlabs/elevenlabs-js";
import { readFile, writeFile } from "node:fs/promises";

await writeFile("workflows/support.json", wf.toJSONString());

const stored = Workflow.fromJSON(await readFile("workflows/support.json", "utf8"));
const fromCli = Workflow.fromJSON(await readFile("agent_configs/support.json", "utf8"));
```

Eine typische Einrichtung:

#### Datei erstellen

Laden Sie den Agenten mit `from_agent()` / `fromAgent()` und schreiben Sie ihn in eine Datei, oder rufen Sie ihn mit `elevenlabs
    agents pull` ab.

#### Bearbeiten

Ändern Sie das JSON direkt oder laden Sie es mit `from_json()` / `fromJSON()` und bearbeiten Sie es mit dem
Builder in einem Skript.

#### In CI validieren

Führen Sie bei jedem Pull
Request `Workflow.from_json(file).build()` / `Workflow.fromJSON(file).build()` aus und posten Sie `elevenlabs agents workflow diagram <file> --format mermaid-md` als Kommentar, damit
Reviewer den Graphen sehen können.

#### Bei Merge bereitstellen

Übertragen Sie den erstellten Workflow mit `agents.update()`.

## Workflow visualisieren

Die [CLI](/docs/de/eleven-agents/operate/cli) zeichnet eine Workflow-Datei als Flussdiagramm. So können Sie prüfen, was Ihr Code erstellt hat, ohne das Dashboard zu öffnen. Sie akzeptiert eine reine Workflow-Datei, die mit `to_json_string()` / `toJSONString()` geschrieben wurde, oder eine Agentenkonfiguration mit einem `workflow`-Schlüssel:

```bash
elevenlabs agents workflow diagram workflows/support.json
```

Standardmäßig zeichnet sie Kästen und Pfeile im Terminal. Jede Kantenbedingung wird auf ihrer Kante nummeriert und darunter in einer Legende ausgeschrieben. Verwenden Sie stattdessen `--format mermaid`, um [Mermaid](https://mermaid.js.org/)-Quelltext auszugeben, oder `--format mermaid-md`, um ihn in einen abgegrenzten Codeblock zu setzen, den GitHub rendert, etwa in einem Pull-Request-Kommentar:

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

Der Befehl liest nur lokale Dateien. Daher benötigt er keinen API-Schlüssel und kann in CI ausgeführt werden.

## Validierung

Verkettete Aufrufe schlagen nie selbstständig fehl. `build()`, `to_json()` / `toJSON()` und `to_json_string()` / `toJSONString()` prüfen den gesamten Graphen und lösen einen einzelnen `WorkflowValidationError` aus. Dessen `issues` enthalten jedes Problem, jeweils mit einem `code`, einer `message` und der zugehörigen `node_id` / `nodeId`.

```python
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)
```

```typescript
import { WorkflowValidationError } from "@elevenlabs/elevenlabs-js";

try {
  const workflow = wf.build({ onWarning: (issue) => console.warn(issue.message) });
} catch (err) {
  if (err instanceof WorkflowValidationError) {
    for (const issue of err.issues) console.error(issue.code, issue.message);
  } else {
    throw err;
  }
}
```

Fehler umfassen:

* Zwei Kanten zwischen demselben Knotenpaar oder eine Kante von einem Knoten zu sich selbst.
* Eine Kante in den Startknoten oder aus einem Endknoten.
* Eine Kante von einem Tool-Knoten, die keine Erfolgs- oder Fehlerkante ist, oder eine Erfolgs- oder Fehlerkante von einem anderen Knotentyp.
* Zwei Knoten mit derselben ID oder eine Kante zu einem nicht vorhandenen Knoten.

Knoten, die vom Startknoten aus nicht erreichbar sind, werden über `on_warning` / `onWarning` als Warnungen gemeldet und halten den Build nicht auf.

## Knotentypen, die neuer sind als Ihr SDK

Ein aus der API oder einer Datei geladener Workflow kann Knotentypen enthalten, die Ihre SDK-Version noch nicht kennt. Sie durchlaufen `from_json()` / `fromJSON()` und `to_json_string()` / `toJSONString()` unverändert, und `build()` meldet jeden davon als Warnung. Das typisierte Request-Modell kann sie nicht verarbeiten. Aktualisieren Sie daher das SDK oder senden Sie das Wire-Format direkt:

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

```typescript
await elevenlabs.conversationalAi.agents.update(
  "agent_id",
  {},
  { additionalBodyParameters: { workflow: wf.toJSON() } }
);
```