Zur Navigation springen

Tools als Code

Agent-Tools mit den Python- und JavaScript-SDKs erstellen, bearbeiten und versionieren

Überblick

Ein Tool wird als Konfiguration mit verschachtelten JSON-Schemas für seine Parameter gespeichert. Wenn Sie diese Konfiguration von Hand schreiben, müssen Pfadparameter zur URL passen, required-Listen zu ihren Eigenschaften passen und jeder Parameter genau eine Wertequelle haben. Mit dem Tool-Builder in den Python- und JavaScript-SDKs beschreiben Sie dasselbe Tool mit verketteten Methodenaufrufen. Er erstellt dann die Anfrage, die tools.create() und tools.update() bereits akzeptieren.

Verwenden Sie ihn, um:

  • Webhook-, Client- und System-Tools im Code zu definieren und wie jede andere Codeänderung zu prüfen.
  • Ein Tool zu laden, einen Parameter zu ändern und es zurückzuspielen, ohne den Rest seiner Konfiguration zu verändern.
  • Tools als JSON in der Versionsverwaltung zu speichern und sie in CI zu validieren.

Der Builder läuft vollständig im SDK. Er ruft keine neuen API-Endpunkte auf, und alles, was er erstellt, kann im Dashboard geöffnet und bearbeitet werden.

Voraussetzungen

  • Python: das Paket elevenlabs. Der Builder wird aus elevenlabs.agent_tools importiert.
  • JavaScript: das Paket @elevenlabs/elevenlabs-js. Der Builder wird aus dem Paketstamm exportiert.

Ein Webhook-Tool erstellen

Tool.webhook(name, description) startet ein Webhook-Tool. Name und Beschreibung sieht das LLM, wenn es entscheidet, ob es das Tool aufrufen soll. Dieses Beispiel sucht eine Bestellung anhand der vom Anrufer angegebenen Nummer, sendet einen API-Schlüssel aus den Secrets des Workspace und speichert den Bestellstatus in einer dynamischen Variable:

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

Die Anfragemethoden legen HTTP-Methode und URL fest. {name}-Platzhalter in der URL werden aus Pfadparametern gefüllt:

PythonJavaScriptLegt fest
get(url), post(url), put(url), patch(url), delete(url)gleichMethode und URL. POST, PUT und PATCH benötigen einen Body; GET darf keinen haben.
path_param(name, schema)pathParam(name, schema)Einen Pfadparameter für den {name}-Platzhalter in der URL.
query_param(name, schema)queryParam(name, schema)Einen Abfrageparameter.
body(schema)body(schema)Den Anfrage-Body. Muss ein Objektschema sein.
response(schema)response(schema)Das Schema für den Response-Body. Muss ein Objektschema sein.
header(name, value)header(name, value)Einen Anfrage-Header. Siehe Header und Authentifizierung.
auth(connection)auth(connection)Die zu verwendende Auth-Verbindung.
assign(variable, path)assign(variable, path)Speichert den Wert unter path in der Response (Punktnotation) in einer dynamischen Variable.

Das Setzen eines Parameters oder Headers mit einem bereits vorhandenen Namen ersetzt ihn und behält seine Position bei. remove_path_param(), remove_query_param(), remove_header() und remove_assignment() (in JavaScript removePathParam() usw.) entfernen jeweils einen. Parameternamen müssen über Pfad, Abfrage und Body hinweg eindeutig sein.

Ein Body ist ein Objektschema, das Eigenschaft für Eigenschaft erstellt wird:

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

Parameterschemas

Schema erstellt die Parameterschemas, die Webhook- und Client-Tools verwenden. Jede Methode gibt ein neues Schema zurück und lässt das Schema, für das sie aufgerufen wurde, unverändert. So können Sie ein Schema einmal definieren und in mehreren Tools verwenden.

KonstruktorErstellt
Schema.string(), Schema.integer(), Schema.number(), Schema.bool()Einen Literalwert
Schema.object()Ein Objekt. Fügen Sie Eigenschaften mit property() hinzu.
Schema.array(items)Ein Array, dessen Elemente dem items-Schema entsprechen

Woher ein Wert kommt

Jeder Literalwert benötigt genau eine Wertequelle, unabhängig davon, wo er vorkommt: in einem Parameter, einem Body, einem Response-Schema oder innerhalb eines Objekts oder Arrays. Auch ein Objekt oder Array kann eine haben, die dann den gesamten Wert liefert.

PythonJavaScriptDer Wert
describe(text)describe(text)Wird vom LLM bereitgestellt, geleitet durch text.
from_variable(name)fromVariable(name)Wird beim Ausführen des Tools aus einer dynamischen Variable gelesen.
constant(value)constant(value)Ist immer value.
system_provided()systemProvided()Wird beim Ausführen des Tools vom System ausgefüllt. Nur Literalwerte.
omit()omit()Wird aus der Anfrage ausgelassen. Nur für eine optionale Eigenschaft.

Bei einem Objekt oder Array dokumentiert describe() den Container für das LLM, und jede Eigenschaft oder jedes Element hat weiterhin eine eigene Quelle.

Weitere Schemamethoden

PythonJavaScriptFunktion
optional()optional()Macht eine Eigenschaft optional. Eigenschaften sind erforderlich, sofern sie nicht als optional markiert sind.
choices(values)choices(values)Beschränkt einen String auf eine feste Auswahl von Werten, aus denen das LLM auswählt.
allowed_from(variable)allowedFrom(variable)Lehnt einen LLM-Wert ab, der nicht in der Liste einer dynamischen Variable enthalten ist. Benötigt describe().
property(name, schema) / without(name)property(name, schema) / without(name)Fügt eine Objekteigenschaft hinzu, ersetzt oder entfernt sie. Eine ersetzte Eigenschaft behält ihre Position.
require_any_of(names) / require_all_of(names)requireAnyOf(names) / requireAllOf(names)Erfordert mindestens eine oder alle Eigenschaften aus einer Gruppe optionaler Eigenschaften.

Header und Authentifizierung

Ein Header-Wert stammt aus einer von vier Quellen. Verwenden Sie für alles Sensible ein Secret oder eine Umgebungsvariable, damit der Wert nie in der Tool-Konfiguration erscheint:

KonstruktorDer Header-Wert ist
Header.value(text)Fester Text.
Header.secret(id)Ein Secret aus dem Secret Store des Workspace.
Header.variable(name)Eine dynamische Variable, die beim Ausführen des Tools gelesen wird.
Header.env_var(label) / Header.envVar(label)Eine Umgebungsvariable des Workspace, die für die aktuelle Umgebung aufgelöst wird.

AuthConnection.id(id) verwendet eine Auth-Verbindung aus dem Workspace anhand ihrer ID. AuthConnection.env_var(label) / AuthConnection.envVar(label) wählt sie aus einer Umgebungsvariable aus, sodass dieselbe Tool-Konfiguration in jeder Umgebung eine andere Verbindung verwenden kann.

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

Ein Client-Tool erstellen

Tool.client(name, description) startet ein Client-Tool, das in Ihrer Anwendung statt auf einem Server ausgeführt wird. Fügen Sie die Parameter mit param(name, schema) hinzu. Setzen Sie expects_response / expectsResponse, wenn der Agent auf das Ergebnis Ihrer Anwendung warten soll:

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

Ein System-Tool erstellen

System-Tools sind in die Plattform integriert. Jedes verfügt über einen eigenen Konstruktor in SystemTool, der die Einstellungen dieses Tools übernimmt:

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

Die beiden Transfer-Tools übernehmen ihre Ziele aus transfer(condition, destination, options). Die Bedingung teilt dem LLM mit, wann dorthin transferiert werden soll, und das Ziel verwendet dasselbe Destination wie Workflows als Code. Ein Transfer zu einer SIP-URI benötigt einen SIP-REFER-Transfer:

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

Tool-Optionen

Einstellungen, die für alle Tool-Arten gelten, stehen in options(): in Python als Keyword-Argumente und in JavaScript als Objekt. Ihre Namen entsprechen den Feldern der Tool-Konfiguration in der API:

Gilt fürPythonJavaScript
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, …
Webhook-Toolsexecution_mode, content_type, response_filter, follow_redirects, follow_redirects_allowed_domains, dynamic_variable_placeholdersexecutionMode, contentType, responseFilter, followRedirects, followRedirectsAllowedDomains, dynamicVariablePlaceholders
Client-Toolsexecution_mode, expects_response, dynamic_variable_placeholdersexecutionMode, expectsResponse, dynamicVariablePlaceholders

Das Response-Timeout eines Webhook-Tools beträgt 5 bis 300 Sekunden. Das eines Client-Tools beträgt 1 bis 120 Sekunden oder -1, um unbegrenzt zu warten. Dafür ist expects_response / expectsResponse erforderlich. follow_redirects / followRedirects benötigt eine Liste erlaubter Domains.

Tools an einen Agenten anhängen

Webhook- und Client-Tools werden eigenständig mit tools.create() erstellt und anhand ihrer ID an Agenten angehängt. So kann ein Tool von mehreren Agenten genutzt werden. System-Tools sind Teil der Agentenkonfiguration: build_config() / buildConfig() gibt den Eintrag für die integrierten Tools des Agenten zurück.

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

Das Feld prompt.tools des Agenten, das Tool-Konfigurationen inline enthält, ist veraltet. Es kann nicht mit tool_ids kombiniert werden. Wenn eine Anfrage es enthält, werden die integrierten Tools des Agenten durch die darin enthaltenen System-Tools ersetzt. Erstellen Sie Tools stattdessen mit tools.create() und hängen Sie sie anhand ihrer ID an.

Ein vorhandenes Tool bearbeiten

Tool.from_response() / Tool.fromResponse() lädt ein von tools.get() zurückgegebenes Tool. Felder, die der Builder nicht modelliert, sowie die von der API ausgefüllten Standardwerte bleiben erhalten. Beim Zurückspielen ändert sich daher nur, was Sie geändert haben. as_webhook(), as_client() und as_system() (in JavaScript asWebhook() usw.) liefern das typisierte Tool zur Bearbeitung oder None / undefined, wenn es sich um eine andere Art handelt.

Um eine Body-Eigenschaft zu ändern, lesen Sie das Body-Schema, setzen die Eigenschaft erneut und setzen den 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())

Tools in der Versionsverwaltung speichern

to_json_string() / toJSONString() schreibt das Tool im Wire-Format der API: snake_case-Schlüssel, auf jeder Ebene sortiert und mit Einrückung von 2 Leerzeichen. Es entspricht dem Format, das die CLI in ihrem Verzeichnis tool_configs/ speichert. Beide SDKs schreiben für dasselbe Tool bytegenau identische Dateien, sodass Diffs klein bleiben. Tool.from_json() / Tool.fromJSON() liest es wieder ein.

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

Ein typisches Setup entspricht dem für Workflows: Legen Sie die Dateien zunächst mit elevenlabs tools pull an, bearbeiten Sie sie direkt oder mit dem Builder, führen Sie bei jedem Pull Request Tool.from_json(file).build() / Tool.fromJSON(file).build() in CI aus und übertragen Sie sie beim Merge mit tools.update() oder elevenlabs tools push.

Validierung

Verkettete Aufrufe schlagen nicht eigenständig fehl. build(), build_config() / buildConfig(), to_json() / toJSON() und to_json_string() / toJSONString() prüfen das gesamte Tool und lösen einen einzelnen ToolValidationError aus. Dessen Liste issues enthält jedes Problem, jeweils mit einem code, einer message und dem path des betreffenden Teils, etwa 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)

Fehler umfassen:

  • Einen URL-Platzhalter ohne Pfadparameter oder einen Pfadparameter ohne Platzhalter. Umgebungsvariablen-Templates wie {{system__env_api_host}} sind keine Platzhalter.
  • Einen Literalwert ohne Wertequelle oder mit mehr als einer.
  • Einen Body bei einem GET oder keinen Body bei einem POST, PUT oder PATCH.
  • Derselben Parameternamen in mehr als einem von Pfad, Abfrage und Body.
  • omit() für eine erforderliche Eigenschaft, choices() für ein Schema, das kein String ist, oder eine Konstante, die nicht zum Typ des Schemas passt.
  • Ein Transfer-Tool ohne Ziele, ein Ziel der falschen Art oder ein SIP-URI-Ziel ohne SIP-REFER-Transfer.
  • Eine Option, die nicht für die Tool-Art gilt, oder ein Timeout außerhalb seines Bereichs.

Tool-Arten, die neuer sind als Ihr SDK

Ein aus der API oder aus einer Datei geladenes Tool kann eine Art haben, die der Builder nicht bearbeiten kann, etwa ein MCP-Tool. Es wird mit der Art "other" geladen und durchläuft from_json() / fromJSON() sowie to_json_string() / toJSONString() unverändert. build() meldet es über on_warning / onWarning als Warnung.