> 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. # Webhook-Tools **Tools** ermöglichen Ihrem Assistenten die Verbindung mit externen Daten und Systemen. Sie können eine Reihe von Tools definieren, auf die der Assistent zugreifen kann. Der Assistent nutzt sie je nach Gespräch, wenn passend. ## Überblick Viele Anwendungen benötigen Assistenten, die externe APIs aufrufen, um Echtzeitinformationen abzurufen. Tools ermöglichen Ihrem Assistenten externe Funktionsaufrufe an Drittanbieter-Apps, damit Sie Echtzeitinformationen erhalten. Hier sind einige Beispiele, bei denen Tools nützlich sind: * **Daten abrufen**: Ermöglichen Sie einem Assistenten, vor der Antwort an den Nutzer Echtzeitdaten aus jeder REST-fähigen Datenbank oder Drittanbieter-Integration abzurufen. * **Aktionen ausführen**: Erlauben Sie einem Assistenten, basierend auf dem Gespräch authentifizierte Aktionen auszulösen, etwa Meetings zu planen oder Warenrücksendungen einzuleiten. > **Info** > > Um mit Anwendungsoberflächen zu interagieren oder clientseitige Ereignisse auszulösen, verwenden Sie stattdessen [Client- Tools](/docs/de/eleven-agents/customization/tools/client-tools). ## Tool-Konfiguration ElevenLabs Agents können mit Tools ausgestattet werden, um mit externen APIs zu interagieren. Anders als bei herkömmlichen Anfragen generiert der Assistent Abfrage-, Body- und Pfadparameter dynamisch basierend auf dem Gespräch und den von Ihnen bereitgestellten Parameterbeschreibungen. Alle Tool-Konfigurationen und Parameterbeschreibungen helfen dem Assistenten zu bestimmen, **wann** und **wie** diese Tools eingesetzt werden. Um den Einsatz von Tools effektiv zu orchestrieren, aktualisieren Sie den System-Prompt des Assistenten, um die Reihenfolge und Logik dieser Aufrufe festzulegen. Dazu gehören: * **Welches Tool** unter welchen Bedingungen verwendet wird. * **Welche Parameter** das Tool benötigt, um korrekt zu funktionieren. * **Wie** Antworten verarbeitet werden. \ #### Konfiguration Definieren Sie einen übergeordneten `Name` und eine `Description`, um den Zweck des Tools zu beschreiben. Das hilft dem LLM, das Tool zu verstehen und zu erkennen, wann es aufgerufen werden soll. > **Info** > > Falls die API Pfadparameter erfordert, fügen Sie Variablen im URL-Pfad ein, indem Sie sie in geschweifte > Klammern `{}` setzen, zum Beispiel: `/api/resource/{id}`, wobei `id` ein Pfadparameter ist. ![Konfiguration](/docs/_fern-img/fb6e6619e4e7a5f19c2a86f9c2a489f5cb33cfb0883c14a06f0eec3cb35d71d5.webp) #### Authentifizierung Konfigurieren Sie die Authentifizierung, indem Sie benutzerdefinierte Header hinzufügen oder integrierte Authentifizierungsmethoden über Auth-Verbindungen nutzen. ![Tool-Authentifizierung](/docs/_fern-img/5ffae070945a86b74975cd9b56679c2bb76f0ce70d05fe7b10e8e5dff6ddd630.webp) #### Header Geben Sie alle Header an, die in die Anfrage aufgenommen werden müssen. ![Header](/docs/_fern-img/9c8c3f2d42f84a6e40922a4c777199e79646b174fa51b9e4d5b21695d7da3f66.webp) #### Pfadparameter Fügen Sie Variablen im URL-Pfad ein, indem Sie sie in geschweifte Klammern `{}` setzen: * **Beispiel**: `/api/resource/{id}`, wobei `id` ein Pfadparameter ist. ![Pfadparameter](/docs/_fern-img/12dde95654a12f8fd5894eefe2bdbebb8b819072d3589ed32ddd578997f53c1d.webp) #### Body-Parameter Geben Sie alle Body-Parameter an, die in die Anfrage aufgenommen werden sollen. ![Body-Parameter](/docs/_fern-img/17627460d24323cc40f461196625d34a5825dbe85d684618be0bc46b11ff9205.webp) ### Content Type Konfigurieren Sie das Format für die Kodierung des Anfrage-Bodys: * **JSON** (Standard): Sendet Body-Parameter als `application/json` * **URL-kodiert**: Sendet Body-Parameter als `application/x-www-form-urlencoded` Das URL-kodierte Format ist nützlich bei der Integration mit APIs, die die Übermittlung von Formulardaten erfordern, etwa: * Altsysteme, die nur formularcodierte Anfragen akzeptieren * OAuth-Token-Endpunkte * APIs zur Zahlungsabwicklung * Drittanbieter-Integrationen mit spezifischen Content-Type-Anforderungen > **Info** > > Die Content-Type-Einstellung gilt nur für POST-, PUT- und PATCH-Anfragen mit Body-Parametern. #### Abfrageparameter Geben Sie alle Abfrageparameter an, die in die Anfrage aufgenommen werden sollen. ![Abfrageparameter](/docs/_fern-img/4127f87fe066cdaa71df0e6f75caa24ec8174e7d156c74b3c62ea9df98b9712e.webp) #### Dynamische Variablenzuweisung Geben Sie dynamische Variablen an, die für die spätere Verwendung im Gespräch aus der Tool-Antwort aktualisiert werden sollen. ![Abfrageparameter](/docs/_fern-img/95ff0cae8613eafa8bc4312e7cafa39ac0eab34d2fd2b21f0894a30775366110.webp) ## Anleitung In dieser Anleitung erstellen wir einen Wetterassistenten, der für jeden Ort Wetterinformationen in Echtzeit bereitstellen kann. Der Assistent nutzt sein geografisches Wissen, um Ortsnamen in Koordinaten umzuwandeln und präzise Wetterdaten abzurufen. #### Wetter-Tool konfigurieren Das Wetter-Tool sendet GET-Anfragen an `https://api.open-meteo.com/v1/forecast` mit `latitude` und `longitude` als vom LLM bereitgestellten Pfadparametern. #### Über das Dashboard hinzufügen Wählen Sie im Bereich **Agent** auf der Einstellungsseite Ihres Agenten **Add Tool**. Wählen Sie **Webhook** als Tool-Typ und konfigurieren Sie dann die Wetter-API-Integration mit diesen Werten: | Feld | Wert | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Name | get_weather | | Beschreibung | Ruft die aktuelle Wettervorhersage für einen Ort ab | | Methode | GET | | URL | [https://api.open-meteo.com/v1/forecast?latitude=\{latitude}\&longitude=\{longitude}\¤t=temperature_2m,wind_speed_10m\&hourly=temperature_2m,relative_humidity_2m,wind_speed_10m](https://api.open-meteo.com/v1/forecast?latitude=\{latitude}\&longitude=\{longitude}\¤t=temperature_2m,wind_speed_10m\&hourly=temperature_2m,relative_humidity_2m,wind_speed_10m) | Fügen Sie zwei Pfadparameter mit dem Werttyp `LLM Prompt` hinzu: | Datentyp | Bezeichner | Beschreibung | | -------- | ---------- | ----------------------------------------- | | string | latitude | Der Breitengrad für den angeforderten Ort | | string | longitude | Der Längengrad für den angeforderten Ort | #### Über die CLI hinzufügen #### Tool-Konfigurationsdatei erstellen Speichern Sie Folgendes als `tool_configs/get_weather.json`: ```json { "type": "webhook", "name": "get_weather", "description": "Gets the current weather forecast for a location", "api_schema": { "url": "https://api.open-meteo.com/v1/forecast?current=temperature_2m,wind_speed_10m", "method": "GET", "path_params_schema": { "latitude": { "type": "string", "description": "The latitude coordinate for the requested location" }, "longitude": { "type": "string", "description": "The longitude coordinate for the requested location" } } } } ``` #### Tool hinzufügen ```bash elevenlabs tools add "get_weather" --type "webhook" --config-path ./tool_configs/get_weather.json ``` #### Das Tool in Ihrem Agenten referenzieren Bearbeiten Sie `agent_configs/.json`, fügen Sie die ID des Tools zu `conversation_config.agent.prompt.tool_ids` hinzu und übertragen Sie die Änderungen: ```bash elevenlabs agents push --agent "" ``` #### Über die API hinzufügen ```python from elevenlabs import ElevenLabs, ToolRequestModel elevenlabs = ElevenLabs() tool = elevenlabs.conversational_ai.tools.create( request=ToolRequestModel( tool_config={ "type": "webhook", "name": "get_weather", "description": "Gets the current weather forecast for a location", "api_schema": { "url": "https://api.open-meteo.com/v1/forecast?current=temperature_2m,wind_speed_10m", "method": "GET", "path_params_schema": { "latitude": { "type": "string", "description": "The latitude coordinate for the requested location", }, "longitude": { "type": "string", "description": "The longitude coordinate for the requested location", }, }, }, } ) ) elevenlabs.conversational_ai.agents.update( agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6", conversation_config={ "agent": {"prompt": {"tool_ids": [tool.id]}}, }, ) ``` ```typescript import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js"; const elevenlabs = new ElevenLabsClient(); const tool = await elevenlabs.conversationalAi.tools.create({ toolConfig: { type: "webhook", name: "get_weather", description: "Gets the current weather forecast for a location", apiSchema: { url: "https://api.open-meteo.com/v1/forecast?current=temperature_2m,wind_speed_10m", method: "GET", pathParamsSchema: { latitude: { type: "string", description: "The latitude coordinate for the requested location", }, longitude: { type: "string", description: "The longitude coordinate for the requested location", }, }, }, }, }); await elevenlabs.conversationalAi.agents.update("agent_7101k5zvyjhmfg983brhmhkd98n6", { conversationConfig: { agent: { prompt: { toolIds: [tool.id] } }, }, }); ``` > **Warning** > > Für dieses Tool ist kein API-Schlüssel erforderlich. Falls einer erforderlich ist, sollte er in den Headern übergeben und als Secret gespeichert werden. #### Orchestrierung Konfigurieren Sie Ihren Assistenten mit diesem System-Prompt für die intelligente Bearbeitung von Wetteranfragen: **`System prompt`** ```plaintext System prompt You are a helpful conversational agent with access to a weather tool. When users ask about weather conditions, use the get_weather tool to fetch accurate, real-time data. The tool requires a latitude and longitude - use your geographic knowledge to convert location names to coordinates accurately. Never ask users for coordinates - you must determine these yourself. Always report weather information conversationally, referring to locations by name only. For weather requests: 1. Extract the location from the user's message 2. Convert the location to coordinates and call get_weather 3. Present the information naturally and helpfully For non-weather queries, provide friendly assistance within your knowledge boundaries. Always be concise, accurate, and helpful. First message: "Hey, how can I help you today?" ``` > **Success** > > Testen Sie Ihren Assistenten, indem Sie nach dem Wetter an verschiedenen Orten fragen. Der Assistent sollte > konkrete Orte ("Wie ist das Wetter in Tokio?") verarbeiten und bei allgemeinen Anfragen um Klärung bitten ("Wie > wird das Wetter heute?"). ## Unterstützte Authentifizierungsmethoden ElevenLabs Agents unterstützt mehrere Authentifizierungsmethoden, um Ihre Tools sicher mit externen APIs zu verbinden. Die Authentifizierungsmethoden werden in Ihren Agenteneinstellungen konfiguriert und bei Bedarf mit einzelnen Tools verbunden. ![Workspace-Auth-Verbindung](/docs/_fern-img/131f7e017f01eaba444cddc672efdb77415db1a4c3a39f05b92a1678c5cd68f1.webp) Nach der Konfiguration können Sie diese Authentifizierungsmethoden mit Ihren Tools verbinden und benutzerdefinierte Header in der Tool-Konfiguration verwalten: ![Tool-Auth-Verbindung](/docs/_fern-img/c018c5bf11266512a6d6157e33274b1a12f8c20768e5ab18da0f20f933f8aea9.webp) #### OAuth2-Client-Anmeldedaten Verarbeitet den OAuth2-Flow für Client-Anmeldedaten automatisch. Konfigurieren Sie ihn mit Ihrer Client-ID, Ihrem Client-Secret und der Token-URL (z. B. `https://api.example.com/oauth/token`). Optional können Sie Scopes als kommagetrennte Werte und zusätzliche JSON-Parameter angeben. Richten Sie dies ein, indem Sie im Bereich **Agent** auf der Einstellungsseite Ihres Agenten unter **Workspace Auth Connections** auf **Add Auth** klicken. #### OAuth2 JWT Verwendet JSON-Web-Token-Authentifizierung für den OAuth-2.0-JWT-Bearer-Flow. Erfordert Ihr JWT-Signatur-Secret, die Token-URL und den Algorithmus (Standard: HS256). Konfigurieren Sie JWT-Claims, einschließlich Aussteller, Zielgruppe und Betreff. Optional können Sie Schlüssel-ID, Ablaufzeit (Standard: 3600 Sekunden), Scopes und zusätzliche Parameter festlegen. Richten Sie dies ein, indem Sie im Bereich **Agent** auf der Einstellungsseite Ihres Agenten unter **Workspace Auth Connections** auf **Add Auth** klicken. #### Basic Authentication Einfache Benutzername-Passwort-Authentifizierung für APIs, die HTTP Basic Auth unterstützen. Richten Sie dies ein, indem Sie im Bereich **Agent** auf der Einstellungsseite Ihres Agenten unter **Workspace Auth Connections** auf **Add Auth** klicken. #### Bearer-Token Tokenbasierte Authentifizierung, die Ihren Bearer-Token-Wert zum Anfrage-Header hinzufügt. Konfigurieren Sie sie, indem Sie der Tool-Konfiguration einen Header hinzufügen, **Secret** als Header-Typ wählen und auf **Create New Secret** klicken. #### Benutzerdefinierte Header Fügen Sie für proprietäre Authentifizierungsmethoden benutzerdefinierte Authentifizierungs-Header mit beliebigem Namen und Wert hinzu. Konfigurieren Sie sie, indem Sie der Tool-Konfiguration einen Header hinzufügen und dessen **name** und **value** angeben. ## 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. ## Tool-Aufrufgeräusche Sie können Umgebungsgeräusche konfigurieren, die während der Tool-Ausführung abgespielt werden, um die Nutzererfahrung zu verbessern. Erfahren Sie mehr über [Tool-Aufrufgeräusche](/docs/de/eleven-agents/customization/tools/tool-configuration/tool-call-sounds).