Passer à la navigation

Outils en code

Concevez, modifiez et versionnez les outils des agents avec les SDK Python et JavaScript

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é depuis elevenlabs.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 :

from elevenlabs import ElevenLabs
from elevenlabs.agent_tools import Header, Schema, Tool
elevenlabs = ElevenLabs()
get_order = (
Tool.webhook("get_order", "Look up an order by the number the caller gives")
.get("https://api.example.com/orders/{order_id}")
.path_param("order_id", Schema.string().describe("The order number, e.g. A-1042"))
.query_param("include", Schema.string().constant("items"))
.header("Authorization", Header.secret("sec_orders_api"))
.assign("order_status", "order.status")
.options(response_timeout_secs=10)
)
tool = elevenlabs.conversational_ai.tools.create(request=get_order.build())

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 :

PythonJavaScriptDéfinit
get(url), post(url), put(url), patch(url), delete(url)idemLa méthode et l’URL. POST, PUT et PATCH nécessitent un corps ; GET ne peut pas en avoir.
path_param(name, schema)pathParam(name, schema)Un paramètre de chemin, pour l’espace réservé {name} dans l’URL.
query_param(name, schema)queryParam(name, schema)Un paramètre de requête.
body(schema)body(schema)Le corps de la requête. Doit être un schéma d’objet.
response(schema)response(schema)Le schéma du corps de la réponse. Doit être un schéma d’objet.
header(name, value)header(name, value)Un en-tête de requête. Consultez En-têtes et authentification.
auth(connection)auth(connection)La connexion d’authentification à utiliser.
assign(variable, path)assign(variable, path)Stocke la valeur située à path dans la réponse (notation par points) dans une variable dynamique.

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é :

refund = (
Tool.webhook("issue_refund", "Refund an order the caller asked to return")
.post("https://api.example.com/refunds")
.body(
Schema.object()
.property("order_id", Schema.string().from_variable("order_id"))
.property(
"reason",
Schema.string().describe("Why the caller wants a refund").choices(["damaged", "late", "other"]),
)
.property("note", Schema.string().describe("Anything else the caller said").optional())
)
)

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.

ConstructeurConstruit
Schema.string(), Schema.integer(), Schema.number(), Schema.bool()Une valeur littérale
Schema.object()Un objet. Ajoutez des propriétés avec property().
Schema.array(items)Un tableau dont les éléments correspondent au schéma items

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.

PythonJavaScriptLa valeur
describe(text)describe(text)Est fournie par le LLM, guidé par text.
from_variable(name)fromVariable(name)Est lue depuis une variable dynamique lors de l’exécution de l’outil.
constant(value)constant(value)Est toujours value.
system_provided()systemProvided()Est renseignée par le système lors de l’exécution de l’outil. Valeurs littérales uniquement.
omit()omit()Est exclue de la requête. Uniquement pour une propriété facultative.

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

PythonJavaScriptFonction
optional()optional()Rend une propriété facultative. Les propriétés sont obligatoires sauf indication contraire.
choices(values)choices(values)Limite une chaîne à un ensemble fixe de valeurs parmi lesquelles le LLM choisit.
allowed_from(variable)allowedFrom(variable)Rejette une valeur de LLM absente de la liste contenue dans une variable dynamique. Nécessite describe().
property(name, schema) / without(name)property(name, schema) / without(name)Ajoute, remplace ou supprime une propriété d’objet. Une propriété remplacée conserve sa position.
require_any_of(names) / require_all_of(names)requireAnyOf(names) / requireAllOf(names)Exige au moins une, ou toutes, les propriétés facultatives d’un groupe.

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 :

ConstructeurLa valeur de l’en-tête est
Header.value(text)Du texte fixe.
Header.secret(id)Un secret du magasin de secrets du Workspace.
Header.variable(name)Une variable dynamique, lue lors de l’exécution de l’outil.
Header.env_var(label) / Header.envVar(label)Une variable d’environnement du Workspace, résolue pour l’environnement actuel.

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.

from elevenlabs.agent_tools import AuthConnection, Header
update_profile = (
Tool.webhook("update_profile", "Update the caller's email address")
.put("https://api.example.com/profiles/{profile_id}")
.path_param("profile_id", Schema.string().from_variable("profile_id"))
.body(Schema.object().property("email", Schema.string().describe("The new email address")))
.header("X-Api-Key", Header.env_var("profiles_api_key"))
.auth(AuthConnection.env_var("profiles_oauth"))
)

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 :

show_map = (
Tool.client("show_store_map", "Show the caller a map of the nearest store")
.param("store_id", Schema.string().describe("The store to show"))
.options(expects_response=False)
)

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 :

PythonJavaScript
SystemTool.end_call()SystemTool.endCall()
SystemTool.skip_turn(wait_timeout_secs=...)SystemTool.skipTurn({ waitTimeoutSecs })
SystemTool.language_detection(...)SystemTool.languageDetection(options?)
SystemTool.play_keypad_touch_tone(...)SystemTool.playKeypadTouchTone(options?)
SystemTool.voicemail_detection(voicemail_message=...)SystemTool.voicemailDetection({ voicemailMessage })
SystemTool.knowledge_base(enabled_strategies=...)SystemTool.knowledgeBase({ enabledStrategies })
SystemTool.transfer_to_number(...)SystemTool.transferToNumber(options?)
SystemTool.transfer_to_agent()SystemTool.transferToAgent()

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 :

from elevenlabs.agent_tools import SystemTool
from elevenlabs.agent_workflows import Destination
transfer = (
SystemTool.transfer_to_number()
.transfer("Caller asks for billing", Destination.phone("+15551234567"))
.transfer("Caller is a reseller partner", Destination.sip("sip:partners@pbx.example.com"), transfer_type="sip_refer")
)
to_sales = SystemTool.transfer_to_agent().transfer(
"Caller wants to buy something", Destination.agent("agent_sales"), transfer_message="Connecting you to sales"
)

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 :

S’applique àPythonJavaScript
Tous les outilsname, description, response_timeout_secs, interruption_mode, pre_tool_speech, tool_call_sound, tool_error_handling_mode, …name, description, responseTimeoutSecs, interruptionMode, preToolSpeech, toolCallSound, toolErrorHandlingMode, …
Outils webhookexecution_mode, content_type, response_filter, follow_redirects, follow_redirects_allowed_domains, dynamic_variable_placeholdersexecutionMode, contentType, responseFilter, followRedirects, followRedirectsAllowedDomains, dynamicVariablePlaceholders
Outils clientexecution_mode, expects_response, dynamic_variable_placeholdersexecutionMode, expectsResponse, dynamicVariablePlaceholders

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.

from elevenlabs import AgentConfig, BuiltInToolsOutput, ConversationalConfig, PromptAgentApiModelOutput
order_tool = elevenlabs.conversational_ai.tools.create(request=get_order.build())
agent = elevenlabs.conversational_ai.agents.create(
name="Support line",
conversation_config=ConversationalConfig(
agent=AgentConfig(
prompt=PromptAgentApiModelOutput(
prompt="You are a support agent for Acme.",
tool_ids=[order_tool.id],
built_in_tools=BuiltInToolsOutput(
end_call=SystemTool.end_call().build_config(),
transfer_to_number=transfer.build_config(),
),
)
)
),
)

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 :

from elevenlabs.agent_tools import ObjectSchema
loaded = Tool.from_response(elevenlabs.conversational_ai.tools.get("tool_id")).as_webhook()
if loaded is None:
raise ValueError("Not a webhook tool")
body = loaded.body_schema
assert isinstance(body, ObjectSchema)
loaded.body(body.property("reason", Schema.string().describe("Why the caller wants a refund")))
loaded.query_param("locale", Schema.string().describe("The caller's language").optional())
elevenlabs.conversational_ai.tools.update("tool_id", request=loaded.build())

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.

from pathlib import Path
from elevenlabs.agent_tools import Tool
Path("tool_configs/get_order.json").write_text(get_order.to_json_string())
stored = Tool.from_json(Path("tool_configs/get_order.json").read_text())
elevenlabs.conversational_ai.tools.update("tool_id", request=stored.build())

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.

from elevenlabs.agent_tools import ToolValidationError
try:
request = refund.build()
except ToolValidationError as err:
for issue in err.issues:
print(issue.code, issue.path, issue.message)

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 un POST, PUT ou PATCH.
  • 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.