> 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 webhook **Narzędzia** pozwalają twojemu asystentowi łączyć się z zewnętrznymi danymi i systemami. Możesz zdefiniować zestaw narzędzi, do których asystent ma dostęp, a on użyje ich tam, gdzie będzie to potrzebne w zależności od rozmowy. ## Omówienie Wiele aplikacji wymaga, by asystenci wywoływali zewnętrzne API, aby uzyskać informacje w czasie rzeczywistym. Narzędzia dają asystentowi możliwość wywoływania zewnętrznych funkcji w aplikacjach innych firm, dzięki czemu możesz uzyskiwać informacje w czasie rzeczywistym. Oto kilka przykładów, kiedy narzędzia mogą się przydać: * **Pobieranie danych**: pozwól asystentowi pobierać dane w czasie rzeczywistym z dowolnej bazy danych obsługującej REST lub integracji innej firmy przed odpowiedzią użytkownikowi. * **Podejmowanie działań**: pozwól asystentowi uruchamiać uwierzytelnione działania na podstawie rozmowy, np. planować spotkania lub inicjować zwroty zamówień. > **Info** > > Aby wchodzić w interakcje z interfejsami aplikacji lub uruchamiać zdarzenia po stronie klienta, użyj zamiast tego [narzędzi klienta](/docs/pl/eleven-agents/customization/tools/client-tools). ## Konfiguracja narzędzia Agenci ElevenLabs mogą być wyposażeni w narzędzia do interakcji z zewnętrznymi API. W przeciwieństwie do tradycyjnych żądań asystent dynamicznie generuje parametry query, body i path na podstawie rozmowy oraz podanych przez ciebie opisów parametrów. Wszystkie konfiguracje narzędzi i opisy parametrów pomagają asystentowi określić, **kiedy** i **jak** używać tych narzędzi. Aby skutecznie koordynować użycie narzędzi, zaktualizuj system prompt asystenta, aby określić kolejność i logikę tych wywołań. Obejmuje to: * **Którego narzędzia** użyć i w jakich warunkach. * **Jakich parametrów** potrzebuje narzędzie, aby działać poprawnie. * **Jak obsługiwać** odpowiedzi. \ #### Konfiguracja Zdefiniuj ogólną `Name` i `Description`, które opisują przeznaczenie narzędzia. Pomaga to modelowi LLM zrozumieć narzędzie i wiedzieć, kiedy je wywołać. > **Info** > > Jeśli API wymaga parametrów path, dodaj zmienne w ścieżce URL, umieszczając je w nawiasach > klamrowych `{}`, na przykład: `/api/resource/{id}`, gdzie `id` jest parametrem path. ![Konfiguracja](/docs/_fern-img/fb6e6619e4e7a5f19c2a86f9c2a489f5cb33cfb0883c14a06f0eec3cb35d71d5.webp) #### Uwierzytelnianie Skonfiguruj uwierzytelnianie, dodając własne nagłówki lub korzystając z gotowych metod uwierzytelniania przez połączenia auth. ![Uwierzytelnianie narzędzia](/docs/_fern-img/5ffae070945a86b74975cd9b56679c2bb76f0ce70d05fe7b10e8e5dff6ddd630.webp) #### Nagłówki Określ nagłówki, które należy uwzględnić w żądaniu. ![Nagłówki](/docs/_fern-img/9c8c3f2d42f84a6e40922a4c777199e79646b174fa51b9e4d5b21695d7da3f66.webp) #### Parametry path Dodaj zmienne w ścieżce URL, umieszczając je w nawiasach klamrowych `{}`: * **Przykład**: `/api/resource/{id}`, gdzie `id` jest parametrem path. ![Parametry path](/docs/_fern-img/12dde95654a12f8fd5894eefe2bdbebb8b819072d3589ed32ddd578997f53c1d.webp) #### Parametry body Określ parametry body, które należy uwzględnić w żądaniu. ![Parametry body](/docs/_fern-img/17627460d24323cc40f461196625d34a5825dbe85d684618be0bc46b11ff9205.webp) ### Typ treści Skonfiguruj format kodowania body żądania: * **JSON** (domyślnie): wysyła parametry body jako `application/json` * **Kodowanie URL**: wysyła parametry body jako `application/x-www-form-urlencoded` Format kodowany URL przydaje się podczas integracji z API wymagającymi przesyłania danych formularza, na przykład: * Starsze systemy, które akceptują tylko żądania kodowane jako formularz * Endpointy tokenów OAuth * API do przetwarzania płatności * Integracje innych firm o określonych wymaganiach dotyczących typu treści > **Info** > > Ustawienie typu treści dotyczy tylko żądań POST, PUT i PATCH z parametrami body. #### Parametry query Określ parametry query, które należy uwzględnić w żądaniu. ![Parametry query](/docs/_fern-img/4127f87fe066cdaa71df0e6f75caa24ec8174e7d156c74b3c62ea9df98b9712e.webp) #### Dynamiczne przypisywanie zmiennych Określ dynamiczne zmienne do aktualizacji na podstawie odpowiedzi narzędzia, aby użyć ich później w rozmowie. ![Parametry query](/docs/_fern-img/95ff0cae8613eafa8bc4312e7cafa39ac0eab34d2fd2b21f0894a30775366110.webp) ## Przewodnik W tym przewodniku utworzymy asystenta pogodowego, który może podawać informacje o pogodzie w czasie rzeczywistym dla dowolnej lokalizacji. Asystent użyje swojej wiedzy geograficznej, aby przekształcić nazwy lokalizacji we współrzędne i pobrać dokładne dane pogodowe. #### Skonfiguruj narzędzie pogodowe Narzędzie pogodowe wysyła żądania GET do `https://api.open-meteo.com/v1/forecast` z `latitude` i `longitude` jako parametrami path podawanymi przez LLM. #### Dodaj w panelu W sekcji **Agent** na stronie ustawień agenta wybierz **Add Tool**. Wybierz **Webhook** jako typ narzędzia, a następnie skonfiguruj integrację z API pogodowym za pomocą tych wartości: | Pole | Wartość | | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Nazwa | get_weather | | Opis | Pobiera aktualną prognozę pogody dla lokalizacji | | Metoda | GET | | URL | [https://api.open-meteo.com/v1/forecast?latitude=\{latitude}\&longitude=\{longitude}\¤t=temperature_2m,wind_speed_10m\&hourly=temperature_2m,relative_humidity_2m,wind_speed_10m](https://api.open-meteo.com/v1/forecast?latitude=\{latitude}\&longitude=\{longitude}\¤t=temperature_2m,wind_speed_10m\&hourly=temperature_2m,relative_humidity_2m,wind_speed_10m) | Dodaj dwa parametry path z typem wartości `LLM Prompt`: | Typ danych | Identyfikator | Opis | | ---------- | ------------- | -------------------------------------------------------- | | string | latitude | Współrzędna szerokości geograficznej żądanej lokalizacji | | string | longitude | Współrzędna długości geograficznej żądanej lokalizacji | #### Dodaj przez CLI #### Utwórz plik konfiguracji narzędzia Zapisz poniższy plik jako `tool_configs/get_weather.json`: ```json { "type": "webhook", "name": "get_weather", "description": "Gets the current weather forecast for a location", "api_schema": { "url": "https://api.open-meteo.com/v1/forecast?current=temperature_2m,wind_speed_10m", "method": "GET", "path_params_schema": { "latitude": { "type": "string", "description": "The latitude coordinate for the requested location" }, "longitude": { "type": "string", "description": "The longitude coordinate for the requested location" } } } } ``` #### Dodaj narzędzie ```bash elevenlabs tools add "get_weather" --type "webhook" --config-path ./tool_configs/get_weather.json ``` #### Odwołaj się do narzędzia w agencie Edytuj `agent_configs/.json` i dodaj ID narzędzia do `conversation_config.agent.prompt.tool_ids`, a następnie wypchnij zmiany: ```bash elevenlabs agents push --agent "" ``` #### Dodaj przez API ```python from elevenlabs import ElevenLabs, ToolRequestModel elevenlabs = ElevenLabs() tool = elevenlabs.conversational_ai.tools.create( request=ToolRequestModel( tool_config={ "type": "webhook", "name": "get_weather", "description": "Gets the current weather forecast for a location", "api_schema": { "url": "https://api.open-meteo.com/v1/forecast?current=temperature_2m,wind_speed_10m", "method": "GET", "path_params_schema": { "latitude": { "type": "string", "description": "The latitude coordinate for the requested location", }, "longitude": { "type": "string", "description": "The longitude coordinate for the requested location", }, }, }, } ) ) elevenlabs.conversational_ai.agents.update( agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6", conversation_config={ "agent": {"prompt": {"tool_ids": [tool.id]}}, }, ) ``` ```typescript import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js"; const elevenlabs = new ElevenLabsClient(); const tool = await elevenlabs.conversationalAi.tools.create({ toolConfig: { type: "webhook", name: "get_weather", description: "Gets the current weather forecast for a location", apiSchema: { url: "https://api.open-meteo.com/v1/forecast?current=temperature_2m,wind_speed_10m", method: "GET", pathParamsSchema: { latitude: { type: "string", description: "The latitude coordinate for the requested location", }, longitude: { type: "string", description: "The longitude coordinate for the requested location", }, }, }, }, }); await elevenlabs.conversationalAi.agents.update("agent_7101k5zvyjhmfg983brhmhkd98n6", { conversationConfig: { agent: { prompt: { toolIds: [tool.id] } }, }, }); ``` > **Warning** > > To narzędzie nie wymaga klucza API. Jeśli jest wymagany, przekaż go w nagłówkach i zapisz jako sekret. #### Koordynacja Skonfiguruj asystenta, aby inteligentnie obsługiwał zapytania o pogodę, używając tego system prompta: **`System prompt`** ```plaintext System prompt You are a helpful conversational agent with access to a weather tool. When users ask about weather conditions, use the get_weather tool to fetch accurate, real-time data. The tool requires a latitude and longitude - use your geographic knowledge to convert location names to coordinates accurately. Never ask users for coordinates - you must determine these yourself. Always report weather information conversationally, referring to locations by name only. For weather requests: 1. Extract the location from the user's message 2. Convert the location to coordinates and call get_weather 3. Present the information naturally and helpfully For non-weather queries, provide friendly assistance within your knowledge boundaries. Always be concise, accurate, and helpful. First message: "Hey, how can I help you today?" ``` > **Success** > > Przetestuj asystenta, pytając o pogodę w różnych lokalizacjach. Asystent powinien > obsługiwać konkretne lokalizacje ("Jaka jest pogoda w Tokio?") i prosić o doprecyzowanie po ogólnych pytaniach ("Jak > wygląda dziś pogoda?"). ## Obsługiwane metody uwierzytelniania ElevenLabs Agents obsługuje wiele metod uwierzytelniania, które pozwalają bezpiecznie łączyć narzędzia z zewnętrznymi API. Metody uwierzytelniania konfigurujesz w ustawieniach agenta, a następnie w razie potrzeby łączysz z poszczególnymi narzędziami. ![Połączenie uwierzytelniania workspace](/docs/_fern-img/131f7e017f01eaba444cddc672efdb77415db1a4c3a39f05b92a1678c5cd68f1.webp) Po konfiguracji możesz połączyć te metody uwierzytelniania z narzędziami i zarządzać własnymi nagłówkami w konfiguracji narzędzia: ![Połączenie uwierzytelniania narzędzia](/docs/_fern-img/c018c5bf11266512a6d6157e33274b1a12f8c20768e5ab18da0f20f933f8aea9.webp) #### OAuth2 Client Credentials Automatycznie obsługuje przepływ OAuth2 client credentials. Skonfiguruj go za pomocą ID klienta, sekretu klienta i URL tokenu (np. `https://api.example.com/oauth/token`). Opcjonalnie określ scope'y jako wartości rozdzielone przecinkami oraz dodatkowe parametry JSON. Aby skonfigurować, kliknij **Add Auth** w **Workspace Auth Connections** w sekcji **Agent** na stronie ustawień agenta. #### OAuth2 JWT Używa uwierzytelniania JSON Web Token dla przepływu OAuth 2.0 JWT Bearer. Wymaga sekretu podpisywania JWT, URL tokenu i algorytmu (domyślnie: HS256). Skonfiguruj deklaracje JWT, w tym wystawcę, odbiorcę i podmiot. Opcjonalnie ustaw ID klucza, czas wygaśnięcia (domyślnie: 3600 sekund), scope'y i dodatkowe parametry. Aby skonfigurować, kliknij **Add Auth** w **Workspace Auth Connections** w sekcji **Agent** na stronie ustawień agenta. #### Uwierzytelnianie podstawowe Proste uwierzytelnianie nazwą użytkownika i hasłem dla API obsługujących HTTP Basic Auth. Aby skonfigurować, kliknij **Add Auth** w **Workspace Auth Connections** w sekcji **Agent** na stronie ustawień agenta. #### Tokeny Bearer Uwierzytelnianie oparte na tokenie, które dodaje wartość tokenu bearer do nagłówka żądania. Skonfiguruj je, dodając nagłówek do konfiguracji narzędzia, wybierając **Secret** jako typ nagłówka i klikając **Create New Secret**. #### Własne nagłówki Dodaj własne nagłówki uwierzytelniania o dowolnej nazwie i wartości dla zastrzeżonych metod uwierzytelniania. Skonfiguruj je, dodając nagłówek do konfiguracji narzędzia i określając jego **name** oraz **value**. ## 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. ## Dźwięki wywołań narzędzi Możesz skonfigurować dźwięk otoczenia odtwarzany podczas działania narzędzia, aby poprawić doświadczenie użytkownika. Dowiedz się więcej o [dźwiękach wywołań narzędzi](/docs/pl/eleven-agents/customization/tools/tool-configuration/tool-call-sounds).