> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt. # Strukturierte Verfahren ## Überblick Ein strukturiertes Verfahren ist ein [Verfahren](/docs/de/eleven-agents/customization/procedures), das eine feste Abfolge von Schritten ausführt. Ein [Freiformverfahren](/docs/de/eleven-agents/customization/procedures/free-form-procedures) besteht aus Anweisungen in natürlicher Sprache, die der Agent interpretiert und an die Situation anpasst. Ein strukturiertes Verfahren ist eine geordnete Liste typisierter Schritte, die der Agent jedes Mal der Reihe nach ausführt, wenn das Verfahren zutrifft. Verwenden Sie ein strukturiertes Verfahren, wenn bestimmte Schritte bei jedem Anruf gleich ausgeführt werden müssen: etwa zur Identitätsprüfung eines Anrufers, zur Eskalation eines Tickets oder zur Zahlungsannahme. Sie erstellen es als kurze Liste von Schritten in einfacher Sprache. Wie jedes Verfahren hat auch ein strukturiertes Verfahren einen Auslöser, der beschreibt, wann es zutrifft. Wenn ein Gespräch dem Auslöser entspricht, führt der Agent die Schritte des Verfahrens der Reihe nach aus und kehrt dann zum übrigen Gespräch zurück. ![Editor für strukturierte Verfahren](/docs/_fern-img/bc996f67b2afad8f1de5abe8febcf8af3766b4f098627b0ae60e0456b3c2703b.webp) ## Wann ein strukturiertes Verfahren verwendet werden sollte Verwenden Sie ein strukturiertes Verfahren, wenn bestimmte Schritte jedes Mal gleich ausgeführt werden müssen, Sie es aber dennoch schnell als einfache Schritte erstellen möchten. Strukturierte Verfahren sind leichter zu schreiben als ein Workflow, aber weniger ausdrucksstark. Einen Vergleich mit Freiformverfahren, Workflows und dem System Prompt finden Sie unter [Wann Verfahren verwendet werden sollten](/docs/de/eleven-agents/customization/procedures#when-to-use-procedures). ## Aufbau einer strukturierten Prozedur Eine strukturierte Prozedur besteht aus drei Teilen: einem Namen, einem Trigger und einer geordneten Liste von Schritten. ### Name Eine kurze Bezeichnung, die die Prozedur im Dashboard identifiziert. Der Name wird nie an das LLM gesendet und beeinflusst daher nicht das Verhalten des Agenten. ### Trigger Eine Beschreibung in natürlicher Sprache, wann der Agent diese Prozedur ausführen soll, zum Beispiel *Wenn der Nutzer die Rückerstattung einer Bestellung anfordert*. Der Agent vergleicht die Absicht des Nutzers mit dem Trigger jeder Prozedur und führt die passende aus. Trigger sollten daher konkret und eindeutig sein. Der Agent sieht nur den Trigger-Text, nie den Namen oder die ID der Prozedur. Ein Trigger funktioniert wie bei jeder anderen Prozedur. Siehe [Trigger formulieren](/docs/de/eleven-agents/customization/procedures/free-form-procedures#writing-triggers). Lassen Sie den Trigger leer, um die Prozedur zu einer Unterprozedur zu machen, die nur ausgeführt wird, wenn eine andere Prozedur sie aufruft. ### Schritte Der Prozedurinhalt ist eine geordnete Liste typisierter Schritte. Es gibt mehrere Schritttypen, die Sie kombinieren, um die Aufgabe zu beschreiben. | Schritt | Funktion | | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Fragen** | Fordert den Nutzer zur Eingabe von Informationen auf und wartet. Fragt weiter, bis der Nutzer antwortet. Dies ist der einzige Schritt, der auf den Nutzer wartet. | | **Mitteilen** | Lässt den Agenten etwas mit eigenen Worten vermitteln und fährt dann mit dem nächsten Schritt fort. | | **Sagen** | Lässt den Agenten eine genaue Nachricht Wort für Wort sprechen und fährt dann mit dem nächsten Schritt fort. Ein Sagen-Schritt kann für jede vom Agenten unterstützte Sprache eine separat konfigurierte Übersetzung enthalten. | | **Tool** | Ruft ein bestimmtes Tool auf. Sie können das LLM in natürlicher Sprache anweisen, wie es das Tool aufrufen soll, oder Parameterwerte explizit festlegen, wenn maximale Deterministik erforderlich ist. Sie können auch Schritte definieren, die bei einem fehlgeschlagenen Tool-Aufruf ausgeführt werden. | | **Wenn** | Wertet eine oder mehrere Bedingungen der Reihe nach aus und führt die Schritte der ersten Übereinstimmung aus. Ein optionales Else wird ausgeführt, wenn nichts übereinstimmt. | | **Unterprozedur** | Führt eine andere strukturierte Prozedur aus. Wenn ihre Schritte abgeschlossen sind, kehrt die Steuerung zum nächsten Schritt in dieser aufrufenden Prozedur zurück. | | **System-Tool** | Führt eine integrierte Systemaktion aus. Derzeit wird nur das Beenden des Anrufs unterstützt. | | **Wiederholen** | Führt den Fehler-Handler eines Tool-Schritts einschließlich des Tool-Aufrufs bis zu dreimal erneut aus. Nur im Fehler-Handler eines Tool-Schritts verfügbar. | ![Menü für Schritttypen strukturierter Prozeduren ](/docs/_fern-img/14976a6b9979d21fd7c77541a49e7475f8aa0764af4940746d3390804e7c4598.webp) Nicht jeder Schritt kann überall verwendet werden. Innerhalb eines Wenn-Zweigs können Sie jeden Schritt außer einem weiteren Wenn oder Wiederholen verwenden. Im Fehler-Handler eines Tool-Schritts können Sie jeden Schritt außer Wenn oder einem weiteren Tool verwenden. ## API-Referenz für Schritte Der `content` einer strukturierten Prozedur ist ein JSON-kodiertes Dokument mit einem `steps`-Array. Jeder Schritt ist ein Objekt, das durch seinen `type` identifiziert wird. Der Trigger ist ein separates Feld der obersten Ebene der Prozedur und nicht Teil von `content`. API- und SDK-Payloads verwenden `type: "deterministic"` für die Prozedur selbst. ### Fragen Ein Fragen-Schritt weist den Agenten an, Informationen anzufordern und zu warten, bis der Nutzer eine passende Antwort gibt. * API-Typ: `ask` * `instruction`: Erforderlicher, nicht leerer String. ```json focus={1-4} { "type": "ask", "instruction": "Ask the user for their order ID." } ``` ### Mitteilen Ein Mitteilen-Schritt weist den Agenten an, eine einzelne Nachricht mit eigenen Worten zu erzeugen. Er wartet nicht auf eine Nutzerantwort, bevor er fortfährt. * API-Typ: `tell` * `instruction`: Erforderlicher, nicht leerer String. ```json focus={1-4} { "type": "tell", "instruction": "Explain that the refund normally takes five to ten business days." } ``` ### Sagen Ein Sagen-Schritt spricht den bereitgestellten Text genau wie geschrieben und fährt dann fort. Geben Sie `message_translations` an, um dem Agenten für jede weitere unterstützte Sprache, nach Sprachcode sortiert, eine genaue Nachricht bereitzustellen. * API-Typ: `say` * `message`: Erforderlicher, nicht leerer String. * `message_translations`: Optionales Objekt, das einen Sprachcode auf `{ "value": "..." }` abbildet. ```json focus={1-7} { "type": "say", "message": "Your refund has been submitted.", "message_translations": { "es": { "value": "Su reembolso ha sido enviado." } } } ``` ### Wenn, else if und else Ein Wenn-Schritt enthält einen oder mehrere geordnete bedingte Zweige. Der erste passende Zweig wird ausgeführt. Das optionale `fallback`-Array ist der Else-Zweig. * API-Typ: `branch` * `branches`: Erforderliche, nicht leere Liste bedingter Zweige. * `fallback`: Optionale Liste von Else-Schritten. * Jeder Zweig benötigt eine `condition` und eine nicht leere `steps`-Liste. ```json focus={1-23} { "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." } ] } ``` Dies verhält sich wie if/else-if/else: 1. Bedingungen werden der Reihe nach ausgewertet. 2. Der erste passende Zweig wird ausgeführt. 3. Wenn keine Bedingung zutrifft, wird `fallback` ausgeführt. 4. Nachdem ein Zweig abgeschlossen ist, wird die Prozedur in der Hauptsequenz fortgesetzt. Das obige Beispiel verwendet eine Textbedingung, die das Modell in natürlicher Sprache auswertet. Bedingungen können auch Ausdrücke über dynamischen Variablen sein: ```json focus={1-14} { "type": "expression", "expression": { "type": "eq_operator", "left": { "type": "dynamic_variable", "name": "plan_tier" }, "right": { "type": "string_literal", "value": "annual" } } } ``` Eine Ausdrucksbedingung prüft dynamische Variablen, die durch Tool-Ergebnisse gefüllt oder beim Start der Konversation festgelegt werden. Sie kann die letzte Antwort des Nutzers nicht lesen. Verwenden Sie eine Textbedingung, um anhand der Nutzeraussage zu verzweigen. Alle Zweige eines Wenn-Schritts müssen denselben Bedingungstyp verwenden: entweder `llm` oder `expression`. ### Tool Ein Tool-Schritt ruft ein bestimmtes Tool auf. * API-Typ: `tool_call` * `tool_id`: Erforderliche, nicht leere Tool-ID. Das Tool muss mit dem Agenten verknüpft sein. * `tool_name`: Erforderlicher Tool-Name, der mit dem Tool übereinstimmt. * `instruction`: Optionale Anweisung, die beschreibt, wie das Tool aufgerufen wird. * `schema_overrides`: Optionale feste Werte für die Parameter des Tools. * `on_failure`: Optionaler Fehler-Handler. ```json focus={1-6} { "type": "tool_call", "tool_id": "tool_abc123", "tool_name": "lookup_order", "instruction": "Look up the order using the order ID provided by the user." } ``` #### Feste Parameterwerte Verwenden Sie `schema_overrides`, wenn ein Parameter immer einen bestimmten Wert haben muss. Das Modell sieht keinen überschriebenen Parameter und wählt ihn nicht aus. Schlüssel sind Parameterpfade im Schema des Tools. Jeder Wert benennt eine Quelle: | `source` | Felder | Verhalten | | ------------------ | ------------------- | ----------------------------------------------------------------- | | `constant` | `constant_value` | Sendet immer den angegebenen Wert. | | `dynamic_variable` | `dynamic_variable` | Sendet den aktuellen Wert der benannten dynamischen Variablen. | | `llm` | `prompt` (optional) | Lässt das Modell den Wert wählen, mit optionalem Prompt-Override. | | `omit` | | Lässt den Parameter im Aufruf weg. | ```json focus={1-9} { "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" } } } ``` #### Fehlerbehandlung Ohne `on_failure` beendet ein fehlgeschlagener Tool-Aufruf die Konversation. Fügen Sie stattdessen `on_failure` hinzu, um Wiederherstellungsschritte auszuführen. * `fallback`: Erforderliche, nicht leere Liste von Schritten, die ausgeführt werden, wenn das Tool fehlschlägt. * `branches`: Für bedingte Fehlerbehandlung reserviert. Lassen Sie es leer. ```json focus={1-14} { "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." } ] } } ``` Ein Fehler-Handler kann Schritte zum Fragen, Mitteilen, Sagen, für Unterprozeduren, System-Tools und Wiederholen enthalten. Er kann keine Tool- oder Wenn-Schritte enthalten. Nach der Ausführung des Handlers wird die Prozedur mit dem Schritt nach dem Tool-Schritt fortgesetzt. ### Wiederholen Ein Wiederholen-Schritt führt den Fehler-Handler, der ihn enthält, einschließlich des Tool-Aufrufs erneut aus. Jeder Versuch ruft das Tool erneut auf und führt bei einem weiteren Fehlschlag erneut alle Schritte im Handler aus. Wenn die Versuche aufgebraucht sind, endet die Konversation. * API-Typ: `retry` * `max_retries`: Optionale Ganzzahl von 1 bis 3. Standardwert ist 1. * Der Wert zählt Versuche nach dem ursprünglichen Tool-Aufruf. * Wiederholen ist nur innerhalb von `on_failure` gültig. * Wiederholen muss der letzte Schritt in seinem Fehler-Handler sein, da spätere Schritte nicht erreichbar wären. ```json focus={1-4} { "type": "retry", "max_retries": 2 } ``` ### Unterprozedur Ein Unterprozedur-Schritt führt eine andere strukturierte Prozedur aus. Wenn die Schritte dieser Prozedur abgeschlossen sind, kehrt die Ausführung zum Schritt nach dem Unterprozedur-Schritt zurück. * API-Typ: `sub_procedure` * `procedure_id`: Erforderliche, nicht leere Prozedur-ID. * Das Ziel muss auf demselben Agenten vorhanden sein. * Das Ziel muss eine strukturierte Prozedur sein. * Eine Prozedur kann sich nicht selbst aufrufen. ```json focus={1-4} { "type": "sub_procedure", "procedure_id": "agtprc_6qbpwdq8n01bxhk44bgjy6f10ck3" } ``` ### System-Tool Ein System-Tool-Schritt führt eine integrierte Systemaktion aus. * API-Typ: `system_tool` * `system_tool_name`: Erforderlicher System-Tool-Name. * Derzeit wird nur `end_call` unterstützt. Weitere System-Tools können später hinzugefügt werden. * Da `end_call` abschließend ist, muss es der letzte Schritt in der enthaltenen Sequenz, dem Zweig oder dem Fehler-Handler sein. ```json focus={1-4} { "type": "system_tool", "system_tool_name": "end_call" } ``` ## Validierungsregeln Das Veröffentlichen des Agenten oder Speichern des Agentenentwurfs lehnt eine strukturierte Prozedur ab, die gegen eine dieser Regeln verstößt. Der Fehler benennt den problematischen Schritt über seinen Pfad. * Zwei Wenn-Schritte können nicht direkt hintereinander platziert werden. * Wenn-Schritte können nicht verschachtelt werden. * Ein Wenn-Schritt mit Ausdrucksbedingungen kann nicht direkt auf einen Fragen-Schritt folgen. * Alle Bedingungen in einem Wenn-Schritt müssen denselben Typ haben: entweder `llm` oder `expression`. * Wiederholen darf nur in `on_failure` erscheinen und muss dort der letzte Schritt sein. * `end_call` muss in jeder Liste, in der es erscheint, der letzte Schritt sein. * Das `fallback` eines Fehler-Handlers muss mindestens einen Schritt enthalten. * Eine Unterprozedur muss auf eine vorhandene strukturierte Prozedur auf demselben Agenten verweisen und darf nicht auf sich selbst verweisen. * `tool_id` muss ein Tool des Agenten sein, `tool_name` muss übereinstimmen und `schema_overrides` muss dem Schema des Tools entsprechen. * Die `steps`-Liste, jede `instruction` und jede `message` dürfen nicht leer sein. Informationen zum Umstrukturieren einer Prozedur, die gegen eine dieser Regeln verstößt, finden Sie unter [Best Practices](#best-practices). ## Vollständiges API-Beispiel Dieses Beispiel verarbeitet eine Stornierung anhand des Versandstatus. Es legt einen Tool-Parameter fest, behandelt einen fehlgeschlagenen Tool-Aufruf, ruft eine andere strukturierte Prozedur auf und beendet dann den Anruf. ```json maxLines=30 { "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" } ] } ``` ## Ausführung einer strukturierten Prozedur Die Umwandlung der Schritte einer strukturierten Prozedur in die Form, die der Agent ausführt, wird als Kompilierung bezeichnet. Die Plattform kompiliert jede strukturierte Prozedur beim Veröffentlichen. Sie müssen nichts selbst kompilieren. Das kompilierte Ergebnis ist derzeit als schreibgeschützte Knoten im Tab **Workflow** sichtbar. Wenn die Anfrage des Nutzers dem Trigger einer Prozedur entspricht, tritt der Agent in die Prozedur ein und führt ihre Schritte der Reihe nach aus. Innerhalb der strukturierten Prozedur konzentriert sich der Agent auf jeden Schritt einzeln. Wenn er das Ende erreicht, kehrt er zum Rest der Konversation zurück. Die folgenden Regeln beschreiben das Laufzeitverhalten der Schritte. #### Nur Fragen wartet auf den Nutzer Jeder Schritt außer Fragen wird sofort ausgeführt und die Steuerung wechselt innerhalb desselben Turns zum nächsten Schritt. Ein Mitteilen- oder Sagen-Schritt übermittelt seine Nachricht und fährt fort. Es gibt außer Fragen keinen Schritt, der die Konversation pausiert, und keinen Schritt, der den aktuellen Turn beendet. Wenn Sie eine Nutzereingabe benötigen, verwenden Sie einen Fragen-Schritt. Wenn die Konversation enden soll, verwenden Sie das System-Tool `end_call`. #### Das Ende einer Prozedur beendet den Turn nicht Wenn der letzte Schritt abgeschlossen ist, endet die Prozedur und der Agent kehrt mit weiterhin offenem Turn zum Rest der Konversation zurück. Er kann also noch mehr sagen. Wenn eine Unterprozedur abgeschlossen ist, kehrt die Steuerung zum nächsten Schritt der Prozedur zurück, die sie aufgerufen hat. #### Tool-Schritte unterscheiden nur Erfolg und Fehler Ein Tool-Schritt kann nicht anhand eines Statuscodes oder des Antworttexts verzweigen. Bei Erfolg des Tools wird die Prozedur fortgesetzt. Wenn es fehlschlägt und der Schritt keinen Fehler-Handler hat, endet die Konversation. Wenn er einen hat, werden die Schritte des Handlers ausgeführt und die Prozedur mit dem nächsten Schritt fortgesetzt. Ein Wiederholen innerhalb des Handlers führt das Tool und bei erneutem Fehlschlag alle Schritte im Handler erneut aus, bis das Tool erfolgreich ist oder die Versuche aufgebraucht sind. Sind sie aufgebraucht, endet die Konversation. #### Wenn-Schritte werden fortgesetzt, wenn nichts zutrifft Bedingungen werden der Reihe nach ausgewertet und die erste Übereinstimmung wird ausgeführt. Der Else-Zweig wird ausgeführt, wenn nichts zutrifft. Gibt es kein Else und trifft nichts zu, wird die Prozedur mit dem Schritt nach dem Wenn fortgesetzt. Ein nicht behandelter Fall ist kein Fehler. #### Wenn-Zweige übernehmen keinen Zustand Keine Entscheidung innerhalb eines Wenn-Zweigs wird von späteren Schritten gespeichert. Wenn etwas, das in einem Zweig gelernt wurde, später benötigt wird, speichern Sie es explizit mit einem Tool-Aufruf oder einer dynamischen Variablen. #### Fragen-, Mitteilen- und Sagen-Schritte haben keine Tools Nur Tool-Schritte können Tools aufrufen. Sie müssen einem Fragen-, Mitteilen- oder Sagen-Schritt nicht mitteilen, dass er keine Tools aufrufen soll. Er kann es nicht. ## Strukturierte Prozedur verwalten #### Im Dashboard erstellen Öffnen Sie Ihren Agenten im [Dashboard](https://elevenlabs.io/app/agents) und wählen Sie dann **Prozeduren**. Verwenden Sie **+**, um eine strukturierte Prozedur zu erstellen. Fügen Sie einen Trigger hinzu, wählen Sie für jeden Schritt einen Typ aus und veröffentlichen Sie die Agentenänderungen. Das Dashboard validiert strukturierte Prozeduren während der Bearbeitung. Wenn eine Prozedur gegen eine [Validierungsregel](#validation-rules) verstößt, zeigt die Schaltfläche **Veröffentlichen** einen Fehlerstatus, der Tab **Prozeduren** zeigt ein Fehler-Badge an und die Vorschau kann erst gestartet werden, wenn die Prozedur korrigiert wurde. Wählen Sie die Fehleranzeige aus, um zu sehen, welche Prozedur und welcher Schritt betroffen ist. ![Editor für strukturierte Prozeduren mit der Schaltfläche „Veröffentlichen“ im Fehlerstatus und einem Badge mit 1 Fehler ](/docs/_fern-img/e406c33fac3966fab26d5d07e10d364a475fc4a56fd75aad2e23edbb0d1940d5.webp) ![Dialog mit Validierungsdetails, der die fehlerhafte Prozedur und den Schritt auflistet, der eine Nachricht benötigt](/docs/_fern-img/a1cc889b2d0e68ce23725609b531938d0f7c417b1c6f4375103531eaae4ada63.webp) #### Über die CLI verwalten Die [ElevenLabs CLI](/docs/de/eleven-agents/operate/cli) erstellt und veröffentlicht strukturierte Prozeduren mit denselben Befehlen wie Freiform-Prozeduren. Setzen Sie `type` auf `deterministic` und übergeben Sie die Schritte als JSON-kodierten String in `content`. ```bash CONTENT=$(jq -n '{ trigger: "When the user asks to refund an order", steps: [{ type: "ask", instruction: "Ask for the order ID." }] }') elevenlabs agents procedures create \ --agent-id agent_7101k5zvyjhmfg983brhmhkd98n6 \ --branch-id agtbranch_0901k4aafjxxfxt93gd841r7tv5t \ --json "$(jq -n --arg content "$CONTENT" '{ name: "Refund request", type: "deterministic", trigger: "When the user asks to refund an order", content: $content }')" elevenlabs agents update \ --agent-id agent_7101k5zvyjhmfg983brhmhkd98n6 \ --branch-id agtbranch_0901k4aafjxxfxt93gd841r7tv5t \ --json '{"version_description": "Publish refund procedure"}' ``` Beim Veröffentlichen werden alle strukturierten Prozeduren im Branch validiert. Ist eine ungültig, wird der Befehl mit einem Fehlercode beendet und gibt die Fehler nach Prozedur-ID aus. Korrigieren Sie den Prozedurentwurf und veröffentlichen Sie erneut. #### Über die API verwalten API- und SDK-Payloads verwenden `type: "deterministic"` für strukturierte Prozeduren. Ihr `content` ist ein JSON-kodiertes Dokument. ### Voraussetzungen * Ein ElevenLabs-API-Schlüssel in der Umgebungsvariablen `ELEVENLABS_API_KEY`. * Die Zielwerte `agent_id` und `branch_id`. Informationen zu Branch-Vorgängen finden Sie unter [Agent-Versionierung](/docs/de/eleven-agents/operate/versioning). * Version `2.60.0` oder neuer des Python-Pakets `elevenlabs` oder des JavaScript-Pakets `@elevenlabs/elevenlabs-js`. API-Bearbeitungen sind für Ihren Nutzer im ausgewählten Branch privat, bis Sie eine neue Agentenversion veröffentlichen. ### Entwurf erstellen oder aktualisieren Erstellen Sie eine strukturierte Prozedur mit `POST /procedures` und setzen Sie `type` auf `deterministic`. Aktualisieren Sie eine vorhandene Prozedur mit `PATCH /procedures/{procedure_id}/draft`, wie unten gezeigt. Setzen Sie `trigger` als Feld der obersten Ebene. JSON-kodieren Sie das Schrittdokument in `content`, statt ein verschachteltes Objekt zu senden. ```python focus={6-18} import json from elevenlabs import ElevenLabs elevenlabs = ElevenLabs() elevenlabs.conversational_ai.agents.procedures.drafts.update( agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6", branch_id="agtbranch_0901k4aafjxxfxt93gd841r7tv5t", procedure_id="agtprc_6qbpwdq8n01bxhk44bgjy6f10ck3", name="Refund request", type="deterministic", trigger="When the user asks to refund an order", content=json.dumps( { "steps": [{"type": "ask", "instruction": "Ask for the order ID."}], } ), ) ``` ```typescript focus={5-17} import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js"; const elevenlabs = new ElevenLabsClient(); await elevenlabs.conversationalAi.agents.procedures.drafts.update( "agent_7101k5zvyjhmfg983brhmhkd98n6", "agtbranch_0901k4aafjxxfxt93gd841r7tv5t", "agtprc_6qbpwdq8n01bxhk44bgjy6f10ck3", { name: "Refund request", type: "deterministic", trigger: "When the user asks to refund an order", content: JSON.stringify({ steps: [{ type: "ask", instruction: "Ask for the order ID." }], }), } ); ``` ```bash focus={1-9} curl -X PATCH "https://api.elevenlabs.io/v1/convai/agents/agent_7101k5zvyjhmfg983brhmhkd98n6/branches/agtbranch_0901k4aafjxxfxt93gd841r7tv5t/procedures/agtprc_6qbpwdq8n01bxhk44bgjy6f10ck3/draft" \ -H "xi-api-key: $ELEVENLABS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Refund request", "type": "deterministic", "trigger": "When the user asks to refund an order", "content": "{\"steps\":[{\"type\":\"ask\",\"instruction\":\"Ask for the order ID.\"}]}" }' ``` Das Speichern eines Prozedurentwurfs validiert seine Schritte nicht. Die Validierung wird beim Veröffentlichen oder beim Speichern des Agentenentwurfs mit `POST /v1/convai/agents/{agent_id}/drafts` ausgeführt. ### Änderungen veröffentlichen Veröffentlichen Sie mit [Agent aktualisieren](/docs/de/api-reference/agents/update). Beim Veröffentlichen werden alle strukturierten Prozeduren im Branch validiert, kompiliert und das Ergebnis mit der neuen Version gespeichert. Die Anfrage benötigt kein Feld `workflow`; die Kompilierung erfolgt beim Veröffentlichen. Informationen zur Bedeutung der Kompilierung finden Sie unter [Ausführung einer strukturierten Prozedur](#how-a-structured-procedure-runs). ```python focus={5-8} from elevenlabs import ElevenLabs elevenlabs = ElevenLabs() elevenlabs.conversational_ai.agents.update( agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6", branch_id="agtbranch_0901k4aafjxxfxt93gd841r7tv5t", ) ``` ```typescript focus={5-7} import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js"; const elevenlabs = new ElevenLabsClient(); await elevenlabs.conversationalAi.agents.update("agent_7101k5zvyjhmfg983brhmhkd98n6", { branchId: "agtbranch_0901k4aafjxxfxt93gd841r7tv5t", }); ``` ```bash focus={1-5} curl -X PATCH \ "https://api.elevenlabs.io/v1/convai/agents/agent_7101k5zvyjhmfg983brhmhkd98n6?branch_id=agtbranch_0901k4aafjxxfxt93gd841r7tv5t" \ -H "xi-api-key: $ELEVENLABS_API_KEY" \ -H "Content-Type: application/json" \ -d '{}' ``` Wenn eine strukturierte Prozedur ungültig ist, gibt das Veröffentlichen `400` zurück und es wird nichts gespeichert: ```json { "detail": { "status": "procedure_validation_failed", "message": "Structured procedures failed validation.", "data": { "errors": { "agtprc_6qbpwdq8n01bxhk44bgjy6f10ck3": [ { "path": "steps[0].ask.instruction", "message": "Step 1: Ask step requires an instruction" } ] } } } } ``` `errors` ist nach Prozedur-ID sortiert. Jeder Eintrag benennt das fehlerhafte Feld und den Schritt. Korrigieren Sie den Prozedurentwurf und veröffentlichen Sie erneut. > **Note** > > Der Endpunkt `/procedures/compile` aus früheren Versionen dieser API funktioniert weiterhin, ist jedoch > veraltet und wird irgendwann eingestellt. Das Veröffentlichen übernimmt die Kompilierung. Rufen Sie den > Compile-Endpunkt in neuem Code nicht auf. Informationen zum Entfernen von Entwürfen und zum Verwerfen von Änderungen finden Sie unter [Prozeduren verwalten](/docs/de/eleven-agents/customization/procedures#manage-procedures) oder vollständige Endpoint- Schemas in der [API-Referenz für Prozeduren](/docs/de/api-reference/agents/procedures/). ## Best Practices Jeder Schritttyp erzwingt bereits sein eigenes Verhalten, daher müssen Sie es selten explizit angeben. Beschreiben Sie die Absicht jedes Schritts und überlassen Sie dem Schritttyp den Rest. Die folgenden Hinweise behandeln die Fälle, die Sie korrekt umsetzen sollten. Um eine strukturierte Prozedur zu testen, folgen Sie [Eine Prozedur iterieren](/docs/de/eleven-agents/customization/procedures/free-form-procedures#iterating-on-a-procedure). ### Schritttypen auswählen #### Eine Frage pro Ask-Schritt stellen Ein Ask-Schritt wartet auf eine Antwort. Wenn Sie mehrere Fragen in einer Anweisung bündeln, überspringt oder kombiniert der Agent häufig einige davon. Verwenden Sie für jede Information einen Ask-Schritt. #### Tell für Aussagen und Ask für Fragen verwenden Ein Tell-Schritt übermittelt seine Nachricht und fährt fort, ohne zu warten. Ein als Frage formulierter Tell-Schritt erhält niemals eine Antwort. Wenn ein Schritt eine Antwort vom Nutzer benötigt, ist er ein Ask-Schritt. #### Ask-Schritten eine klare Abbruchbedingung geben, wenn die Frage allein nicht ausreicht Ein Ask-Schritt fährt fort, sobald er eine passende Antwort erhalten hat. Wenn aus der Frage nicht klar hervorgeht, was als Antwort zählt, geben Sie dies in der Anweisung an, zum Beispiel \_Fragen Sie nach der Bestell-ID; eine gültige ID hat acht Ziffern \_. #### Tell für Formulierungen, Say für exakte Worte wählen Verwenden Sie einen Tell-Schritt, wenn der Agent die Nachricht selbst formulieren soll, und einen Say-Schritt, wenn der Wortlaut wörtlich oder übersetzt sein muss. Beide übermitteln genau eine Nachricht, daher müssen Sie einen Schritt nicht anweisen, eine einzelne Nachricht zu senden. #### Nicht-Tool-Schritte nicht anweisen, Tools zu vermeiden Ask-, Tell- und Say-Schritte können keine Tools aufrufen. *Keine Tools aufrufen* in diese Schritte zu schreiben, fügt der Anweisung Rauschen hinzu, ohne das Verhalten zu ändern. ### Die Prozedur strukturieren #### Nicht zwischen zwei If-Schritten auffüllen Zwei If-Schritte können nicht direkt hintereinander platziert werden. Einen nicht zusammenhängenden Tell- oder Say-Schritt dazwischen einzufügen, um die Regel zu erfüllen, führt dazu, dass der Agent etwas sagt, das er nicht sagen sollte. Fassen Sie die zweite Entscheidung stattdessen im ersten If-Schritt als zusätzliche Else-if-Zweige zusammen oder verschieben Sie sie in eine Unterprozedur. #### Verschachtelte Entscheidungen in eine Unterprozedur verschieben If-Schritte können nicht verschachtelt werden. Wenn eine Entscheidung von einer anderen abhängt, verschieben Sie die innere Entscheidung in ihre eigene strukturierte Prozedur und rufen Sie sie mit einem Sub-procedure-Schritt aus dem Zweig auf, der sie benötigt. #### Ein Else hinzufügen, wenn „keines der oben genannten“ wichtig ist Ein If-Schritt ohne Else fährt mit dem nächsten Schritt fort, wenn nichts zutrifft. Wenn der nicht zutreffende Fall anders behandelt werden soll, fügen Sie dafür einen Else-Zweig hinzu. #### Alles speichern, was ein späterer Schritt benötigt Entscheidungen innerhalb eines If-Zweigs werden danach nicht gespeichert. Wenn ein späterer Schritt von etwas abhängt, das in einem Zweig ermittelt wurde, speichern Sie es mit einem Tool-Aufruf oder einer dynamischen Variable innerhalb des Zweigs. #### Ausdrucksbedingungen nach dem Tool platzieren, das sie füllt Ausdrucksbedingungen prüfen dynamische Variablen. Platzieren Sie einen If-Schritt, der sie verwendet, direkt nach dem Tool- Schritt, der diese Variablen setzt. Um nach dem zu verzweigen, was der Nutzer gesagt hat, verwenden Sie eine Textbedingung. #### Gemeinsame Schritte in eine Unterprozedur auslagern Wenn mehrere strukturierte Prozeduren dieselbe Abfolge teilen, etwa die Eskalation an einen Menschen, verschieben Sie diese in eine strukturierte Prozedur mit einem leeren Trigger und rufen Sie sie aus jeder Prozedur auf. Kopierte Abfolgen entwickeln sich mit der Zeit auseinander. ### Mit Tools arbeiten #### Einen Tool-Schritt mit If absichern, nicht mit seiner Anweisung Ein Tool-Schritt ruft sein Tool immer auf. Eine in die Anweisung geschriebene Bedingung wie *diesen Schritt überspringen, wenn das Ticket bereits markiert ist* kann den Aufruf nicht verhindern. Wenn der Aufruf nicht immer erfolgen soll, setzen Sie die Bedingung in einen If-Schritt vor dem Tool-Schritt. #### Parameterwerte festlegen, statt sie zu beschreiben Wenn ein Parameter immer einen bestimmten Wert annehmen muss, legen Sie ihn mit einem `constant`-Override in `schema_overrides` fest. Eine Anweisung wie *Status immer auf ausstehend setzen* fordert das Modell zur Einhaltung auf; ein Override wird erzwungen und kann nicht übersprungen werden. #### Jedem Tool-Schritt eine Fehlerbehandlung geben Ohne `on_failure` beendet jeder Tool-Fehler die Unterhaltung. Fügen Sie eine Behandlung hinzu, die dem Nutzer erklärt, was passiert ist, und den Vorgang wiederholt, eskaliert oder fortsetzt. #### Tool-Schritte auf den Tool-Aufruf beschränken Ein Tool-Schritt führt nur das Tool aus; der Agent kann dabei weder sprechen noch eine Entscheidung treffen. Um mit dem Nutzer zu sprechen oder anhand der Tool-Rückgabe zu verzweigen, verwenden Sie dafür einen separaten Schritt vor oder nach dem Tool-Schritt. ### Anweisungen schreiben #### Nur den aktuellen Schritt beschreiben Die Prozedur steuert, was als Nächstes ausgeführt wird, und der Agent kennt spätere Schritte während der Ausführung des aktuellen Schritts nicht. Lassen Sie die Schrittfolge die Reihenfolge bestimmen. #### Nicht versuchen, den Turn mit Prosa zu beenden Sätze in Schrittanweisungen wie *dies ist die letzte Nachricht dieses Turns* fordern den Agenten auf, eine Grenze durchzusetzen, die die Plattform nicht kennt. Verwenden Sie einen Ask-Schritt, um auf den Nutzer zu warten, oder das System-Tool `end_call`, um die Unterhaltung zu beenden. #### Globale Regeln im System-Prompt halten Ton, Formatierung, Verabschiedungen und Richtlinien für Ablehnungen gehören in den [System- Prompt](/docs/de/eleven-agents/best-practices/prompting-guide). Eine Schrittanweisung sollte nur angeben, was für diesen Schritt spezifisch ist. ### Prozeduren kombinieren Die allgemeinen Hinweise zum Kombinieren von Prozeduren gelten auch für strukturierte Prozeduren; siehe [Prozeduren kombinieren](/docs/de/eleven-agents/customization/procedures/free-form-procedures#composing-procedures) auf der Seite zu Freiform-Prozeduren. Ein Muster gilt speziell für die Kombination von Typen: Eine Freiform-Prozedur kann auf eine strukturierte Prozedur verweisen. Behalten Sie die offene Bearbeitung in einer Freiform-Prozedur und delegieren Sie die Teile, die jedes Mal gleich ablaufen müssen, etwa Identitätsprüfung oder Eskalation, an eine strukturierte Prozedur. ## Einschränkungen * If-Schritte können nicht verschachtelt werden, und zwei If-Schritte können nicht direkt hintereinander platziert werden. * Das einzige unterstützte System-Tool ist `end_call`. * Strukturierte Prozeduren können nicht auf Wissensdatenbankdokumente verweisen. * Es gibt keine Möglichkeit, den aktuellen Turn zu beenden, wenn eine Prozedur abgeschlossen ist; der Agent hält den Turn offen und spricht möglicherweise weiter. * Eine strukturierte Prozedur kann nicht von einem bestimmten Workflow-Knoten im Dashboard gestartet werden. * Das Starten einer Prozedur erhöht die Latenz: Der Agent führt einen Tool-Aufruf aus, um sie zu starten, und durchläuft anschließend den generierten Workflow. ### Unterstützung durch Modellanbieter Strukturierte Prozeduren erzwingen interne Tool-Aufrufe beim Starten einer Unterprozedur und beim Abschließen einer Prozedur. Die wichtigsten OpenAI-, Anthropic-, Gemini- und Grok-Modellfamilien unterstützen eine erzwungene Tool-Auswahl. Andere Modelle oder benutzerdefinierte Anbieter garantieren dies möglicherweise nicht, wodurch Übergänge zu Unterprozeduren oder der Abschluss von Prozeduren weniger zuverlässig sein können. Prüfen Sie die Unterstützung der erzwungenen Tool-Auswahl, wenn Sie einen anderen Modellanbieter verwenden. Unter [Prozeduren](/docs/de/eleven-agents/customization/procedures#limitations) finden Sie Einschränkungen, die für alle Prozeduren gelten, einschließlich der Begrenzung der Inhaltsgröße und der Unterschiede zwischen strukturierten und Freiform-Prozeduren.