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ę zelevenlabs.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:
Metody żądań ustawiają metodę HTTP i URL. Symbole zastępcze {name} w URL-u są uzupełniane parametrami ścieżki:
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:
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.
Ź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ść.
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
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:
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.
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:
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:
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:
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:
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.
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ść:
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.
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.
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
GETalbo brak treści przyPOST,PUTlubPATCH. - 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.