> 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. # Narzędzia kodowe **Narzędzia kodowe** pozwalają agentowi uruchamiać własny JavaScript w odizolowanym środowisku po stronie serwera, bez tworzenia i hostowania własnego endpointu webhooka. Napisz logikę raz we wbudowanym edytorze kodu, a ElevenLabs uruchomi ją za każdym razem, gdy agent wywoła narzędzie. > **Note** > > Ta funkcja jest dostępna tylko w planie Enterprise. ## Omówienie Narzędzie kodowe to funkcja JavaScript uruchamiana, gdy agent ją wywoła. Piszesz całą treść funkcji, więc narzędzie może robić tyle, ile wymaga zadanie: * **Własne obliczenia**: stosuj reguły cenowe, przeliczaj jednostki, twórz logikę punktacji lub wykonuj obliczenia na datach, korzystając tylko z parametrów wywołania narzędzia. Dostęp do sieci nie jest wymagany. * **Wywoływanie zewnętrznych API**: używaj `fetch` dla domen z listy dozwolonych, z sekretami workspace'u i połączeniami uwierzytelniania dodanymi do kontekstu funkcji. * **Łączenie wielu źródeł**: wywołaj dwa lub trzy API i połącz, porównaj lub uzgodnij ich wyniki przed zwróceniem jednej odpowiedzi. * **Rozgałęzienia warunkowe**: uruchamiaj inną logikę zależnie od parametrów wywołania narzędzia, bez tworzenia osobnego narzędzia dla każdej gałęzi. * **Przekształcanie danych**: zwracaj dokładnie taką strukturę, jaką agent ma zobaczyć, zamiast surowej odpowiedzi źródłowej. > **Info** > > W przypadku pojedynczego wywołania zewnętrznego API bez własnej logiki [narzędzia webhooka](/docs/pl/eleven-agents/customization/tools/webhook-tools) są zwykle prostsze w konfiguracji. Aby wywoływać działania w przeglądarce lub aplikacji użytkownika, użyj zamiast tego [narzędzi klienckich](/docs/pl/eleven-agents/customization/tools/client-tools). ## Jak to działa Twój kod to moduł JavaScript, który eksportuje jedną domyślną funkcję asynchroniczną. Funkcja otrzymuje obiekt `ctx` i zwraca wynik narzędzia: ```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}!` }; }; ``` Zwrócona wartość staje się wynikiem narzędzia. Jest przekazywana agentowi, wyświetlana w transkrypcji rozmowy i może służyć do [dynamicznego przypisywania zmiennych](/docs/pl/eleven-agents/customization/tools/webhook-tools#tool-configuration). ### Obiekt `ctx` `ctx` to punkt dostępu do wszystkiego, z czego narzędzie może skorzystać podczas wywołania. Parametry przekazane przez agenta zawsze trafiają do `ctx.args`; sekrety, wartości konfiguracji i połączenia uwierzytelniania są opcjonalne i pojawiają się tylko wtedy, gdy przypiszesz je w sekcji **Context object** narzędzia. | Właściwość | Opis | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ctx.args` | Parametry wywołania narzędzia przekazane przez agenta. | | `ctx.config` | Zwykłe zmienne tekstowe przypisane do kontekstu tego narzędzia. | | `ctx.secrets` | Sekrety workspace'u przypisane do kontekstu tego narzędzia do użycia w nagłówkach żądań. Surowy sekret nigdy nie jest dostępny dla twojego kodu; jest dodawany przy wysyłaniu żądania i wyłącznie w nagłówkach. | | `ctx.auth_connections` | Odwołania do skonfigurowanych [połączeń uwierzytelniania](/docs/pl/eleven-agents/customization/tools/webhook-tools#supported-authentication-methods) przypisanych do kontekstu tego narzędzia, do użycia w nagłówku żądania `X-With-Auth-Connection`. Dane uwierzytelniające nigdy nie są dostępne dla twojego kodu; są dodawane przy wysyłaniu żądania i wyłącznie w nagłówkach. | > **Note** > > Tylko `ctx.args` jest widoczne dla agenta, gdy wywołuje narzędzie. Sekrety, wartości konfiguracji i połączenia uwierzytelniania nigdy nie są ujawniane agentowi. #### Konfiguracja parametrów Parametry to wartości przekazywane przez agenta podczas wywołania narzędzia. Trafiają do `ctx.args`. Zdefiniuj je w sekcji **Parameters** formularza konfiguracji narzędzia lub w edytorze kodu na karcie **Params**, w podkarcie **Define Params**. Każdy parametr ma typ danych, identyfikator i opis, którego agent używa, aby określić poprawną wartość z rozmowy. Twój kod odczytuje tę wartość pod identyfikatorem, takim jak `ctx.args.appointment_datetime` poniżej. ![Definiowanie parametru narzędzia kodowego](/docs/_fern-img/d492e864ae15f3a355251faae3b719544e1ab56b703c02740b51be6c6769ccf7.webp) #### Konfiguracja obiektu kontekstu Dodaj sekrety, wartości konfiguracji i połączenia uwierzytelniania w sekcji **Context object** narzędzia. Każdy wpis ma typ i nazwę. Panel pokazuje dokładny accessor dla każdego wpisu, na przykład `ctx.secrets.DEMO_KEY` poniżej. ![Przypisywanie sekretu workspace'u do obiektu kontekstu narzędzia kodowego](/docs/_fern-img/ad58ee53f3591f447b108191aff760f1134350911933b968b06798fa6d42f438.webp) ### Dostęp do sieci Kod uruchamiany w sandboxie może łączyć się tylko z domenami wyraźnie dozwolonymi w twoim workspace'ie. Dodaj domeny, z którymi ma łączyć się kod, w **ElevenAgents Settings**, w sekcji **Code Tool Network Access**. Żądanie do każdej innej domeny zakończy się błędem. > **Warning** > > Edycja **Code Tool Network Access** wymaga uprawnień administratora workspace'u. ### Limity wykonywania * **Limit czasu**: każde uruchomienie musi zakończyć się w czasie odpowiedzi skonfigurowanym dla narzędzia — od 1 do 30 sekund. * **Bez zewnętrznych pakietów**: narzędzia kodowe obecnie działają bez zależności npm. ### Testowanie kodu Przed zapisaniem użyj **Run** w edytorze kodu, aby uruchomić kod z przykładowymi wartościami parametrów: * **Params** — ustaw wartości testowe dla każdego parametru zdefiniowanego przez narzędzie. * **Output** — zobacz zwrócony wynik lub błąd, jeśli wykonanie się nie powiodło. * **Logs** — zobacz wszystko, co zapisano za pomocą `console.log`, `console.warn` lub `console.error`, a także czas kompilacji i wykonania. ## Przewodnik W tym przewodniku utworzymy narzędzie kodowe, które przelicza temperaturę i zwraca przyjazny, sformatowany tekst: #### Utwórz nowe narzędzie kodowe W sekcji **Agent** na stronie ustawień agenta wybierz **Add Tool**. Wybierz **Code** jako typ narzędzia, a następnie ustaw nazwę i opis: | Pole | Wartość | | ----- | -------------------------------------------------------------- | | Nazwa | convert_temperature | | Opis | Przelicza temperaturę między stopniami Celsjusza i Fahrenheita | #### Zdefiniuj parametry Dodaj dwa parametry, aby LLM wiedział, co przekazać: | Typ danych | Identyfikator | Wymagany | Opis | | ---------- | ------------- | -------- | ----------------------------------- | | number | value | true | Wartość temperatury do przeliczenia | | string | from_unit | true | Jednostka źródłowa: `"C"` lub `"F"` | #### Napisz kod Otwórz edytor kodu i zastąp domyślny kod źródłowy poniższym: ```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` }; }; ``` Użyj **Run** z kilkoma przykładowymi wartościami (np. `value: 100, from_unit: "C"`), aby potwierdzić wynik przed zapisaniem. #### Orkiestracja Zaktualizuj prompt systemowy agenta, aby wiedział, kiedy użyć narzędzia: **`Prompt systemowy`** ```plaintext Prompt systemowy 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. ``` #### Testowanie Rozpocznij rozmowę i spróbuj: > *Ile to 100 stopni Celsjusza w Fahrenheitach?* Agent powinien wywołać narzędzie i podać przeliczoną wartość. ### Przykłady uwierzytelniania **Wywoływanie API z sekretem** ```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(); }; ``` Przypisz `EXAMPLE_API_KEY` do sekretu workspace'u w sekcji **Context object** narzędzia, a następnie dodaj `api.example.com` do **Code Tool Network Access**, aby umożliwić wysłanie żądania. Wartość, do której się odwołujesz, jest placeholderem: prawdziwy sekret jest podstawiany do nagłówka przy wysyłaniu żądania i nigdy nie jest widoczny dla twojego kodu. **Wywoływanie API z połączeniem uwierzytelniania OAuth** ```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(); }; ``` Przypisz `EXAMPLE_CRM` do skonfigurowanego [połączenia uwierzytelniania](/docs/pl/eleven-agents/customization/tools/webhook-tools#supported-authentication-methods) w sekcji **Context object** narzędzia. Wartość, do której się odwołujesz, jest placeholderem: prawdziwe dane uwierzytelniające są podstawiane do nagłówka przy wysyłaniu żądania i nigdy nie są widoczne dla twojego kodu. ## Dobre praktyki #### Nazywaj narzędzia intuicyjnie i dodawaj szczegółowe opisy Jeśli asystent nie wywołuje właściwych narzędzi, być może trzeba zaktualizować ich nazwy i opisy, aby lepiej rozumiał, kiedy wybrać każde z nich. Nie używaj skrótów ani akronimów, by skracać nazwy narzędzi i argumentów. Możesz też dodać szczegółowe opisy, kiedy należy wywołać dane narzędzie. W przypadku złożonych narzędzi warto opisać każdy argument, aby asystent wiedział, o co musi zapytać użytkownika, by uzyskać dany argument. #### Nazywaj parametry narzędzi intuicyjnie i dodawaj szczegółowe opisy Używaj jasnych, opisowych nazw parametrów narzędzi. Jeśli ma to zastosowanie, określ w opisie oczekiwany format parametru (np. YYYY-mm-dd lub dd/mm/yy dla daty). #### Rozważ dodanie informacji o tym, jak i kiedy wywoływać narzędzia, do promptu systemowego asystenta Jasne instrukcje w prompcie systemowym mogą znacznie poprawić trafność wywoływania narzędzi przez asystenta. Na przykład poprowadź asystenta instrukcjami takimi jak poniżej: ```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?'. ``` Dodaj kontekst w złożonych sytuacjach. Na przykład: ```plaintext Before scheduling a meeting with `schedule_meeting`, check the user's calendar for availability using check_availability to avoid conflicts. ``` #### Wybór LLM > **Warning** > > Podczas korzystania z narzędzi zalecamy wybór modeli o wysokich zdolnościach rozumowania, takich jak GPT 6 lub Claude Sonnet 5.5. Wybór LLM ma znaczenie dla skuteczności wywołań funkcji. Niektóre LLM mogą mieć trudności z wyciąganiem istotnych parametrów z rozmowy.