Vai alla navigazione

Strumenti come codice

Crea, modifica e versiona gli strumenti degli agenti con gli SDK Python e JavaScript

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 da elevenlabs.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:

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())

I metodi della richiesta impostano il metodo HTTP e l’URL. I placeholder {name} nell’URL vengono compilati dai parametri del path:

PythonJavaScriptImposta
get(url), post(url), put(url), patch(url), delete(url)stessoIl metodo e l’URL. POST, PUT e PATCH richiedono un body; GET non può averne uno.
path_param(name, schema)pathParam(name, schema)Un parametro del path, per il placeholder {name} nell’URL.
query_param(name, schema)queryParam(name, schema)Un parametro query.
body(schema)body(schema)Il body della richiesta. Deve essere uno schema oggetto.
response(schema)response(schema)Lo schema del body della risposta. Deve essere uno schema oggetto.
header(name, value)header(name, value)Un header della richiesta. Vedi Header e autenticazione.
auth(connection)auth(connection)La connessione di autenticazione da usare.
assign(variable, path)assign(variable, path)Memorizza in una variabile dinamica il valore in corrispondenza di path nella risposta (notazione con punti).

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

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())
)
)

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.

CostruttoreCrea
Schema.string(), Schema.integer(), Schema.number(), Schema.bool()Un valore letterale
Schema.object()Un oggetto. Aggiungi proprietà con property().
Schema.array(items)Un array i cui elementi corrispondono allo schema items

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.

PythonJavaScriptIl valore
describe(text)describe(text)Viene fornito dall’LLM, guidato da text.
from_variable(name)fromVariable(name)Viene letto da una variabile dinamica quando lo strumento viene eseguito.
constant(value)constant(value)È sempre value.
system_provided()systemProvided()Viene compilato dal sistema quando lo strumento viene eseguito. Solo valori letterali.
omit()omit()Viene escluso dalla richiesta. Solo per una proprietà facoltativa.

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

PythonJavaScriptFunzione
optional()optional()Rende facoltativa una proprietà. Le proprietà sono obbligatorie se non sono contrassegnate come facoltative.
choices(values)choices(values)Limita una stringa a un set fisso di valori, tra cui l’LLM sceglie.
allowed_from(variable)allowedFrom(variable)Rifiuta un valore dell’LLM che non è nell’elenco contenuto in una variabile dinamica. Richiede describe().
property(name, schema) / without(name)property(name, schema) / without(name)Aggiunge, sostituisce o rimuove una proprietà dell’oggetto. Una proprietà sostituita mantiene la posizione.
require_any_of(names) / require_all_of(names)requireAnyOf(names) / requireAllOf(names)Richiede almeno una o tutte le proprietà facoltative di un gruppo.

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:

CostruttoreIl valore dell’header è
Header.value(text)Testo fisso.
Header.secret(id)Un segreto dall’archivio dei segreti del workspace.
Header.variable(name)Una variabile dinamica, letta quando lo strumento viene eseguito.
Header.env_var(label) / Header.envVar(label)Una variabile d’ambiente del workspace, risolta per l’ambiente corrente.

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.

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"))
)

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:

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)
)

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:

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()

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:

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"
)

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:

Si applica aPythonJavaScript
Tutti gli strumentiname, description, response_timeout_secs, interruption_mode, pre_tool_speech, tool_call_sound, tool_error_handling_mode, …name, description, responseTimeoutSecs, interruptionMode, preToolSpeech, toolCallSound, toolErrorHandlingMode, …
Strumenti webhookexecution_mode, content_type, response_filter, follow_redirects, follow_redirects_allowed_domains, dynamic_variable_placeholdersexecutionMode, contentType, responseFilter, followRedirects, followRedirectsAllowedDomains, dynamicVariablePlaceholders
Strumenti clientexecution_mode, expects_response, dynamic_variable_placeholdersexecutionMode, expectsResponse, dynamicVariablePlaceholders

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.

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(),
),
)
)
),
)

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:

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())

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.

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())

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.

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)

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 GET oppure nessun body in una POST, PUT o PATCH.
  • 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.