Tools als code
Bouw, bewerk en versiebeheer agenttools met de Python- en JavaScript-SDK’s
Overzicht
Een tool wordt opgeslagen als een configuratie met geneste JSON-schema’s voor de parameters. Als je die configuratie handmatig schrijft, moet je padparameters laten overeenkomen met de URL, required-lijsten met de bijbehorende eigenschappen en elke parameter precies één waardebron geven. Met de toolbuilder in de Python- en JavaScript-SDK’s kun je dezelfde tool beschrijven met gekoppelde method calls. Vervolgens produceert deze de request die tools.create() en tools.update() al accepteren.
Gebruik deze om:
- Webhook-, client- en systeemtools in code te definiëren en ze te beoordelen zoals elke andere codewijziging.
- Een tool te laden, één parameter te wijzigen en deze terug te sturen zonder de rest van de configuratie te verstoren.
- Tools als JSON in versiebeheer op te slaan en ze in CI te valideren.
De builder draait volledig in de SDK. Hij roept geen nieuwe API-endpoints aan en alles wat hij bouwt, kan in het dashboard worden geopend en bewerkt.
Vereisten
- Python: het pakket
elevenlabs. De builder wordt geïmporteerd vanuitelevenlabs.agent_tools. - JavaScript: het pakket
@elevenlabs/elevenlabs-js. De builder wordt geëxporteerd vanuit de pakketroot.
Een webhooktool bouwen
Tool.webhook(name, description) start een webhooktool. De naam en beschrijving ziet de LLM wanneer die beslist of de tool wordt aangeroepen. Dit voorbeeld zoekt een bestelling op aan de hand van het nummer dat de beller opgeeft, stuurt een API-sleutel vanuit de secrets van de workspace en slaat de status van de bestelling op in een dynamische variabele:
De requestmethoden stellen de HTTP-methode en URL in. Tijdelijke aanduidingen {name} in de URL worden ingevuld vanuit padparameters:
Als je een parameter of header instelt waarvan de naam al bestaat, wordt die vervangen en behoudt deze zijn positie. Met remove_path_param(), remove_query_param(), remove_header() en remove_assignment() (in JavaScript removePathParam() enzovoort) verwijder je er één. Parameternamen moeten uniek zijn voor pad, query en body.
Een body is een objectschema dat eigenschap voor eigenschap wordt opgebouwd:
Parameterschema’s
Schema bouwt de parameterschema’s die webhook- en clienttools gebruiken. Elke methode retourneert een nieuw schema en laat het schema waarop deze is aangeroepen ongewijzigd, zodat je een schema één keer kunt definiëren en in meerdere tools kunt gebruiken.
Waar een waarde vandaan komt
Elke letterlijke waarde heeft precies één waardebron nodig, ongeacht waar deze voorkomt: in een parameter, in een body, in een responseschema of binnen een object of array. Een object of array kan er ook één hebben, die dan de volledige waarde levert.
Voor een object of array documenteert describe() de container voor de LLM en heeft elke eigenschap of elk element nog steeds een eigen bron.
Andere schemamethoden
Headers en authenticatie
Een headerwaarde komt uit een van vier bronnen. Gebruik voor gevoelige gegevens een secret of omgevingsvariabele, zodat de waarde nooit in de toolconfiguratie verschijnt:
AuthConnection.id(id) gebruikt een auth-verbinding uit de workspace op basis van ID. AuthConnection.env_var(label) / AuthConnection.envVar(label) kiest deze uit een omgevingsvariabele, zodat dezelfde toolconfiguratie in elke omgeving een andere verbinding kan gebruiken.
Een clienttool bouwen
Tool.client(name, description) start een clienttool, die in je applicatie draait in plaats van op een server. Voeg parameters toe met param(name, schema). Stel expects_response / expectsResponse in wanneer de agent moet wachten op het resultaat van je applicatie:
Een systeemtool bouwen
Systeemtools zijn ingebouwd in het platform. Elke tool heeft een eigen constructor op SystemTool, die de instellingen van die tool accepteert:
De twee transfertools halen hun bestemmingen uit transfer(condition, destination, options). De voorwaarde vertelt de LLM wanneer deze daarnaartoe moet transfereren en de bestemming gebruikt dezelfde Destination als workflows als code. Voor een transfer naar een SIP-URI is een SIP REFER-transfer nodig:
Toolopties
Instellingen die alle soorten tools delen, plaats je in options(): als keyword arguments in Python en als object in JavaScript. De namen komen overeen met de velden van de toolconfiguratie in de API:
De responsetime-out van een webhooktool is 5 tot 300 seconden. Die van een clienttool is 1 tot 120 seconden, of -1 om zo lang als nodig te wachten; daarvoor is expects_response / expectsResponse vereist. Voor follow_redirects / followRedirects is een lijst met toegestane domeinen vereist.
Tools aan een agent koppelen
Webhook- en clienttools worden afzonderlijk gemaakt met tools.create() en via ID aan agents gekoppeld, zodat één tool door meerdere agents kan worden gedeeld. Systeemtools maken deel uit van de configuratie van de agent: build_config() / buildConfig() retourneert de invoer voor de ingebouwde tools van de agent.
Het veld prompt.tools van de agent, waarin toolconfiguraties inline worden opgeslagen, is verouderd. Het kan niet worden
gecombineerd met tool_ids, en wanneer een request het bevat, worden de ingebouwde tools van de agent vervangen
door de systeemtools die het bevat. Maak tools met tools.create() en koppel ze in plaats daarvan via ID.
Een bestaande tool bewerken
Tool.from_response() / Tool.fromResponse() laadt een tool die wordt geretourneerd door tools.get(). Velden die de builder niet modelleert en de standaardwaarden die de API invult, blijven behouden, dus terugsturen wijzigt alleen wat je hebt gewijzigd. as_webhook(), as_client() en as_system() (in JavaScript asWebhook() enzovoort) geven je de getypeerde tool om te bewerken, of None / undefined als het een ander soort tool is.
Om een body-eigenschap te wijzigen, lees je het bodyschema, stel je de eigenschap opnieuw in en stel je de body in:
Tools opslaan in versiebeheer
to_json_string() / toJSONString() schrijft de tool in het wireformat van de API: snake_case-sleutels, gesorteerd op elk niveau, met inspringing van 2 spaties. Het heeft dezelfde structuur als de CLI bewaart in de directory tool_configs/, en beide SDK’s schrijven voor dezelfde tool byte voor byte identieke bestanden, zodat diffs klein blijven. Tool.from_json() / Tool.fromJSON() leest het weer in.
Een gebruikelijke opzet is dezelfde als voor workflows: vul de bestanden eerst met elevenlabs tools pull, bewerk ze rechtstreeks of met de builder, voer Tool.from_json(file).build() / Tool.fromJSON(file).build() uit in CI voor elke pull request en push ze bij een merge met tools.update() of elevenlabs tools push.
Validatie
Gekoppelde calls mislukken nooit op zichzelf. build(), build_config() / buildConfig(), to_json() / toJSON() en to_json_string() / toJSONString() controleren de volledige tool en geven of werpen één ToolValidationError waarvan de lijst issues elk probleem bevat, met telkens een code, een message en het path van het betreffende onderdeel, zoals body.reason.
Fouten omvatten:
- Een tijdelijke aanduiding in een URL zonder padparameter, of een padparameter zonder tijdelijke aanduiding. Templates voor omgevingsvariabelen zoals
{{system__env_api_host}}zijn geen tijdelijke aanduidingen. - Een letterlijke waarde zonder waardebron, of met meer dan één bron.
- Een body bij een
GET, of geen body bij eenPOST,PUTofPATCH. - Dezelfde parameternaam in meer dan één van pad, query en body.
omit()bij een verplichte eigenschap,choices()bij een schema dat geen string is, of een constante die niet overeenkomt met het type van het schema.- Een transfertool zonder bestemmingen, een bestemming van het verkeerde type of een SIP-URI-bestemming zonder SIP REFER-transfer.
- Een optie die niet van toepassing is op het soort tool, of een time-out buiten het toegestane bereik.
Tooltypen die nieuwer zijn dan je SDK
Een tool die uit de API of uit een bestand is geladen, kan een type hebben dat de builder niet kan bewerken, zoals een MCP-tool. Deze wordt geladen met het type "other" en gaat ongewijzigd heen en terug via from_json() / fromJSON() en to_json_string() / toJSONString(). build() rapporteert deze als waarschuwing via on_warning / onWarning.