Naar navigatie springen

Tools als code

Bouw, bewerk en versiebeheer agenttools met de Python- en JavaScript-SDK’s

Overzicht

Een tool wordt opgeslagen als een configuratie met geneste JSON-schema’s voor de parameters. Als je die configuratie handmatig schrijft, moet je padparameters laten overeenkomen met de URL, required-lijsten met de bijbehorende eigenschappen en elke parameter precies één waardebron geven. Met de toolbuilder in de Python- en JavaScript-SDK’s kun je dezelfde tool beschrijven met gekoppelde method calls. Vervolgens produceert deze de request die tools.create() en tools.update() al accepteren.

Gebruik deze om:

  • Webhook-, client- en systeemtools in code te definiëren en ze te beoordelen zoals elke andere codewijziging.
  • Een tool te laden, één parameter te wijzigen en deze terug te sturen zonder de rest van de configuratie te verstoren.
  • Tools als JSON in versiebeheer op te slaan en ze in CI te valideren.

De builder draait volledig in de SDK. Hij roept geen nieuwe API-endpoints aan en alles wat hij bouwt, kan in het dashboard worden geopend en bewerkt.

Vereisten

  • Python: het pakket elevenlabs. De builder wordt geïmporteerd vanuit elevenlabs.agent_tools.
  • JavaScript: het pakket @elevenlabs/elevenlabs-js. De builder wordt geëxporteerd vanuit de pakketroot.

Een webhooktool bouwen

Tool.webhook(name, description) start een webhooktool. De naam en beschrijving ziet de LLM wanneer die beslist of de tool wordt aangeroepen. Dit voorbeeld zoekt een bestelling op aan de hand van het nummer dat de beller opgeeft, stuurt een API-sleutel vanuit de secrets van de workspace en slaat de status van de bestelling op in een dynamische variabele:

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

De requestmethoden stellen de HTTP-methode en URL in. Tijdelijke aanduidingen {name} in de URL worden ingevuld vanuit padparameters:

PythonJavaScriptStelt in
get(url), post(url), put(url), patch(url), delete(url)sameDe methode en URL. POST, PUT en PATCH hebben een body nodig; GET kan er geen hebben.
path_param(name, schema)pathParam(name, schema)Een padparameter voor de tijdelijke aanduiding {name} in de URL.
query_param(name, schema)queryParam(name, schema)Een queryparameter.
body(schema)body(schema)De requestbody. Moet een objectschema zijn.
response(schema)response(schema)Het schema van de responsebody. Moet een objectschema zijn.
header(name, value)header(name, value)Een requestheader. Zie Headers en authenticatie.
auth(connection)auth(connection)De te gebruiken auth-verbinding.
assign(variable, path)assign(variable, path)Slaat de waarde bij path in de response (puntnotatie) op in een dynamische variabele.

Als je een parameter of header instelt waarvan de naam al bestaat, wordt die vervangen en behoudt deze zijn positie. Met remove_path_param(), remove_query_param(), remove_header() en remove_assignment() (in JavaScript removePathParam() enzovoort) verwijder je er één. Parameternamen moeten uniek zijn voor pad, query en body.

Een body is een objectschema dat eigenschap voor eigenschap wordt opgebouwd:

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

Parameterschema’s

Schema bouwt de parameterschema’s die webhook- en clienttools gebruiken. Elke methode retourneert een nieuw schema en laat het schema waarop deze is aangeroepen ongewijzigd, zodat je een schema één keer kunt definiëren en in meerdere tools kunt gebruiken.

ConstructorBouwt
Schema.string(), Schema.integer(), Schema.number(), Schema.bool()Een letterlijke waarde
Schema.object()Een object. Voeg eigenschappen toe met property().
Schema.array(items)Een array waarvan de elementen overeenkomen met het schema items

Waar een waarde vandaan komt

Elke letterlijke waarde heeft precies één waardebron nodig, ongeacht waar deze voorkomt: in een parameter, in een body, in een responseschema of binnen een object of array. Een object of array kan er ook één hebben, die dan de volledige waarde levert.

PythonJavaScriptDe waarde
describe(text)describe(text)Wordt geleverd door de LLM, aangestuurd door text.
from_variable(name)fromVariable(name)Wordt uit een dynamische variabele gelezen wanneer de tool draait.
constant(value)constant(value)Is altijd value.
system_provided()systemProvided()Wordt door het systeem ingevuld wanneer de tool draait. Alleen letterlijke waarden.
omit()omit()Wordt weggelaten uit de request. Alleen voor een optionele eigenschap.

Voor een object of array documenteert describe() de container voor de LLM en heeft elke eigenschap of elk element nog steeds een eigen bron.

Andere schemamethoden

PythonJavaScriptDoet
optional()optional()Maakt een eigenschap optioneel. Eigenschappen zijn verplicht, tenzij ze als optioneel zijn gemarkeerd.
choices(values)choices(values)Beperkt een string tot een vaste set waarden waaruit de LLM kiest.
allowed_from(variable)allowedFrom(variable)Wijst een LLM-waarde af die niet in de lijst staat die door een dynamische variabele wordt bijgehouden. Vereist describe().
property(name, schema) / without(name)property(name, schema) / without(name)Voegt een objecteigenschap toe, vervangt deze of verwijdert deze. Een vervangen eigenschap behoudt zijn positie.
require_any_of(names) / require_all_of(names)requireAnyOf(names) / requireAllOf(names)Vereist minstens één of alle eigenschappen uit een groep optionele eigenschappen.

Headers en authenticatie

Een headerwaarde komt uit een van vier bronnen. Gebruik voor gevoelige gegevens een secret of omgevingsvariabele, zodat de waarde nooit in de toolconfiguratie verschijnt:

ConstructorDe headerwaarde is
Header.value(text)Vaste tekst.
Header.secret(id)Een secret uit de secretstore van de workspace.
Header.variable(name)Een dynamische variabele, gelezen wanneer de tool draait.
Header.env_var(label) / Header.envVar(label)Een omgevingsvariabele van de workspace, opgelost voor de huidige omgeving.

AuthConnection.id(id) gebruikt een auth-verbinding uit de workspace op basis van ID. AuthConnection.env_var(label) / AuthConnection.envVar(label) kiest deze uit een omgevingsvariabele, zodat dezelfde toolconfiguratie in elke omgeving een andere verbinding kan gebruiken.

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

Een clienttool bouwen

Tool.client(name, description) start een clienttool, die in je applicatie draait in plaats van op een server. Voeg parameters toe met param(name, schema). Stel expects_response / expectsResponse in wanneer de agent moet wachten op het resultaat van je applicatie:

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

Een systeemtool bouwen

Systeemtools zijn ingebouwd in het platform. Elke tool heeft een eigen constructor op SystemTool, die de instellingen van die tool accepteert:

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

De twee transfertools halen hun bestemmingen uit transfer(condition, destination, options). De voorwaarde vertelt de LLM wanneer deze daarnaartoe moet transfereren en de bestemming gebruikt dezelfde Destination als workflows als code. Voor een transfer naar een SIP-URI is een SIP REFER-transfer nodig:

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

Toolopties

Instellingen die alle soorten tools delen, plaats je in options(): als keyword arguments in Python en als object in JavaScript. De namen komen overeen met de velden van de toolconfiguratie in de API:

Van toepassing opPythonJavaScript
Alle toolsname, description, response_timeout_secs, interruption_mode, pre_tool_speech, tool_call_sound, tool_error_handling_mode, …name, description, responseTimeoutSecs, interruptionMode, preToolSpeech, toolCallSound, toolErrorHandlingMode, …
Webhooktoolsexecution_mode, content_type, response_filter, follow_redirects, follow_redirects_allowed_domains, dynamic_variable_placeholdersexecutionMode, contentType, responseFilter, followRedirects, followRedirectsAllowedDomains, dynamicVariablePlaceholders
Clienttoolsexecution_mode, expects_response, dynamic_variable_placeholdersexecutionMode, expectsResponse, dynamicVariablePlaceholders

De responsetime-out van een webhooktool is 5 tot 300 seconden. Die van een clienttool is 1 tot 120 seconden, of -1 om zo lang als nodig te wachten; daarvoor is expects_response / expectsResponse vereist. Voor follow_redirects / followRedirects is een lijst met toegestane domeinen vereist.

Tools aan een agent koppelen

Webhook- en clienttools worden afzonderlijk gemaakt met tools.create() en via ID aan agents gekoppeld, zodat één tool door meerdere agents kan worden gedeeld. Systeemtools maken deel uit van de configuratie van de agent: build_config() / buildConfig() retourneert de invoer voor de ingebouwde tools van de 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(),
),
)
)
),
)

Het veld prompt.tools van de agent, waarin toolconfiguraties inline worden opgeslagen, is verouderd. Het kan niet worden gecombineerd met tool_ids, en wanneer een request het bevat, worden de ingebouwde tools van de agent vervangen door de systeemtools die het bevat. Maak tools met tools.create() en koppel ze in plaats daarvan via ID.

Een bestaande tool bewerken

Tool.from_response() / Tool.fromResponse() laadt een tool die wordt geretourneerd door tools.get(). Velden die de builder niet modelleert en de standaardwaarden die de API invult, blijven behouden, dus terugsturen wijzigt alleen wat je hebt gewijzigd. as_webhook(), as_client() en as_system() (in JavaScript asWebhook() enzovoort) geven je de getypeerde tool om te bewerken, of None / undefined als het een ander soort tool is.

Om een body-eigenschap te wijzigen, lees je het bodyschema, stel je de eigenschap opnieuw in en stel je de body in:

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

Tools opslaan in versiebeheer

to_json_string() / toJSONString() schrijft de tool in het wireformat van de API: snake_case-sleutels, gesorteerd op elk niveau, met inspringing van 2 spaties. Het heeft dezelfde structuur als de CLI bewaart in de directory tool_configs/, en beide SDK’s schrijven voor dezelfde tool byte voor byte identieke bestanden, zodat diffs klein blijven. Tool.from_json() / Tool.fromJSON() leest het weer in.

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

Een gebruikelijke opzet is dezelfde als voor workflows: vul de bestanden eerst met elevenlabs tools pull, bewerk ze rechtstreeks of met de builder, voer Tool.from_json(file).build() / Tool.fromJSON(file).build() uit in CI voor elke pull request en push ze bij een merge met tools.update() of elevenlabs tools push.

Validatie

Gekoppelde calls mislukken nooit op zichzelf. build(), build_config() / buildConfig(), to_json() / toJSON() en to_json_string() / toJSONString() controleren de volledige tool en geven of werpen één ToolValidationError waarvan de lijst issues elk probleem bevat, met telkens een code, een message en het path van het betreffende onderdeel, zoals 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)

Fouten omvatten:

  • Een tijdelijke aanduiding in een URL zonder padparameter, of een padparameter zonder tijdelijke aanduiding. Templates voor omgevingsvariabelen zoals {{system__env_api_host}} zijn geen tijdelijke aanduidingen.
  • Een letterlijke waarde zonder waardebron, of met meer dan één bron.
  • Een body bij een GET, of geen body bij een POST, PUT of PATCH.
  • Dezelfde parameternaam in meer dan één van pad, query en body.
  • omit() bij een verplichte eigenschap, choices() bij een schema dat geen string is, of een constante die niet overeenkomt met het type van het schema.
  • Een transfertool zonder bestemmingen, een bestemming van het verkeerde type of een SIP-URI-bestemming zonder SIP REFER-transfer.
  • Een optie die niet van toepassing is op het soort tool, of een time-out buiten het toegestane bereik.

Tooltypen die nieuwer zijn dan je SDK

Een tool die uit de API of uit een bestand is geladen, kan een type hebben dat de builder niet kan bewerken, zoals een MCP-tool. Deze wordt geladen met het type "other" en gaat ongewijzigd heen en terug via from_json() / fromJSON() en to_json_string() / toJSONString(). build() rapporteert deze als waarschuwing via on_warning / onWarning.