> 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. # Code-Tools **Code-Tools** ermöglichen Ihrem Agenten, eigenes JavaScript in einer isolierten serverseitigen Umgebung auszuführen, ohne dass Sie einen eigenen Webhook-Endpunkt einrichten und hosten müssen. Schreiben Sie die Logik einmal im integrierten Code-Editor, und ElevenLabs führt sie aus, wann immer der Agent das Tool aufruft. > **Note** > > Diese Funktion ist nur für Enterprise verfügbar. ## Übersicht Ein Code-Tool ist eine JavaScript-Funktion, die ausgeführt wird, wenn der Agent sie aufruft. Sie schreiben den gesamten Funktionskörper, sodass das Tool je nach Aufgabe mehr oder weniger leisten kann: * **Eigene Berechnungen**: Wenden Sie Preisregeln, Einheitenumrechnungen, Bewertungslogik oder Datumsberechnungen nur mit den Tool-Aufrufparametern an. Kein Netzwerkzugriff erforderlich. * **Externe APIs aufrufen**: Verwenden Sie `fetch` für freigegebene Domains, wobei Workspace-Secrets und Auth-Verbindungen in den Kontext der Funktion eingefügt werden. * **Mehrere Quellen kombinieren**: Rufen Sie zwei oder drei APIs auf und führen Sie deren Ergebnisse zusammen, vergleichen oder gleichen Sie sie ab, bevor Sie eine einzelne Antwort zurückgeben. * **Bedingte Verzweigungen**: Führen Sie je nach Tool-Aufrufparametern unterschiedliche Logik aus, ohne für jeden Zweig ein separates Tool zu benötigen. * **Daten umformen**: Geben Sie genau die Struktur zurück, die der Agent sehen soll, statt einer unverarbeiteten Upstream-Antwort. > **Info** > > Für einen einzelnen externen API-Aufruf ohne eigene Logik sind [Webhook- Tools](/docs/de/eleven-agents/customization/tools/webhook-tools) meist einfacher einzurichten. Um > Aktionen im Browser oder in der App eines Nutzers auszulösen, verwenden Sie stattdessen [Client- Tools](/docs/de/eleven-agents/customization/tools/client-tools). ## So funktioniert es Ihr Code ist ein JavaScript-Modul, das eine einzelne standardmäßige asynchrone Funktion exportiert. Die Funktion erhält ein `ctx`-Objekt und gibt das Ergebnis des Tools zurück: ```javascript export default async (ctx) => { // ctx.args. — the parameters the agent passed to this tool call const { city } = ctx.args; return { message: `Hello from ${city}!` }; }; ``` Der zurückgegebene Wert wird zum Ergebnis des Tools. Er wird an den Agenten zurückgegeben, im Gesprächstranskript angezeigt und kann für die [dynamische Zuweisung von Variablen](/docs/de/eleven-agents/customization/tools/webhook-tools#tool-configuration) verwendet werden. ### Das `ctx`-Objekt `ctx` ist Ihr Zugang zu allem, worauf das Tool zum Zeitpunkt des Aufrufs zugreifen kann. Die vom Agenten bereitgestellten Parameter treffen immer in `ctx.args` ein; Secrets, Konfigurationswerte und Auth-Verbindungen sind optional und erscheinen nur, wenn Sie sie im Abschnitt **Context object** des Tools zuordnen. | Eigenschaft | Beschreibung | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ctx.args` | Die vom Agenten bereitgestellten Tool-Aufrufparameter. | | `ctx.config` | Einfache String-Variablen, die Sie dem Kontext dieses Tools zugeordnet haben. | | `ctx.secrets` | Workspace-Secrets, die Sie dem Kontext dieses Tools zur Verwendung in Anfrage-Headern zugeordnet haben. Das eigentliche Secret wird Ihrem Code nie offengelegt; die Einfügung erfolgt beim Ausleiten und ausschließlich in den Headern. | | `ctx.auth_connections` | Referenzen auf konfigurierte [Auth-Verbindungen](/docs/de/eleven-agents/customization/tools/webhook-tools#supported-authentication-methods), die Sie dem Kontext dieses Tools zur Verwendung im Anfrage-Header `X-With-Auth-Connection` zugeordnet haben. Die zugrunde liegenden Zugangsdaten werden Ihrem Code nie offengelegt; die Einfügung erfolgt beim Ausleiten und ausschließlich in den Headern. | > **Note** > > Nur `ctx.args` ist für den Agenten sichtbar, wenn er das Tool aufruft. Secrets, Konfigurationswerte und Auth- > Verbindungen werden dem Agenten nie offengelegt. #### Parameter konfigurieren Parameter sind die Werte, die der Agent beim Aufruf des Tools bereitstellt. Sie treffen in `ctx.args` ein. Definieren Sie sie im Abschnitt **Parameters** des Tool-Konfigurationsformulars oder im Code-Editor unter dem Tab **Params** im Untertab **Define Params**. Jeder Parameter benötigt einen Datentyp, einen Bezeichner und eine Beschreibung, anhand derer der Agent den richtigen Wert aus dem Gespräch bestimmt. Ihr Code liest diesen Wert über den Bezeichner aus, etwa `ctx.args.appointment_datetime` unten. ![Definition eines Code-Tool-Parameters](/docs/_fern-img/d492e864ae15f3a355251faae3b719544e1ab56b703c02740b51be6c6769ccf7.webp) #### Kontextobjekt konfigurieren Fügen Sie Secrets, Konfigurationswerte und Auth-Verbindungen im Abschnitt **Context object** des Tools hinzu. Jeder Eintrag benötigt einen Typ und einen Namen. Das Bedienfeld zeigt für jeden Eintrag den exakten Accessor an, etwa `ctx.secrets.DEMO_KEY` unten. ![Zuordnung eines Workspace-Secrets zum Kontextobjekt eines Code-Tools](/docs/_fern-img/ad58ee53f3591f447b108191aff760f1134350911933b968b06798fa6d42f438.webp) ### Netzwerkzugriff Code, der in der Sandbox ausgeführt wird, kann nur Domains erreichen, die Ihr Workspace ausdrücklich freigegeben hat. Fügen Sie die Domains, die Ihr Code aufrufen muss, in den **ElevenAgents Settings** unter **Code Tool Network Access** hinzu. Anfragen an andere Domains schlagen fehl. > **Warning** > > Zum Bearbeiten von **Code Tool Network Access** benötigen Sie Workspace-Admin-Berechtigungen. ### Ausführungslimits * **Timeout**: Jede Ausführung muss innerhalb des für das Tool konfigurierten Antwort-Timeouts von 1 bis 30 Sekunden abgeschlossen sein. * **Keine externen Pakete**: Code-Tools werden derzeit ohne npm-Abhängigkeiten ausgeführt. ### Code testen Verwenden Sie vor dem Speichern im Code-Editor **Run**, um Ihren Code mit Beispielparameterwerten auszuführen: * **Params** — Legen Sie Testwerte für jeden Parameter fest, den Ihr Tool definiert. * **Output** — Sehen Sie das zurückgegebene Ergebnis oder den Fehler, falls die Ausführung fehlgeschlagen ist. * **Logs** — Sehen Sie alles, was mit `console.log`, `console.warn` oder `console.error` geschrieben wurde, sowie Build- und Ausführungszeiten. ## Anleitung In dieser Anleitung erstellen wir ein Code-Tool, das eine Temperatur umrechnet und einen formatierten, verständlichen String zurückgibt: #### Neues Code-Tool erstellen Wählen Sie im Bereich **Agent** Ihrer Agent-Einstellungsseite **Add Tool**. Wählen Sie **Code** als Tool-Typ und legen Sie dann einen Namen und eine Beschreibung fest: | Feld | Wert | | ------------ | ---------------------------------------------------------- | | Name | convert_temperature | | Beschreibung | Rechnet eine Temperatur zwischen Celsius und Fahrenheit um | #### Parameter definieren Fügen Sie zwei Parameter hinzu, damit das LLM weiß, was es bereitstellen soll: | Datentyp | Bezeichner | Erforderlich | Beschreibung | | -------- | ---------- | ------------ | ------------------------------------- | | number | value | true | Der umzurechnende Temperaturwert | | string | from_unit | true | Die Ausgangseinheit: `"C"` oder `"F"` | #### Code schreiben Öffnen Sie den Code-Editor und ersetzen Sie den Standardquellcode durch: ```javascript export default async (ctx) => { const { value, from_unit } = ctx.args; if (from_unit === "C") { const fahrenheit = (value * 9) / 5 + 32; return { result: `${value}°C is ${fahrenheit.toFixed(1)}°F` }; } const celsius = ((value - 32) * 5) / 9; return { result: `${value}°F is ${celsius.toFixed(1)}°C` }; }; ``` Verwenden Sie **Run** mit einigen Beispielwerten (z. B. `value: 100, from_unit: "C"`), um die Ausgabe vor dem Speichern zu prüfen. #### Orchestrierung Aktualisieren Sie den System-Prompt Ihres Agenten, damit er weiß, wann er das Tool verwenden soll: **`System-Prompt`** ```plaintext System-Prompt When the user asks to convert a temperature, call convert_temperature with the value and its unit ("C" or "F"), and read back the result naturally. ``` #### Testen Starten Sie ein Gespräch und versuchen Sie Folgendes: > *Wie viel sind 100 Grad Celsius in Fahrenheit?* Der Agent sollte das Tool aufrufen und den umgerechneten Wert ausgeben. ### Authentifizierungsbeispiele **API mit einem Secret aufrufen** ```javascript export default async (ctx) => { const { order_id } = ctx.args; const response = await fetch(`https://api.example.com/orders/${order_id}`, { headers: { Authorization: `Bearer ${ctx.secrets.EXAMPLE_API_KEY}`, }, }); if (!response.ok) { throw new Error(`Upstream error: ${response.status}`); } return await response.json(); }; ``` Ordnen Sie `EXAMPLE_API_KEY` im Abschnitt **Context object** des Tools einem Workspace-Secret zu und fügen Sie dann `api.example.com` zu **Code Tool Network Access** hinzu, damit die Anfrage ausgeleitet werden darf. Der referenzierte Wert ist ein Platzhalter: Das echte Secret wird beim Ausleiten in den Header eingefügt und ist für Ihren Code nie sichtbar. **API mit einer OAuth-Auth-Verbindung aufrufen** ```javascript export default async (ctx) => { const { customer_id } = ctx.args; const response = await fetch(`https://api.example.com/customers/${customer_id}`, { headers: { "X-With-Auth-Connection": ctx.authConnections.EXAMPLE_CRM, }, }); if (!response.ok) { throw new Error(`Upstream error: ${response.status}`); } return await response.json(); }; ``` Ordnen Sie `EXAMPLE_CRM` im Abschnitt **Context object** des Tools einer konfigurierten [Auth-Verbindung](/docs/de/eleven-agents/customization/tools/webhook-tools#supported-authentication-methods) zu. Der referenzierte Wert ist ein Platzhalter: Die echten Zugangsdaten werden beim Ausleiten in den Header eingefügt und sind für Ihren Code nie sichtbar. ## Best Practices #### Tools intuitiv benennen und detailliert beschreiben Wenn der Assistent nicht die richtigen Tools aufruft, müssen Sie möglicherweise die Namen und Beschreibungen Ihrer Tools aktualisieren, damit der Assistent klarer versteht, wann er welches Tool auswählen soll. Vermeiden Sie Abkürzungen oder Akronyme, um Tool- und Argumentnamen zu verkürzen. Sie können auch detailliert beschreiben, wann ein Tool aufgerufen werden soll. Bei komplexen Tools sollten Sie jedes Argument beschreiben, damit der Assistent weiß, welche Angaben er vom Nutzer erfragen muss. #### Tool-Parameter intuitiv benennen und detailliert beschreiben Verwenden Sie klare und aussagekräftige Namen für Tool-Parameter. Geben Sie in der Beschreibung gegebenenfalls das erwartete Format eines Parameters an (z. B. YYYY-mm-dd oder dd/mm/yy für ein Datum). #### Erwägen Sie, im System-Prompt Ihres Assistenten zusätzliche Informationen dazu bereitzustellen, wie und wann Tools aufgerufen werden sollen Klare Anweisungen in Ihrem System-Prompt können die Genauigkeit von Tool-Aufrufen des Assistenten deutlich verbessern. Leiten Sie den Assistenten beispielsweise mit Anweisungen wie den folgenden an: ```plaintext Use `check_order_status` when the user inquires about the status of their order, such as 'Where is my order?' or 'Has my order shipped yet?'. ``` Geben Sie Kontext für komplexe Szenarien. Zum Beispiel: ```plaintext Before scheduling a meeting with `schedule_meeting`, check the user's calendar for availability using check_availability to avoid conflicts. ``` #### LLM-Auswahl > **Warning** > > Bei der Verwendung von Tools empfehlen wir intelligente Modelle wie GPT 6 oder Claude Sonnet 5.5. Die Wahl des LLM ist entscheidend für den Erfolg von Funktionsaufrufen. Einige LLMs haben möglicherweise Schwierigkeiten, die relevanten Parameter aus dem Gespräch zu extrahieren.