Tools als Code
Agent-Tools mit den Python- und JavaScript-SDKs erstellen, bearbeiten und versionieren
Überblick
Ein Tool wird als Konfiguration mit verschachtelten JSON-Schemas für seine Parameter gespeichert. Wenn Sie diese Konfiguration von Hand schreiben, müssen Pfadparameter zur URL passen, required-Listen zu ihren Eigenschaften passen und jeder Parameter genau eine Wertequelle haben. Mit dem Tool-Builder in den Python- und JavaScript-SDKs beschreiben Sie dasselbe Tool mit verketteten Methodenaufrufen. Er erstellt dann die Anfrage, die tools.create() und tools.update() bereits akzeptieren.
Verwenden Sie ihn, um:
- Webhook-, Client- und System-Tools im Code zu definieren und wie jede andere Codeänderung zu prüfen.
- Ein Tool zu laden, einen Parameter zu ändern und es zurückzuspielen, ohne den Rest seiner Konfiguration zu verändern.
- Tools als JSON in der Versionsverwaltung zu speichern und sie in CI zu validieren.
Der Builder läuft vollständig im SDK. Er ruft keine neuen API-Endpunkte auf, und alles, was er erstellt, kann im Dashboard geöffnet und bearbeitet werden.
Voraussetzungen
- Python: das Paket
elevenlabs. Der Builder wird auselevenlabs.agent_toolsimportiert. - JavaScript: das Paket
@elevenlabs/elevenlabs-js. Der Builder wird aus dem Paketstamm exportiert.
Ein Webhook-Tool erstellen
Tool.webhook(name, description) startet ein Webhook-Tool. Name und Beschreibung sieht das LLM, wenn es entscheidet, ob es das Tool aufrufen soll. Dieses Beispiel sucht eine Bestellung anhand der vom Anrufer angegebenen Nummer, sendet einen API-Schlüssel aus den Secrets des Workspace und speichert den Bestellstatus in einer dynamischen Variable:
Die Anfragemethoden legen HTTP-Methode und URL fest. {name}-Platzhalter in der URL werden aus Pfadparametern gefüllt:
Das Setzen eines Parameters oder Headers mit einem bereits vorhandenen Namen ersetzt ihn und behält seine Position bei. remove_path_param(), remove_query_param(), remove_header() und remove_assignment() (in JavaScript removePathParam() usw.) entfernen jeweils einen. Parameternamen müssen über Pfad, Abfrage und Body hinweg eindeutig sein.
Ein Body ist ein Objektschema, das Eigenschaft für Eigenschaft erstellt wird:
Parameterschemas
Schema erstellt die Parameterschemas, die Webhook- und Client-Tools verwenden. Jede Methode gibt ein neues Schema zurück und lässt das Schema, für das sie aufgerufen wurde, unverändert. So können Sie ein Schema einmal definieren und in mehreren Tools verwenden.
Woher ein Wert kommt
Jeder Literalwert benötigt genau eine Wertequelle, unabhängig davon, wo er vorkommt: in einem Parameter, einem Body, einem Response-Schema oder innerhalb eines Objekts oder Arrays. Auch ein Objekt oder Array kann eine haben, die dann den gesamten Wert liefert.
Bei einem Objekt oder Array dokumentiert describe() den Container für das LLM, und jede Eigenschaft oder jedes Element hat weiterhin eine eigene Quelle.
Weitere Schemamethoden
Header und Authentifizierung
Ein Header-Wert stammt aus einer von vier Quellen. Verwenden Sie für alles Sensible ein Secret oder eine Umgebungsvariable, damit der Wert nie in der Tool-Konfiguration erscheint:
AuthConnection.id(id) verwendet eine Auth-Verbindung aus dem Workspace anhand ihrer ID. AuthConnection.env_var(label) / AuthConnection.envVar(label) wählt sie aus einer Umgebungsvariable aus, sodass dieselbe Tool-Konfiguration in jeder Umgebung eine andere Verbindung verwenden kann.
Ein Client-Tool erstellen
Tool.client(name, description) startet ein Client-Tool, das in Ihrer Anwendung statt auf einem Server ausgeführt wird. Fügen Sie die Parameter mit param(name, schema) hinzu. Setzen Sie expects_response / expectsResponse, wenn der Agent auf das Ergebnis Ihrer Anwendung warten soll:
Ein System-Tool erstellen
System-Tools sind in die Plattform integriert. Jedes verfügt über einen eigenen Konstruktor in SystemTool, der die Einstellungen dieses Tools übernimmt:
Die beiden Transfer-Tools übernehmen ihre Ziele aus transfer(condition, destination, options). Die Bedingung teilt dem LLM mit, wann dorthin transferiert werden soll, und das Ziel verwendet dasselbe Destination wie Workflows als Code. Ein Transfer zu einer SIP-URI benötigt einen SIP-REFER-Transfer:
Tool-Optionen
Einstellungen, die für alle Tool-Arten gelten, stehen in options(): in Python als Keyword-Argumente und in JavaScript als Objekt. Ihre Namen entsprechen den Feldern der Tool-Konfiguration in der API:
Das Response-Timeout eines Webhook-Tools beträgt 5 bis 300 Sekunden. Das eines Client-Tools beträgt 1 bis 120 Sekunden oder -1, um unbegrenzt zu warten. Dafür ist expects_response / expectsResponse erforderlich. follow_redirects / followRedirects benötigt eine Liste erlaubter Domains.
Tools an einen Agenten anhängen
Webhook- und Client-Tools werden eigenständig mit tools.create() erstellt und anhand ihrer ID an Agenten angehängt. So kann ein Tool von mehreren Agenten genutzt werden. System-Tools sind Teil der Agentenkonfiguration: build_config() / buildConfig() gibt den Eintrag für die integrierten Tools des Agenten zurück.
Das Feld prompt.tools des Agenten, das Tool-Konfigurationen inline enthält, ist veraltet. Es kann nicht
mit tool_ids kombiniert werden. Wenn eine Anfrage es enthält, werden die integrierten Tools des Agenten
durch die darin enthaltenen System-Tools ersetzt. Erstellen Sie Tools stattdessen mit tools.create() und hängen Sie sie anhand ihrer ID an.
Ein vorhandenes Tool bearbeiten
Tool.from_response() / Tool.fromResponse() lädt ein von tools.get() zurückgegebenes Tool. Felder, die der Builder nicht modelliert, sowie die von der API ausgefüllten Standardwerte bleiben erhalten. Beim Zurückspielen ändert sich daher nur, was Sie geändert haben. as_webhook(), as_client() und as_system() (in JavaScript asWebhook() usw.) liefern das typisierte Tool zur Bearbeitung oder None / undefined, wenn es sich um eine andere Art handelt.
Um eine Body-Eigenschaft zu ändern, lesen Sie das Body-Schema, setzen die Eigenschaft erneut und setzen den Body:
Tools in der Versionsverwaltung speichern
to_json_string() / toJSONString() schreibt das Tool im Wire-Format der API: snake_case-Schlüssel, auf jeder Ebene sortiert und mit Einrückung von 2 Leerzeichen. Es entspricht dem Format, das die CLI in ihrem Verzeichnis tool_configs/ speichert. Beide SDKs schreiben für dasselbe Tool bytegenau identische Dateien, sodass Diffs klein bleiben. Tool.from_json() / Tool.fromJSON() liest es wieder ein.
Ein typisches Setup entspricht dem für Workflows: Legen Sie die Dateien zunächst mit elevenlabs tools pull an, bearbeiten Sie sie direkt oder mit dem Builder, führen Sie bei jedem Pull Request Tool.from_json(file).build() / Tool.fromJSON(file).build() in CI aus und übertragen Sie sie beim Merge mit tools.update() oder elevenlabs tools push.
Validierung
Verkettete Aufrufe schlagen nicht eigenständig fehl. build(), build_config() / buildConfig(), to_json() / toJSON() und to_json_string() / toJSONString() prüfen das gesamte Tool und lösen einen einzelnen ToolValidationError aus. Dessen Liste issues enthält jedes Problem, jeweils mit einem code, einer message und dem path des betreffenden Teils, etwa body.reason.
Fehler umfassen:
- Einen URL-Platzhalter ohne Pfadparameter oder einen Pfadparameter ohne Platzhalter. Umgebungsvariablen-Templates wie
{{system__env_api_host}}sind keine Platzhalter. - Einen Literalwert ohne Wertequelle oder mit mehr als einer.
- Einen Body bei einem
GEToder keinen Body bei einemPOST,PUToderPATCH. - Derselben Parameternamen in mehr als einem von Pfad, Abfrage und Body.
omit()für eine erforderliche Eigenschaft,choices()für ein Schema, das kein String ist, oder eine Konstante, die nicht zum Typ des Schemas passt.- Ein Transfer-Tool ohne Ziele, ein Ziel der falschen Art oder ein SIP-URI-Ziel ohne SIP-REFER-Transfer.
- Eine Option, die nicht für die Tool-Art gilt, oder ein Timeout außerhalb seines Bereichs.
Tool-Arten, die neuer sind als Ihr SDK
Ein aus der API oder aus einer Datei geladenes Tool kann eine Art haben, die der Builder nicht bearbeiten kann, etwa ein MCP-Tool. Es wird mit der Art "other" geladen und durchläuft from_json() / fromJSON() sowie to_json_string() / toJSONString() unverändert. build() meldet es über on_warning / onWarning als Warnung.