> 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. # Webhooktools **Tools** stellen je assistent in staat verbinding te maken met externe gegevens en systemen. Je kunt een set tools definiëren waartoe de assistent toegang heeft. De assistent gebruikt deze waar nodig op basis van het gesprek. ## Overzicht Veel applicaties vereisen dat assistenten externe API's aanroepen om realtime informatie op te halen. Tools geven je assistent de mogelijkheid om externe functieaanroepen naar apps van derden te doen, zodat je realtime informatie kunt ophalen. Hier zijn enkele voorbeelden waarin tools nuttig kunnen zijn: * **Gegevens ophalen**: stel een assistent in staat om realtime gegevens op te halen uit een database met REST-ondersteuning of een integratie van derden voordat deze de gebruiker antwoordt. * **Acties uitvoeren**: laat een assistent geauthenticeerde acties activeren op basis van het gesprek, zoals vergaderingen inplannen of retourzendingen starten. > **Info** > > Gebruik in plaats daarvan [client tools](/docs/nl/eleven-agents/customization/tools/client-tools) om te communiceren met applicatie-UI's of client-side events te activeren. ## Toolconfiguratie ElevenLabs-agents kunnen worden uitgerust met tools om te communiceren met externe API's. Anders dan bij traditionele requests genereert de assistent query-, body- en pathparameters dynamisch op basis van het gesprek en de parameterbeschrijvingen die je opgeeft. Alle toolconfiguraties en parameterbeschrijvingen helpen de assistent te bepalen **wanneer** en **hoe** deze tools gebruikt moeten worden. Werk de systeemprompt van de assistent bij om het gebruik van tools effectief te orkestreren en de volgorde en logica voor deze aanroepen te specificeren. Dit omvat: * **Welke tool** je onder welke voorwaarden gebruikt. * **Welke parameters** de tool nodig heeft om goed te functioneren. * **Hoe je** de responses verwerkt. \ #### Configuratie Definieer een algemene `Name` en `Description` om het doel van de tool te beschrijven. Dit helpt het LLM de tool te begrijpen en te weten wanneer het deze moet aanroepen. > **Info** > > Als de API pathparameters vereist, neem je variabelen op in het URL-pad door ze tussen accolades > `{}` te plaatsen, bijvoorbeeld: `/api/resource/{id}`, waarbij `id` een pathparameter is. ![Configuratie](/docs/_fern-img/fb6e6619e4e7a5f19c2a86f9c2a489f5cb33cfb0883c14a06f0eec3cb35d71d5.webp) #### Authenticatie Configureer authenticatie door aangepaste headers toe te voegen of kant-en-klare authenticatiemethoden via auth connections te gebruiken. ![Toolauthenticatie](/docs/_fern-img/5ffae070945a86b74975cd9b56679c2bb76f0ce70d05fe7b10e8e5dff6ddd630.webp) #### Headers Geef headers op die in de request moeten worden opgenomen. ![Headers](/docs/_fern-img/9c8c3f2d42f84a6e40922a4c777199e79646b174fa51b9e4d5b21695d7da3f66.webp) #### Pathparameters Neem variabelen op in het URL-pad door ze tussen accolades `{}` te plaatsen: * **Voorbeeld**: `/api/resource/{id}`, waarbij `id` een pathparameter is. ![Pathparameters](/docs/_fern-img/12dde95654a12f8fd5894eefe2bdbebb8b819072d3589ed32ddd578997f53c1d.webp) #### Bodyparameters Geef bodyparameters op die in de request moeten worden opgenomen. ![Bodyparameters](/docs/_fern-img/17627460d24323cc40f461196625d34a5825dbe85d684618be0bc46b11ff9205.webp) ### Contenttype Configureer de indeling voor de encoding van de requestbody: * **JSON** (standaard): verzendt bodyparameters als `application/json` * **URL-gecodeerd**: verzendt bodyparameters als `application/x-www-form-urlencoded` De URL-gecodeerde indeling is nuttig bij integratie met API's die het indienen van formuliergegevens vereisen, zoals: * Verouderde systemen die alleen formuliergecodeerde requests accepteren * OAuth-tokenendpoints * API's voor betalingsverwerking * Integraties van derden met specifieke vereisten voor contenttypes > **Info** > > De instelling voor het contenttype geldt alleen voor POST-, PUT- en PATCH-requests met bodyparameters. #### Queryparameters Geef queryparameters op die in de request moeten worden opgenomen. ![Queryparameters](/docs/_fern-img/4127f87fe066cdaa71df0e6f75caa24ec8174e7d156c74b3c62ea9df98b9712e.webp) #### Dynamische variabelentoewijzing Geef dynamische variabelen op die je voor later gebruik in het gesprek wilt bijwerken vanuit de toolresponse. ![Queryparameters](/docs/_fern-img/95ff0cae8613eafa8bc4312e7cafa39ac0eab34d2fd2b21f0894a30775366110.webp) ## Handleiding In deze handleiding maken we een weerassistent die realtime weersinformatie voor elke locatie kan geven. De assistent gebruikt geografische kennis om locatienamen om te zetten in coördinaten en nauwkeurige weergegevens op te halen. #### Configureer de weertool De weertool verzendt GET-requests naar `https://api.open-meteo.com/v1/forecast` met `latitude` en `longitude` als pathparameters die door het LLM worden opgegeven. #### Toevoegen via het dashboard Kies in het gedeelte **Agent** op de instellingenpagina van je agent **Add Tool**. Selecteer **Webhook** als Tool Type en configureer vervolgens de integratie met de weer-API met deze waarden: | Veld | Waarde | | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Naam | get\_weather | | Beschrijving | Haalt de huidige weersverwachting voor een locatie op | | 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) | Voeg twee pathparameters toe met het waardetype `LLM Prompt`: | Gegevenstype | Identificatie | Beschrijving | | ------------ | ------------- | --------------------------------------------------- | | string | latitude | De breedtegraadcoördinaat voor de gevraagde locatie | | string | longitude | De lengtegraadcoördinaat voor de gevraagde locatie | #### Toevoegen via de CLI #### Maak een toolconfiguratiebestand Sla het volgende op 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" } } } } ``` #### Voeg de tool toe ```bash elevenlabs tools add "get_weather" --type "webhook" --config-path ./tool_configs/get_weather.json ``` #### Verwijs naar de tool vanuit je agent Bewerk `agent_configs/.json`, voeg de ID van de tool toe aan `conversation_config.agent.prompt.tool_ids` en push vervolgens: ```bash elevenlabs agents push --agent "" ``` #### Toevoegen via de API ```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** > > Voor deze tool is geen API-sleutel vereist. Als er wel een vereist is, moet deze in de headers worden doorgegeven en als secret worden opgeslagen. #### Orkestratie Configureer je assistent om weersvragen intelligent af te handelen met deze systeemprompt: **`Systeemprompt`** ```plaintext Systeemprompt 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** > > Test je assistent door te vragen naar het weer op verschillende locaties. De assistent moet > specifieke locaties afhandelen ("Wat is het weer in Tokio?") en om verduidelijking vragen na algemene vragen ("Hoe > ziet het weer er vandaag uit?"). ## Ondersteunde authenticatiemethoden ElevenLabs Agents ondersteunt meerdere authenticatiemethoden om je tools veilig te verbinden met externe API's. Authenticatiemethoden worden geconfigureerd in de instellingen van je agent en vervolgens waar nodig gekoppeld aan afzonderlijke tools. ![Workspace-authverbinding](/docs/_fern-img/131f7e017f01eaba444cddc672efdb77415db1a4c3a39f05b92a1678c5cd68f1.webp) Na configuratie kun je deze authenticatiemethoden aan je tools koppelen en aangepaste headers beheren in de toolconfiguratie: ![Toolauthverbinding](/docs/_fern-img/c018c5bf11266512a6d6157e33274b1a12f8c20768e5ab18da0f20f933f8aea9.webp) #### OAuth2 Client Credentials Verwerkt automatisch de OAuth2-clientcredentialsflow. Configureer met je client-ID, client secret en token-URL (bijvoorbeeld `https://api.example.com/oauth/token`). Je kunt optioneel scopes opgeven als kommagescheiden waarden en aanvullende JSON-parameters. Stel dit in door in **Workspace Auth Connections** in het gedeelte **Agent** op de instellingenpagina van je agent op **Add Auth** te klikken. #### OAuth2 JWT Gebruikt JSON Web Token-authenticatie voor de OAuth 2.0 JWT Bearer-flow. Vereist je JWT-ondertekeningssecret, token-URL en algoritme (standaard: HS256). Configureer JWT-claims, waaronder issuer, audience en subject. Stel optioneel key ID, vervaltijd (standaard: 3600 seconden), scopes en extra parameters in. Stel dit in door in **Workspace Auth Connections** in het gedeelte **Agent** op de instellingenpagina van je agent op **Add Auth** te klikken. #### Basisauthenticatie Eenvoudige authenticatie met gebruikersnaam en wachtwoord voor API's die HTTP Basic Auth ondersteunen. Stel dit in door in **Workspace Auth Connections** in het gedeelte **Agent** op de instellingenpagina van je agent op **Add Auth** te klikken. #### Bearer tokens Tokengebaseerde authenticatie die de waarde van je bearer token toevoegt aan de requestheader. Configureer dit door een header aan de toolconfiguratie toe te voegen, **Secret** als headertype te selecteren en op **Create New Secret** te klikken. #### Aangepaste headers Voeg aangepaste authenticatieheaders met een willekeurige naam en waarde toe voor eigen authenticatiemethoden. Configureer dit door een header aan de toolconfiguratie toe te voegen en de **naam** en **waarde** op te geven. ## Best practices #### Geef tools intuïtieve namen met gedetailleerde beschrijvingen Als je merkt dat de assistent niet de juiste tools aanroept, moet je mogelijk de toolnamen en beschrijvingen bijwerken zodat de assistent duidelijker begrijpt wanneer elke tool moet worden geselecteerd. Gebruik geen afkortingen of acroniemen om tool- en argumentnamen in te korten. Je kunt ook gedetailleerd beschrijven wanneer een tool moet worden aangeroepen. Bij complexe tools moet je beschrijvingen voor elk argument opnemen, zodat de assistent weet welke informatie hij aan de gebruiker moet vragen om dat argument te verzamelen. #### Geef toolparameters intuïtieve namen met gedetailleerde beschrijvingen Gebruik duidelijke en beschrijvende namen voor toolparameters. Geef indien van toepassing in de beschrijving de verwachte indeling voor een parameter op (bijvoorbeeld YYYY-mm-dd of dd/mm/yy voor een datum). #### Overweeg om in de systeemprompt van je assistent aanvullende informatie te geven over hoe en wanneer tools moeten worden aangeroepen Duidelijke instructies in je systeemprompt kunnen de nauwkeurigheid van toolaanroepen door de assistent aanzienlijk verbeteren. Geef de assistent bijvoorbeeld instructies zoals de volgende: ```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?'. ``` Geef context voor complexe scenario's. Bijvoorbeeld: ```plaintext Before scheduling a meeting with `schedule_meeting`, check the user's calendar for availability using check_availability to avoid conflicts. ``` #### LLM-selectie > **Warning** > > Bij het gebruik van tools raden we aan om modellen met hoge intelligentie te kiezen, zoals GPT 6 of Claude Sonnet 5.5. Het is belangrijk om te weten dat de keuze van LLM bepalend is voor het succes van functieaanroepen. Sommige LLM's kunnen moeite hebben met het extraheren van de relevante parameters uit het gesprek. ## Geluiden bij toolaanroepen Je kunt ambient audio configureren die tijdens de uitvoering van een tool wordt afgespeeld om de gebruikerservaring te verbeteren. Lees meer over [geluiden bij toolaanroepen](/docs/nl/eleven-agents/customization/tools/tool-configuration/tool-call-sounds).