> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt. # Kodverktyg **Kodverktyg** låter din agent köra anpassad JavaScript i en isolerad servermiljö, utan att du behöver sätta upp och drifta en egen webhook-slutpunkt. Skriv logiken en gång i den inbyggda kոդredigeraren, så kör ElevenLabs den varje gång agenten anropar verktyget. > **Note** > > Det här är en funktion endast för Enterprise. ## Översikt Ett kodverktyg är en JavaScript-funktion som körs när agenten anropar den. Du skriver hela funktionskroppen, så verktyget kan göra så mycket eller lite som uppgiften kräver: * **Anpassade beräkningar**: tillämpa prisregler, enhetsomvandlingar, poänglogik eller datumberäkningar med enbart parametrarna i verktygsanropet. Ingen nätverksåtkomst krävs. * **Anropa externa API:er**: använd `fetch` från tillåtna domäner, med arbetsytehemligheter och autentiseringsanslutningar injicerade i funktionens kontext. * **Kombinera flera källor**: anropa två eller tre API:er och slå ihop, jämför eller stäm av resultaten innan du returnerar ett enda svar. * **Villkorsstyrd förgrening**: kör olika logik beroende på parametrarna i verktygsanropet, utan att behöva ett separat verktyg per gren. * **Omforma data**: returnera exakt den struktur som du vill att agenten ska se, i stället för ett rått uppströmssvar. > **Info** > > För ett enda externt API-anrop utan anpassad logik är [webhook- verktyg](/docs/sv/eleven-agents/customization/tools/webhook-tools) vanligtvis enklare att konfigurera. För att > utlösa åtgärder i en användares webbläsare eller app använder du [klient- verktyg](/docs/sv/eleven-agents/customization/tools/client-tools) i stället. ## Så fungerar det Din kod är en JavaScript-modul som exporterar en enda asynkron standardfunktion. Funktionen tar emot ett `ctx`-objekt och returnerar verktygets resultat: ```javascript export default async (ctx) => { // ctx.args. — the parameters the agent passed to this tool call const { city } = ctx.args; return { message: `Hello from ${city}!` }; }; ``` Värdet du returnerar blir verktygets resultat. Det skickas tillbaka till agenten, visas i samtalstranskriptet och kan användas för [dynamisk variabeltilldelning](/docs/sv/eleven-agents/customization/tools/webhook-tools#tool-configuration). ### Objektet `ctx` `ctx` är din ingång till allt som verktyget kan komma åt vid anropstillfället. Parametrarna som agenten anger kommer alltid i `ctx.args`; hemligheter, konfigurationsvärden och autentiseringsanslutningar är valfria och visas endast om du mappar dem i verktygets avsnitt **Kontextobjekt**. | Egenskap | Beskrivning | | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ctx.args` | Parametrarna för verktygsanropet som agenten angav. | | `ctx.config` | Vanliga strängvariabler som du har mappat till verktygets kontext. | | `ctx.secrets` | Arbetsytehemligheter som du har mappat till verktygets kontext för användning i begärandehuvuden. Den råa hemligheten exponeras aldrig för din kod; injektionen sker vid utgående trafik och enbart i huvuden. | | `ctx.auth_connections` | Referenser till konfigurerade [autentiseringsanslutningar](/docs/sv/eleven-agents/customization/tools/webhook-tools#supported-authentication-methods) som du har mappat till verktygets kontext, för användning i begärandehuvudet `X-With-Auth-Connection`. Den underliggande autentiseringsuppgiften exponeras aldrig för din kod; injektionen sker vid utgående trafik och enbart i huvuden. | > **Note** > > Endast `ctx.args` är synligt för agenten när den anropar verktyget. Hemligheter, konfigurationsvärden och autentiseringsanslutningar visas aldrig för agenten. #### Konfigurera parametrar Parametrar är de värden agenten tillhandahåller när den anropar verktyget, och de kommer i `ctx.args`. Definiera dem i avsnittet **Parametrar** i formuläret för verktygskonfigurationen eller i kodredigeraren på fliken **Parametrar**, under underfliken **Definiera parametrar**. Varje parameter har en datatyp, en identifierare och en beskrivning som agenten använder för att avgöra rätt värde utifrån samtalet. Din kod läser värdet via identifieraren, exempelvis `ctx.args.appointment_datetime` nedan. ![Definiera en parameter för ett kodverktyg](/docs/_fern-img/d492e864ae15f3a355251faae3b719544e1ab56b703c02740b51be6c6769ccf7.webp) #### Konfigurera kontextobjektet Lägg till hemligheter, konfigurationsvärden och autentiseringsanslutningar i verktygets avsnitt **Kontextobjekt**. Varje post har en typ och ett namn. Panelen visar den exakta åtkomstmetoden för varje post, exempelvis `ctx.secrets.DEMO_KEY` nedan. ![Mappa en arbetsytehemlighet till ett kodverktygs kontextobjekt](/docs/_fern-img/ad58ee53f3591f447b108191aff760f1134350911933b968b06798fa6d42f438.webp) ### Nätverksåtkomst Kod som körs i sandboxen kan endast nå domäner som din arbetsyta uttryckligen har tillåtit. Lägg till de domäner som din kod behöver anropa i dina **ElevenAgents-inställningar**, under **Nätverksåtkomst för kodverktyg**. En begäran till en annan domän misslyckas. > **Warning** > > För att redigera **Nätverksåtkomst för kodverktyg** krävs administratörsbehörighet för arbetsytan. ### Körningsgränser * **Tidsgräns**: varje körning måste slutföras inom verktygets konfigurerade svarstidsgräns, från 1 till 30 sekunder. * **Inga externa paket**: kodverktyg körs för närvarande utan npm-beroenden. ### Testa din kod Innan du sparar kan du använda **Kör** i kodredigeraren för att köra koden med exempelvärden för parametrar: * **Parametrar** — ange testvärden för varje parameter som verktyget definierar. * **Utdata** — se det returnerade resultatet eller felet om körningen misslyckades. * **Loggar** — se allt som skrivits med `console.log`, `console.warn` eller `console.error`, samt tider för bygge och körning. ## Guide I den här guiden skapar vi ett kodverktyg som omvandlar en temperatur och returnerar en vänlig, formaterad sträng: #### Skapa ett nytt kodverktyg I avsnittet **Agent** på sidan med agentinställningar väljer du **Lägg till verktyg**. Välj **Kod** som verktygstyp och ange sedan ett namn och en beskrivning: | Fält | Värde | | ----------- | ----------------------------------------------------- | | Namn | convert\_temperature | | Beskrivning | Omvandlar en temperatur mellan Celsius och Fahrenheit | #### Definiera parametrarna Lägg till två parametrar så att LLM:en vet vad den ska ange: | Datatyp | Identifierare | Obligatorisk | Beskrivning | | ------- | ------------- | ------------ | -------------------------------------------- | | number | value | true | Temperaturvärdet som ska omvandlas | | string | from\_unit | true | Enheten att omvandla från: `"C"` eller `"F"` | #### Skriv koden Öppna kodredigeraren och ersätt standardkällkoden med: ```javascript export default async (ctx) => { const { value, from_unit } = ctx.args; if (from_unit === "C") { const fahrenheit = (value * 9) / 5 + 32; return { result: `${value}°C is ${fahrenheit.toFixed(1)}°F` }; } const celsius = ((value - 32) * 5) / 9; return { result: `${value}°F is ${celsius.toFixed(1)}°C` }; }; ``` Använd **Kör** med några exempelvärden (t.ex. `value: 100, from_unit: "C"`) för att bekräfta resultatet innan du sparar. #### Orkestrering Uppdatera agentens systemprompt så att den vet när den ska använda verktyget: **`Systemprompt`** ```plaintext Systemprompt When the user asks to convert a temperature, call convert_temperature with the value and its unit ("C" or "F"), and read back the result naturally. ``` #### Testning Starta ett samtal och prova: > *Vad är 100 grader Celsius i Fahrenheit?* Agenten bör anropa verktyget och läsa upp det omvandlade värdet. ### Exempel på autentisering **Anropa ett API med en hemlighet** ```javascript export default async (ctx) => { const { order_id } = ctx.args; const response = await fetch(`https://api.example.com/orders/${order_id}`, { headers: { Authorization: `Bearer ${ctx.secrets.EXAMPLE_API_KEY}`, }, }); if (!response.ok) { throw new Error(`Upstream error: ${response.status}`); } return await response.json(); }; ``` Mappa `EXAMPLE_API_KEY` till en arbetsytehemlighet i verktygets avsnitt **Kontextobjekt** och lägg sedan till `api.example.com` i **Nätverksåtkomst för kodverktyg** så att begäran tillåts gå ut. Värdet du refererar till är en platshållare: den verkliga hemligheten ersätts i huvudet vid utgående trafik och är aldrig synlig för din kod. **Anropa ett API med en OAuth-autentiseringsanslutning** ```javascript export default async (ctx) => { const { customer_id } = ctx.args; const response = await fetch(`https://api.example.com/customers/${customer_id}`, { headers: { "X-With-Auth-Connection": ctx.authConnections.EXAMPLE_CRM, }, }); if (!response.ok) { throw new Error(`Upstream error: ${response.status}`); } return await response.json(); }; ``` Mappa `EXAMPLE_CRM` till en konfigurerad [autentiseringsanslutning](/docs/sv/eleven-agents/customization/tools/webhook-tools#supported-authentication-methods) i verktygets avsnitt **Kontextobjekt**. Värdet du refererar till är en platshållare: den verkliga autentiseringsuppgiften ersätts i huvudet vid utgående trafik och är aldrig synlig för din kod. ## Bästa praxis #### Namnge verktyg intuitivt och med detaljerade beskrivningar Om assistenten inte anropar rätt verktyg kan du behöva uppdatera verktygsnamnen och beskrivningarna så att assistenten tydligare förstår när varje verktyg ska väljas. Undvik att använda förkortningar eller akronymer för att förkorta namn på verktyg och argument. Du kan också inkludera detaljerade beskrivningar av när ett verktyg ska anropas. För komplexa verktyg bör du inkludera beskrivningar för varje argument för att hjälpa assistenten förstå vad den behöver fråga användaren om för att samla in argumentet. #### Namnge verktygsparametrar intuitivt och med detaljerade beskrivningar Använd tydliga och beskrivande namn för verktygsparametrar. Ange vid behov det förväntade formatet för en parameter i beskrivningen (t.ex. YYYY-mm-dd eller dd/mm/yy för ett datum). #### Överväg att ge ytterligare information om hur och när verktyg ska anropas i assistentens systemprompt Tydliga instruktioner i systemprompten kan avsevärt förbättra assistentens precision vid verktygsanrop. Du kan till exempel vägleda assistenten med instruktioner som följande: ```plaintext Use `check_order_status` when the user inquires about the status of their order, such as 'Where is my order?' or 'Has my order shipped yet?'. ``` Ge kontext för komplexa scenarier. Till exempel: ```plaintext Before scheduling a meeting with `schedule_meeting`, check the user's calendar for availability using check_availability to avoid conflicts. ``` #### Val av LLM > **Warning** > > När du använder verktyg rekommenderar vi modeller med hög intelligens, som GPT 6 eller Claude Sonnet 5.5. Det är viktigt att notera att valet av LLM påverkar hur väl funktionsanrop lyckas. Vissa LLM:er kan ha svårt att extrahera relevanta parametrar från konversationen.