Przejdź do nawigacji

Narzędzia jako kod

Twórz, edytuj i wersjonuj narzędzia agentów za pomocą SDK dla Pythona i JavaScriptu

Omówienie

Tool jest przechowywany jako konfiguracja z zagnieżdżonymi schematami JSON parametrów. Ręczne pisanie tej konfiguracji wymaga synchronizacji parametrów ścieżki z URL-em, list required z ich właściwościami oraz przypisania każdemu parametrowi dokładnie jednego źródła wartości. Kreator narzędzi w SDK dla Pythona i JavaScriptu pozwala opisać to samo narzędzie za pomocą łańcuchowych wywołań metod. Następnie tworzy żądanie, które akceptują już tools.create() i tools.update().

Użyj go, aby:

  • Definiować narzędzia webhook, klienckie i systemowe w kodzie oraz przeglądać je jak każdą inną zmianę w kodzie.
  • Wczytać narzędzie, zmienić jeden parametr i odesłać je bez naruszania reszty konfiguracji.
  • Zapisywać narzędzia jako JSON w kontroli wersji i walidować je w CI.

Kreator działa całkowicie w SDK. Nie wywołuje nowych endpointów API, a wszystko, co utworzy, można otworzyć i edytować w panelu.

Wymagania

  • Python: pakiet elevenlabs. Kreator importuje się z elevenlabs.agent_tools.
  • JavaScript: pakiet @elevenlabs/elevenlabs-js. Kreator jest eksportowany z głównego modułu pakietu.

Tworzenie narzędzia webhook

Tool.webhook(name, description) tworzy narzędzie webhook. Nazwa i opis to informacje, które widzi LLM, gdy decyduje, czy wywołać narzędzie. Ten przykład wyszukuje zamówienie po numerze podanym przez rozmówcę, wysyła klucz API z sekretów workspace’u i zapisuje status zamówienia w zmiennej dynamicznej:

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

Metody żądań ustawiają metodę HTTP i URL. Symbole zastępcze {name} w URL-u są uzupełniane parametrami ścieżki:

PythonJavaScriptUstawia
get(url), post(url), put(url), patch(url), delete(url)sameMetodę i URL. POST, PUT oraz PATCH wymagają treści żądania; GET nie może jej mieć.
path_param(name, schema)pathParam(name, schema)Parametr ścieżki dla symbolu zastępczego {name} w URL-u.
query_param(name, schema)queryParam(name, schema)Parametr zapytania.
body(schema)body(schema)Treść żądania. Musi być schematem obiektu.
response(schema)response(schema)Schemat treści odpowiedzi. Musi być schematem obiektu.
header(name, value)header(name, value)Nagłówek żądania. Zobacz Nagłówki i uwierzytelnianie.
auth(connection)auth(connection)Połączenie uwierzytelniające, którego należy użyć.
assign(variable, path)assign(variable, path)Zapisuje wartość z path w odpowiedzi (notacja kropkowa) w zmiennej dynamicznej.

Ustawienie parametru lub nagłówka o istniejącej nazwie zastępuje go i zachowuje jego pozycję. remove_path_param(), remove_query_param(), remove_header() i remove_assignment() (w JavaScripcie removePathParam() itd.) usuwają element. Nazwy parametrów muszą być unikalne dla ścieżki, zapytania i treści.

Treść żądania to schemat obiektu budowany właściwość po właściwości:

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

Schematy parametrów

Schema tworzy schematy parametrów używane przez narzędzia webhook i klienckie. Każda metoda zwraca nowy schemat i nie zmienia tego, na którym została wywołana, więc możesz raz zdefiniować schemat i użyć go w kilku narzędziach.

KonstruktorTworzy
Schema.string(), Schema.integer(), Schema.number(), Schema.bool()Wartość literalną
Schema.object()Obiekt. Dodaj właściwości przez property().
Schema.array(items)Tablicę, której elementy pasują do schematu items

Źródło wartości

Każda wartość literalna potrzebuje dokładnie jednego źródła, niezależnie od tego, gdzie się znajduje: w parametrze, treści żądania, schemacie odpowiedzi albo wewnątrz obiektu czy tablicy. Obiekt lub tablica też mogą je mieć, co zapewnia wtedy całą wartość.

PythonJavaScriptWartość
describe(text)describe(text)Jest podawana przez LLM zgodnie z wskazówką text.
from_variable(name)fromVariable(name)Jest odczytywana ze zmiennej dynamicznej podczas działania narzędzia.
constant(value)constant(value)Zawsze wynosi value.
system_provided()systemProvided()Jest uzupełniana przez system podczas działania narzędzia. Tylko wartości literalne.
omit()omit()Jest pomijana w żądaniu. Tylko dla opcjonalnej właściwości.

W przypadku obiektu lub tablicy describe() dokumentuje kontener dla LLM, a każda właściwość lub element nadal ma własne źródło.

Inne metody schematu

PythonJavaScriptDziałanie
optional()optional()Czyni właściwość opcjonalną. Właściwości są wymagane, chyba że oznaczysz je jako opcjonalne.
choices(values)choices(values)Ogranicza tekst do ustalonego zestawu wartości, z których wybiera LLM.
allowed_from(variable)allowedFrom(variable)Odrzuca wartość LLM, której nie ma na liście przechowywanej przez zmienną dynamiczną. Wymaga describe().
property(name, schema) / without(name)property(name, schema) / without(name)Dodaje, zastępuje lub usuwa właściwość obiektu. Zastąpiona właściwość zachowuje pozycję.
require_any_of(names) / require_all_of(names)requireAnyOf(names) / requireAllOf(names)Wymaga co najmniej jednej lub wszystkich opcjonalnych właściwości z grupy.

Nagłówki i uwierzytelnianie

Wartość nagłówka może pochodzić z jednego z czterech miejsc. Do danych wrażliwych używaj sekretu lub zmiennej środowiskowej, aby wartość nigdy nie pojawiła się w konfiguracji narzędzia:

KonstruktorWartość nagłówka
Header.value(text)Stały tekst.
Header.secret(id)Sekret z magazynu sekretów workspace’u.
Header.variable(name)Zmienna dynamiczna, odczytywana podczas działania narzędzia.
Header.env_var(label) / Header.envVar(label)Zmienna środowiskowa workspace’u, rozwiązywana dla bieżącego środowiska.

AuthConnection.id(id) używa połączenia uwierzytelniającego z workspace’u według ID. AuthConnection.env_var(label) / AuthConnection.envVar(label) wybiera je ze zmiennej środowiskowej, dzięki czemu ta sama konfiguracja narzędzia może używać innego połączenia w każdym środowisku.

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

Tworzenie narzędzia klienckiego

Tool.client(name, description) tworzy narzędzie klienckie, które działa w twojej aplikacji, a nie na serwerze. Dodaj jego parametry przez param(name, schema). Ustaw expects_response / expectsResponse, gdy agent ma czekać na wynik twojej aplikacji:

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

Tworzenie narzędzia systemowego

Narzędzia systemowe są wbudowane w platformę. Każde ma własny konstruktor w SystemTool, który przyjmuje ustawienia tego narzędzia:

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

Dwa narzędzia transferu pobierają miejsca docelowe z transfer(condition, destination, options). Warunek mówi LLM, kiedy wykonać transfer, a miejsce docelowe używa tego samego Destination co workflow jako kod. Transfer do URI SIP wymaga transferu 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"
)

Opcje narzędzi

Ustawienia wspólne dla każdego typu narzędzia umieszcza się w options(): jako argumenty nazwane w Pythonie i obiekt w JavaScripcie. Ich nazwy odpowiadają polom konfiguracji narzędzia w API:

DotyczyPythonJavaScript
Wszystkie narzędzianame, description, response_timeout_secs, interruption_mode, pre_tool_speech, tool_call_sound, tool_error_handling_mode, …name, description, responseTimeoutSecs, interruptionMode, preToolSpeech, toolCallSound, toolErrorHandlingMode, …
Narzędzia webhookexecution_mode, content_type, response_filter, follow_redirects, follow_redirects_allowed_domains, dynamic_variable_placeholdersexecutionMode, contentType, responseFilter, followRedirects, followRedirectsAllowedDomains, dynamicVariablePlaceholders
Narzędzia klienckieexecution_mode, expects_response, dynamic_variable_placeholdersexecutionMode, expectsResponse, dynamicVariablePlaceholders

Limit czasu odpowiedzi narzędzia webhook wynosi od 5 do 300 sekund. Dla narzędzia klienckiego wynosi od 1 do 120 sekund albo -1, aby czekać tak długo, jak potrzeba, co wymaga expects_response / expectsResponse. follow_redirects / followRedirects wymaga listy dozwolonych domen.

Dodawanie narzędzi do agenta

Narzędzia webhook i klienckie są tworzone osobno przez tools.create() i dodawane do agentów za pomocą ID, więc jedno narzędzie może być współdzielone przez kilku agentów. Narzędzia systemowe są częścią konfiguracji agenta: build_config() / buildConfig() zwraca wpis dla wbudowanych narzędzi agenta.

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

Pole prompt.tools agenta, które przechowuje konfiguracje narzędzi bezpośrednio, jest wycofywane. Nie można go łączyć z tool_ids, a gdy żądanie je zawiera, wbudowane narzędzia agenta są zastępowane narzędziami systemowymi, które ono zawiera. Zamiast tego twórz narzędzia przez tools.create() i dodawaj je według ID.

Edycja istniejącego narzędzia

Tool.from_response() / Tool.fromResponse() wczytuje narzędzie zwrócone przez tools.get(). Pola, których kreator nie modeluje, oraz domyślne wartości uzupełniane przez API zostają zachowane, więc odesłanie narzędzia zmienia tylko to, co zmienisz. as_webhook(), as_client() i as_system() (w JavaScripcie asWebhook() itd.) zwracają typowane narzędzie do edycji albo None / undefined, jeśli jest innego rodzaju.

Aby zmienić właściwość treści żądania, odczytaj schemat treści, ponownie ustaw właściwość i ustaw treść:

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

Przechowywanie narzędzi w kontroli wersji

to_json_string() / toJSONString() zapisuje narzędzie w formacie przesyłanym przez API: klucze w snake_case, sortowane na każdym poziomie, z wcięciem 2 spacji. Ma ten sam format, który CLI przechowuje w katalogu tool_configs/, a oba SDK zapisują bajt w bajt identyczne pliki dla tego samego narzędzia, więc różnice pozostają małe. Tool.from_json() / Tool.fromJSON() odczytuje je ponownie.

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

Typowa konfiguracja jest taka sama jak dla workflow: zainicjuj pliki za pomocą elevenlabs tools pull, edytuj je bezpośrednio lub przez kreator, uruchamiaj Tool.from_json(file).build() / Tool.fromJSON(file).build() w CI przy każdym pull requeście i wysyłaj je przez tools.update() lub elevenlabs tools push po scaleniu.

Walidacja

Wywołania łańcuchowe same w sobie nigdy nie kończą się błędem. build(), build_config() / buildConfig(), to_json() / toJSON() i to_json_string() / toJSONString() sprawdzają całe narzędzie oraz zgłaszają pojedynczy ToolValidationError, którego lista issues zawiera każdy problem wraz z code, message i path części, której dotyczy, na przykład 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)

Błędy obejmują:

  • Symbol zastępczy URL bez parametru ścieżki albo parametr ścieżki bez symbolu zastępczego. Szablony zmiennych środowiskowych, takie jak {{system__env_api_host}}, nie są symbolami zastępczymi.
  • Wartość literalną bez źródła wartości albo z więcej niż jednym źródłem.
  • Treść żądania przy GET albo brak treści przy POST, PUT lub PATCH.
  • Tę samą nazwę parametru w więcej niż jednym z miejsc: ścieżce, zapytaniu i treści.
  • omit() dla wymaganej właściwości, choices() dla schematu, który nie jest tekstem, albo stałą niezgodną z typem schematu.
  • Narzędzie transferu bez miejsc docelowych, miejsce docelowe niewłaściwego rodzaju albo miejsce docelowe URI SIP bez transferu SIP REFER.
  • Opcję, która nie dotyczy danego rodzaju narzędzia, albo limit czasu poza dozwolonym zakresem.

Typy narzędzi nowsze niż twoje SDK

Narzędzie wczytane z API lub pliku może mieć typ, którego kreator nie może edytować, na przykład narzędzie MCP. Jest wczytywane z rodzajem "other" i bez zmian przechodzi przez from_json() / fromJSON() oraz to_json_string() / toJSONString(), a build() zgłasza je jako ostrzeżenie przez on_warning / onWarning.