Verktyg som kod
Bygg, redigera och versionshantera agentverktyg med Python- och JavaScript-SDK:erna
Översikt
Ett verktyg lagras som en konfiguration med kapslade JSON-scheman för sina parametrar. Om du skriver konfigurationen för hand måste du hålla sökvägsparametrar synkroniserade med URL:en, required-listor synkroniserade med sina egenskaper och ge varje parameter exakt en värdekälla. Verktygsbyggaren i Python- och JavaScript-SDK:erna låter dig beskriva samma verktyg med kedjade metodanrop. Den skapar sedan begäran som tools.create() och tools.update() redan accepterar.
Använd den för att:
- Definiera webhook-, klient- och systemverktyg i kod och granska dem som alla andra kodändringar.
- Läsa in ett verktyg, ändra en parameter och skicka tillbaka det utan att påverka resten av konfigurationen.
- Lagra verktyg som JSON i versionshantering och validera dem i CI.
Byggaren körs helt i SDK:n. Den anropar inga nya API-slutpunkter, och allt den bygger kan öppnas och redigeras i kontrollpanelen.
Krav
- Python: paketet
elevenlabs. Byggaren importeras frånelevenlabs.agent_tools. - JavaScript: paketet
@elevenlabs/elevenlabs-js. Byggaren exporteras från paketets rot.
Bygg ett webhook-verktyg
Tool.webhook(name, description) startar ett webhook-verktyg. Namnet och beskrivningen är vad LLM:en ser när den avgör om verktyget ska anropas. Det här exemplet slår upp en order utifrån numret som den som ringer uppger, skickar en API-nyckel från arbetsytans hemligheter och lagrar orderns status i en dynamisk variabel:
Begärandemetoderna anger HTTP-metod och URL. {name}-platshållare i URL:en fylls i från sökvägsparametrar:
Om du anger en parameter eller header vars namn redan finns ersätts den och behåller sin position. remove_path_param(), remove_query_param(), remove_header() och remove_assignment() (removePathParam() och så vidare i JavaScript) tar bort en. Parameternamn måste vara unika mellan sökväg, fråga och brödtext.
En brödtext är ett objektschema som byggs egenskap för egenskap:
Parameterscheman
Schema bygger parameterscheman som webhook- och klientverktyg använder. Varje metod returnerar ett nytt schema och lämnar det den anropades på oförändrat, så du kan definiera ett schema en gång och använda det i flera verktyg.
Var ett värde kommer från
Varje bokstavligt värde behöver exakt en värdekälla, oavsett var det förekommer: i en parameter, i en brödtext, i ett svarsschema eller inuti ett objekt eller en matris. Ett objekt eller en matris kan också ha en, som då tillhandahåller hela värdet.
På ett objekt eller en matris dokumenterar describe() behållaren för LLM:en, och varje egenskap eller element har fortfarande sin egen källa.
Andra schemametoder
Headers och autentisering
Ett header-värde kommer från en av fyra platser. Använd en hemlighet eller en miljövariabel för allt känsligt, så att värdet aldrig visas i verktygskonfigurationen:
AuthConnection.id(id) använder en autentiseringsanslutning från arbetsytan via ID. AuthConnection.env_var(label) / AuthConnection.envVar(label) väljer den från en miljövariabel, så att samma verktygskonfiguration kan använda en annan anslutning i varje miljö.
Bygg ett klientverktyg
Tool.client(name, description) startar ett klientverktyg, som körs i din applikation i stället för på en server. Lägg till dess parametrar med param(name, schema). Ange expects_response / expectsResponse när agenten ska vänta på resultatet från din applikation:
Bygg ett systemverktyg
Systemverktyg är inbyggda i plattformen. Varje verktyg har en egen konstruktor på SystemTool, som tar verktygets inställningar:
De två överföringsverktygen hämtar sina destinationer från transfer(condition, destination, options). Villkoret anger för LLM:en när överföringen ska göras, och destinationen använder samma Destination som workflows som kod. En överföring till en SIP-URI kräver en SIP REFER-överföring:
Verktygsalternativ
Inställningar som delas av alla typer av verktyg anges i options(), som nyckelordsargument i Python och ett objekt i JavaScript. Namnen matchar verktygskonfigurationens fält i API:et:
Ett webhook-verktygs svarstimeout är 5 till 300 sekunder. Ett klientverktygs är 1 till 120 sekunder, eller -1 för att vänta så länge som krävs, vilket kräver expects_response / expectsResponse. follow_redirects / followRedirects kräver en lista med tillåtna domäner.
Koppla verktyg till en agent
Webhook- och klientverktyg skapas separat med tools.create() och kopplas till agenter via ID, så att ett verktyg kan delas av flera agenter. Systemverktyg är en del av agentens konfiguration: build_config() / buildConfig() returnerar posten för agentens inbyggda verktyg.
Agentens fält prompt.tools, som innehåller verktygskonfigurationer inline, är föråldrat. Det kan inte
kombineras med tool_ids, och när en begäran innehåller det ersätts agentens inbyggda verktyg
av systemverktygen som det innehåller. Skapa i stället verktyg med tools.create() och koppla dem via ID.
Redigera ett befintligt verktyg
Tool.from_response() / Tool.fromResponse() läser in ett verktyg som returneras av tools.get(). Fält som byggaren inte modellerar och standardvärdena som API:et fyller i behålls, så när du skickar tillbaka det ändras endast det du har ändrat. as_webhook(), as_client() och as_system() (asWebhook() och så vidare i JavaScript) ger dig det typade verktyget att redigera, eller None / undefined om det är en annan typ.
För att ändra en egenskap i brödtexten läser du brödtextschemat, anger egenskapen igen och anger brödtexten:
Lagra verktyg i versionshantering
to_json_string() / toJSONString() skriver verktyget i API:ets trådformat: snake_case-nycklar, sorterade på varje nivå, med indrag på två blanksteg. Det har samma form som CLI lagrar i sin katalog tool_configs/, och båda SDK:erna skriver byte-identiska filer för samma verktyg, så skillnaderna hålls små. Tool.from_json() / Tool.fromJSON() läser in det igen.
En vanlig konfiguration är densamma som för workflows: skapa filerna med elevenlabs tools pull, redigera dem direkt eller med byggaren, kör Tool.from_json(file).build() / Tool.fromJSON(file).build() i CI för varje pull request och skicka dem med tools.update() eller elevenlabs tools push vid sammanslagning.
Validering
Kedjade anrop misslyckas aldrig på egen hand. build(), build_config() / buildConfig(), to_json() / toJSON() och to_json_string() / toJSONString() kontrollerar hela verktyget och reser eller kastar ett enda ToolValidationError vars issues listar varje problem, vart och ett med en code, ett message och path till den berörda delen, till exempel body.reason.
Fel omfattar:
- En URL-platshållare utan sökvägsparameter, eller en sökvägsparameter utan platshållare. Mallar för miljövariabler som
{{system__env_api_host}}är inte platshållare. - Ett bokstavligt värde utan värdekälla eller med fler än en.
- En brödtext på en
GET, eller ingen brödtext på enPOST,PUTellerPATCH. - Samma parameternamn i fler än en av sökväg, fråga och brödtext.
omit()på en obligatorisk egenskap,choices()på ett schema som inte är en sträng eller en konstant som inte matchar schemats typ.- Ett överföringsverktyg utan destinationer, en destination av fel typ eller en SIP-URI-destination utan SIP REFER-överföring.
- Ett alternativ som inte gäller för verktygstypen eller en timeout utanför dess intervall.
Verktygstyper som är nyare än din SDK
Ett verktyg som läses in från API:et eller från en fil kan vara av en typ som byggaren inte kan redigera, till exempel ett MCP-verktyg. Det läses in med typen "other" och går oförändrat tur och retur via from_json() / fromJSON() och to_json_string() / toJSONString(), och build() rapporterar det som en varning via on_warning / onWarning.