Strumenti come codice
Panoramica
Uno strumento viene memorizzato come configurazione con schemi JSON annidati per i relativi parametri. Scrivere questa configurazione manualmente significa dover mantenere i parametri del path allineati con l’URL, gli elenchi required allineati con le relative proprietà e assegnare a ogni parametro esattamente una fonte del valore. Il builder di strumenti negli SDK Python e JavaScript ti consente di descrivere lo stesso strumento con chiamate di metodi concatenate. Genera quindi la richiesta già accettata da tools.create() e tools.update().
Usalo per:
- Definire strumenti webhook, client e di sistema nel codice e revisionarli come qualsiasi altra modifica al codice.
- Caricare uno strumento, modificare un parametro e inviarlo di nuovo senza alterare il resto della configurazione.
- Archiviare gli strumenti come JSON nel controllo versione e convalidarli in CI.
Il builder viene eseguito interamente nell’SDK. Non chiama nuovi endpoint API e tutto ciò che crea può essere aperto e modificato nella dashboard.
Requisiti
- Python: il pacchetto
elevenlabs. Il builder viene importato daelevenlabs.agent_tools. - JavaScript: il pacchetto
@elevenlabs/elevenlabs-js. Il builder viene esportato dalla root del pacchetto.
Crea uno strumento webhook
Tool.webhook(name, description) avvia uno strumento webhook. Il nome e la descrizione sono ciò che l’LLM vede quando decide se chiamare lo strumento. Questo esempio cerca un ordine in base al numero fornito dal chiamante, invia una chiave API dai segreti del workspace e memorizza lo stato dell’ordine in una variabile dinamica:
I metodi della richiesta impostano il metodo HTTP e l’URL. I placeholder {name} nell’URL vengono compilati dai parametri del path:
L’impostazione di un parametro o di un header con un nome già esistente lo sostituisce e ne mantiene la posizione. remove_path_param(), remove_query_param(), remove_header() e remove_assignment() (removePathParam() e così via in JavaScript) ne rimuovono uno. I nomi dei parametri devono essere univoci tra path, query e body.
Un body è uno schema oggetto creato proprietà per proprietà:
Schemi dei parametri
Schema crea gli schemi dei parametri usati dagli strumenti webhook e client. Ogni metodo restituisce un nuovo schema e lascia invariato quello su cui è stato chiamato, quindi puoi definire uno schema una volta e usarlo in più strumenti.
Origine di un valore
Ogni valore letterale richiede esattamente una fonte del valore, ovunque compaia: in un parametro, in un body, in uno schema di risposta o all’interno di un oggetto o di un array. Anche un oggetto o un array può averne una, che fornisce quindi l’intero valore.
Su un oggetto o un array, describe() documenta il contenitore per l’LLM e ogni proprietà o elemento mantiene la propria fonte.
Altri metodi dello schema
Header e autenticazione
Il valore di un header proviene da uno di quattro punti. Usa un segreto o una variabile d’ambiente per qualsiasi dato sensibile, in modo che il valore non compaia mai nella configurazione dello strumento:
AuthConnection.id(id) usa una connessione di autenticazione del workspace tramite ID. AuthConnection.env_var(label) / AuthConnection.envVar(label) la seleziona da una variabile d’ambiente, così la stessa configurazione dello strumento può usare una connessione diversa in ogni ambiente.
Crea uno strumento client
Tool.client(name, description) avvia uno strumento client, che viene eseguito nella tua applicazione anziché su un server. Aggiungi i relativi parametri con param(name, schema). Imposta expects_response / expectsResponse quando l’agente deve attendere il risultato della tua applicazione:
Crea uno strumento di sistema
Gli strumenti di sistema sono integrati nella piattaforma. Ognuno ha il proprio costruttore in SystemTool, che accetta le impostazioni dello strumento:
I due strumenti di trasferimento ricevono le destinazioni da transfer(condition, destination, options). La condizione indica all’LLM quando effettuare il trasferimento e la destinazione usa lo stesso Destination dei workflow come codice. Un trasferimento a un URI SIP richiede un trasferimento SIP REFER:
Opzioni dello strumento
Le impostazioni condivise da ogni tipo di strumento vanno in options(), come argomenti con nome in Python e come oggetto in JavaScript. I loro nomi corrispondono ai campi della configurazione dello strumento nell’API:
Il timeout della risposta di uno strumento webhook va da 5 a 300 secondi. Quello di uno strumento client va da 1 a 120 secondi, oppure è -1 per attendere il tempo necessario, opzione che richiede expects_response / expectsResponse. follow_redirects / followRedirects richiede un elenco di domini consentiti.
Collega strumenti a un agente
Gli strumenti webhook e client vengono creati separatamente con tools.create() e collegati agli agenti tramite ID, così uno strumento può essere condiviso da più agenti. Gli strumenti di sistema fanno parte della configurazione dell’agente: build_config() / buildConfig() restituisce la voce per gli strumenti integrati dell’agente.
Il campo prompt.tools dell’agente, che contiene le configurazioni degli strumenti inline, è deprecato. Non può essere
combinato con tool_ids e, quando una richiesta lo include, gli strumenti integrati dell’agente vengono sostituiti
dagli strumenti di sistema che contiene. Crea invece gli strumenti con tools.create() e collegali tramite ID.
Modifica uno strumento esistente
Tool.from_response() / Tool.fromResponse() carica uno strumento restituito da tools.get(). I campi che il builder non modella e i valori predefiniti compilati dall’API vengono mantenuti, quindi reinviarlo modifica solo ciò che hai cambiato. as_webhook(), as_client() e as_system() (asWebhook() e così via in JavaScript) restituiscono lo strumento tipizzato da modificare, oppure None / undefined se è di un altro tipo.
Per modificare una proprietà del body, leggi lo schema del body, imposta nuovamente la proprietà e imposta il body:
Archivia gli strumenti nel controllo versione
to_json_string() / toJSONString() scrive lo strumento nel wire format dell’API: chiavi in snake_case, ordinate a ogni livello, con rientro di 2 spazi. È lo stesso formato che la CLI conserva nella directory tool_configs/ e, per lo stesso strumento, entrambi gli SDK scrivono file identici byte per byte, così le differenze rimangono limitate. Tool.from_json() / Tool.fromJSON() lo legge nuovamente.
Una configurazione tipica è uguale a quella dei workflow: inizializza i file con elevenlabs tools pull, modificali direttamente o con il builder, esegui Tool.from_json(file).build() / Tool.fromJSON(file).build() in CI a ogni pull request e inviali con tools.update() o elevenlabs tools push al merge.
Convalida
Le chiamate concatenate non generano mai errori da sole. build(), build_config() / buildConfig(), to_json() / toJSON() e to_json_string() / toJSONString() controllano l’intero strumento e sollevano o lanciano un singolo ToolValidationError, il cui elenco issues raccoglie ogni problema, ciascuno con un code, un message e il path della parte interessata, ad esempio body.reason.
Gli errori includono:
- Un placeholder URL senza parametro del path o un parametro del path senza placeholder. I template delle variabili d’ambiente come
{{system__env_api_host}}non sono placeholder. - Un valore letterale senza una fonte del valore o con più di una.
- Un body in una
GEToppure nessun body in unaPOST,PUToPATCH. - Lo stesso nome di parametro in più di uno tra path, query e body.
omit()su una proprietà obbligatoria,choices()su uno schema che non è una stringa o una costante che non corrisponde al tipo dello schema.- Uno strumento di trasferimento senza destinazioni, una destinazione del tipo errato o una destinazione URI SIP senza trasferimento SIP REFER.
- Un’opzione che non si applica al tipo di strumento o un timeout fuori dall’intervallo consentito.
Tipi di strumenti più recenti del tuo SDK
Uno strumento caricato dall’API o da un file può essere di un tipo che il builder non può modificare, ad esempio uno strumento MCP. Viene caricato con il tipo "other" e passa invariato attraverso from_json() / fromJSON() e to_json_string() / toJSONString(), mentre build() lo segnala come avviso tramite on_warning / onWarning.