Outils en code
Vue d’ensemble
Un outil est stocké sous forme de configuration, avec des schémas JSON imbriqués pour ses paramètres. Rédiger cette configuration à la main implique de maintenir les paramètres de chemin synchronisés avec l’URL, les listes required avec leurs propriétés, et d’attribuer à chaque paramètre exactement une source de valeur. Le générateur d’outils des SDK Python et JavaScript vous permet de décrire le même outil à l’aide d’appels de méthodes chaînés. Il produit ensuite la requête déjà acceptée par tools.create() et tools.update().
Utilisez-le pour :
- Définir des outils webhook, client et système dans du code, puis les examiner comme toute autre modification de code.
- Charger un outil, modifier un paramètre et le renvoyer sans affecter le reste de sa configuration.
- Stocker des outils au format JSON dans le contrôle de version et les valider dans votre intégration continue.
Le générateur s’exécute entièrement dans le SDK. Il n’appelle aucun nouveau point de terminaison API, et tout ce qu’il génère peut être ouvert et modifié dans le Dashboard.
Prérequis
- Python : le package
elevenlabs. Le générateur est importé depuiselevenlabs.agent_tools. - JavaScript : le package
@elevenlabs/elevenlabs-js. Le générateur est exporté depuis la racine du package.
Concevoir un outil webhook
Tool.webhook(name, description) initialise un outil webhook. Le nom et la description sont ceux que le LLM voit lorsqu’il décide d’appeler ou non l’outil. Cet exemple recherche une commande à partir du numéro fourni par l’appelant, envoie une clé API depuis les secrets du Workspace et stocke le statut de la commande dans une variable dynamique :
Les méthodes de requête définissent la méthode HTTP et l’URL. Les espaces réservés {name} dans l’URL sont renseignés à partir des paramètres de chemin :
Définir un paramètre ou un en-tête dont le nom existe déjà le remplace tout en conservant sa position. remove_path_param(), remove_query_param(), remove_header() et remove_assignment() (removePathParam() et ainsi de suite en JavaScript) en suppriment un. Les noms des paramètres doivent être uniques parmi les paramètres de chemin, de requête et de corps.
Un corps est un schéma d’objet construit propriété par propriété :
Schémas de paramètres
Schema construit les schémas de paramètres utilisés par les outils webhook et client. Chaque méthode renvoie un nouveau schéma et laisse inchangé celui sur lequel elle a été appelée. Vous pouvez donc définir un schéma une fois et l’utiliser dans plusieurs outils.
Origine d’une valeur
Chaque valeur littérale nécessite exactement une source de valeur, quel que soit son emplacement : dans un paramètre, dans un corps, dans un schéma de réponse ou dans un objet ou un tableau. Un objet ou un tableau peut également en avoir une, qui fournit alors la valeur entière.
Sur un objet ou un tableau, describe() documente le conteneur pour le LLM, et chaque propriété ou élément conserve sa propre source.
Autres méthodes de schéma
En-têtes et authentification
Une valeur d’en-tête provient de l’un de quatre emplacements. Utilisez un secret ou une variable d’environnement pour toute donnée sensible afin que la valeur n’apparaisse jamais dans la configuration de l’outil :
AuthConnection.id(id) utilise une connexion d’authentification du Workspace via son ID. AuthConnection.env_var(label) / AuthConnection.envVar(label) la sélectionne depuis une variable d’environnement, afin qu’une même configuration d’outil puisse utiliser une connexion différente dans chaque environnement.
Concevoir un outil client
Tool.client(name, description) initialise un outil client, qui s’exécute dans votre application plutôt que sur un serveur. Ajoutez ses paramètres avec param(name, schema). Définissez expects_response / expectsResponse lorsque l’agent doit attendre le résultat de votre application :
Concevoir un outil système
Les outils système sont intégrés à la plateforme. Chacun dispose de son propre constructeur sur SystemTool, qui accepte les paramètres de cet outil :
Les deux outils de transfert reçoivent leurs destinations depuis transfer(condition, destination, options). La condition indique au LLM quand effectuer le transfert, et la destination utilise le même Destination que les workflows en code. Un transfert vers un URI SIP nécessite un transfert SIP REFER :
Options des outils
Les paramètres communs à tous les types d’outils sont définis dans options(), sous forme d’arguments nommés en Python et d’objet en JavaScript. Leurs noms correspondent aux champs de la configuration de l’outil dans l’API :
Le délai d’attente de réponse d’un outil webhook est compris entre 5 et 300 secondes. Celui d’un outil client est compris entre 1 et 120 secondes, ou peut être défini sur -1 pour attendre aussi longtemps que nécessaire, ce qui requiert expects_response / expectsResponse. follow_redirects / followRedirects requiert une liste de domaines autorisés.
Associer des outils à un agent
Les outils webhook et client sont créés séparément avec tools.create() et associés aux agents par ID. Un même outil peut donc être partagé par plusieurs agents. Les outils système font partie de la configuration de l’agent : build_config() / buildConfig() renvoie l’entrée correspondant aux outils intégrés de l’agent.
Le champ prompt.tools de l’agent, qui contient les configurations d’outils intégrées, est obsolète. Il ne peut pas être
combiné avec tool_ids et, lorsqu’une requête l’inclut, les outils intégrés de l’agent sont remplacés
par les outils système qu’il contient. Créez plutôt les outils avec tools.create() et associez-les par ID.
Modifier un outil existant
Tool.from_response() / Tool.fromResponse() charge un outil renvoyé par tools.get(). Les champs que le générateur ne modélise pas, ainsi que les valeurs par défaut renseignées par l’API, sont conservés. Le renvoyer ne modifie donc que les éléments que vous avez changés. as_webhook(), as_client() et as_system() (asWebhook() et ainsi de suite en JavaScript) vous donnent l’outil typé à modifier, ou None / undefined s’il est d’un autre type.
Pour modifier une propriété du corps, lisez le schéma du corps, définissez de nouveau la propriété, puis définissez le corps :
Stocker des outils dans le contrôle de version
to_json_string() / toJSONString() écrit l’outil au format de transfert de l’API : clés en snake_case, triées à chaque niveau, avec une indentation de 2 espaces. Il s’agit de la même structure que conserve la CLI dans son répertoire tool_configs/, et les deux SDK écrivent des fichiers identiques octet par octet pour un même outil, afin de limiter les différences. Tool.from_json() / Tool.fromJSON() le relit.
Une configuration classique est identique à celle des workflows : initialisez les fichiers avec elevenlabs tools pull, modifiez-les directement ou avec le générateur, exécutez Tool.from_json(file).build() / Tool.fromJSON(file).build() dans l’intégration continue pour chaque pull request, puis envoyez-les avec tools.update() ou elevenlabs tools push lors de la fusion.
Validation
Les appels chaînés n’échouent jamais seuls. build(), build_config() / buildConfig(), to_json() / toJSON() et to_json_string() / toJSONString() vérifient l’ensemble de l’outil et lèvent ou déclenchent une seule ToolValidationError, dont la liste issues répertorie tous les problèmes, chacun avec un code, un message et le path de la partie concernée, par exemple body.reason.
Les erreurs incluent :
- Un espace réservé d’URL sans paramètre de chemin, ou un paramètre de chemin sans espace réservé. Les modèles de variables d’environnement tels que
{{system__env_api_host}}ne sont pas des espaces réservés. - Une valeur littérale sans source de valeur, ou avec plusieurs sources.
- Un corps sur un
GET, ou l’absence de corps sur unPOST,PUTouPATCH. - Le même nom de paramètre dans plusieurs emplacements parmi le chemin, la requête et le corps.
omit()sur une propriété obligatoire,choices()sur un schéma qui n’est pas une chaîne, ou une constante qui ne correspond pas au type du schéma.- Un outil de transfert sans destination, une destination du mauvais type, ou une destination URI SIP sans transfert SIP REFER.
- Une option qui ne s’applique pas à ce type d’outil, ou un délai d’attente hors de sa plage autorisée.
Types d’outils plus récents que votre SDK
Un outil chargé depuis l’API ou depuis un fichier peut être d’un type que le générateur ne peut pas modifier, comme un outil MCP. Il est chargé avec le type "other", reste inchangé lors des passages par from_json() / fromJSON() et to_json_string() / toJSONString(), et build() le signale comme avertissement via on_warning / onWarning.