> 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 klienta **Narzędzia klienta** pozwalają asystentowi wykonywać funkcje po stronie klienta. W przeciwieństwie do [narzędzi webhook](/docs/pl/eleven-agents/customization/tools/webhook-tools), narzędzia klienta pozwalają asystentowi wykonywać działania takie jak wywoływanie zdarzeń przeglądarki, uruchamianie funkcji po stronie klienta czy wysyłanie powiadomień do UI. ## Omówienie Aplikacje mogą wymagać, aby asystenci bezpośrednio wchodzili w interakcję ze środowiskiem użytkownika. Narzędzia po stronie klienta umożliwiają asystentowi wykonywanie takich działań. Oto kilka przykładów, w których narzędzia klienta mogą się przydać: * **Wywoływanie zdarzeń UI**: Pozwól asystentowi wywoływać zdarzenia przeglądarki, takie jak alerty, modale lub powiadomienia. * **Interakcja z DOM**: Umożliw asystentowi manipulowanie Document Object Model (DOM), aby dynamicznie aktualizować treść lub prowadzić użytkowników przez złożone interfejsy. > **Info** > > Aby wywoływać API po stronie serwera, użyj zamiast tego [narzędzi webhook](/docs/pl/eleven-agents/customization/tools/webhook-tools). ## Przewodnik ### Wymagania wstępne * [Konto ElevenLabs](https://elevenlabs.io) * Skonfigurowany Agent Konwersacyjny ElevenLabs ([utwórz go tutaj](https://elevenlabs.io/app/agents)) #### Utwórz nowe narzędzie po stronie klienta Skonfiguruj narzędzie klienta o nazwie `logMessage` z wymaganym parametrem tekstowym `message` ("Wiadomość do zapisania w konsoli"). #### Dodaj przez panel Przejdź do panelu agenta. W sekcji **Tools** kliknij **Add Tool**. Upewnij się, że **Tool Type** jest ustawione na **Client**. Następnie skonfiguruj: | Ustawienie | Parametr | | ---------- | ------------------------------------------------------------------------------------- | | Nazwa | logMessage | | Opis | Użyj tego narzędzia po stronie klienta, aby zapisać wiadomość w kliencie użytkownika. | Następnie utwórz parametr `message` z poniższą konfiguracją: | Ustawienie | Parametr | | ------------- | ------------------------------------------------------------------------------ | | Typ danych | String | | Identyfikator | message | | Wymagane | true | | Opis | Wiadomość do zapisania w konsoli. Upewnij się, że jest informacyjna i istotna. | ![konfiguracja narzędzia klienta logMessage](/docs/_fern-img/f7ed25d49a2a814b76112f3e385d471e0dc8444705e11f2f6fad0bd23f1eae12.webp) #### Dodaj przez CLI #### Utwórz plik konfiguracji narzędzia Zapisz poniższą zawartość jako `tool_configs/log_message.json`: ```json { "type": "client", "name": "logMessage", "description": "Use this client-side tool to log a message to the user's client.", "expects_response": false, "parameters": { "type": "object", "properties": { "message": { "type": "string", "description": "The message to log in the console." } }, "required": ["message"] } } ``` #### Dodaj narzędzie ```bash elevenlabs tools add "logMessage" --type "client" --config-path ./tool_configs/log_message.json ``` #### Dodaj narzędzie do agenta Edytuj `agent_configs/.json`, aby dodać ID narzędzia do `conversation_config.agent.prompt.tool_ids`, a następnie prześlij 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": "client", "name": "logMessage", "description": "Use this client-side tool to log a message to the user's client.", "expects_response": False, "parameters": { "type": "object", "properties": { "message": { "type": "string", "description": "The message to log in the console.", } }, "required": ["message"], }, } ) ) 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: "client", name: "logMessage", description: "Use this client-side tool to log a message to the user's client.", expectsResponse: false, parameters: { type: "object", properties: { message: { type: "string", description: "The message to log in the console.", }, }, required: ["message"], }, }, }); await elevenlabs.conversationalAi.agents.update("agent_7101k5zvyjhmfg983brhmhkd98n6", { conversationConfig: { agent: { prompt: { toolIds: [tool.id] } }, }, }); ``` #### Zarejestruj narzędzie klienta w kodzie W przeciwieństwie do narzędzi webhook narzędzia klienta trzeba zarejestrować w kodzie. Użyj poniższego kodu, aby zarejestrować narzędzie klienta: **`Python`** ```python title="Python" focus={4-16} from elevenlabs import ElevenLabs from elevenlabs.conversational_ai.conversation import Conversation, ClientTools def log_message(parameters): message = parameters.get("message") print(message) client_tools = ClientTools() client_tools.register("logMessage", log_message) conversation = Conversation( client=ElevenLabs(api_key="your-api-key"), agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6", requires_auth=True, client_tools=client_tools, # ... ) conversation.start_session() ``` **`JavaScript`** ```javascript title="JavaScript" focus={2-10} // ... const conversation = await Conversation.startSession({ // ... clientTools: { logMessage: async ({message}) => { console.log(message); } }, // ... }); ``` **`Swift`** ```swift title="Swift" focus={2-10} // ... var clientTools = ElevenLabsSDK.ClientTools() clientTools.register("logMessage") { parameters async throws -> String? in guard let message = parameters["message"] as? String else { throw ElevenLabsSDK.ClientToolError.invalidParameters } print(message) return message } ``` > **Note** > > Nazwy narzędzia i parametrów w konfiguracji agenta rozróżniają wielkość liter i **muszą** odpowiadać nazwom zarejestrowanym w kodzie. #### Testowanie Rozpocznij rozmowę z agentem i powiedz na przykład: > *Zapisz w konsoli wiadomość Hello World* W konsoli powinien pojawić się log `Hello World`. #### Kolejne kroki Po skonfigurowaniu podstawowego zdarzenia po stronie klienta możesz: * Poznać bardziej złożone narzędzia klienta, takie jak otwieranie modali, przechodzenie do stron czy interakcja z DOM. * Łączyć narzędzia klienta z webhookami po stronie serwera, aby tworzyć interakcje full-stack. * Używać narzędzi klienta, aby zwiększać zaangażowanie użytkowników i zapewniać informacje zwrotne w czasie rzeczywistym podczas rozmów. ### Przekazywanie wyników narzędzia klienta do kontekstu rozmowy Jeśli chcesz, aby agent otrzymywał dane zwracane przez narzędzie klienta, zaznacz opcję **Wait for response** w konfiguracji narzędzia. ![Opcja oczekiwania na odpowiedź w konfiguracji narzędzia klienta](/docs/_fern-img/0ecc615fc9f25446b67369fd3e010e34b39549a22146a2483ea17251206caf1e.webp) Po dodaniu narzędzia klienta agent będzie czekać na odpowiedź po wywołaniu funkcji i doda ją do kontekstu rozmowy. **`Python`** ```python title="Python" def get_customer_details(): # Fetch customer details (e.g., from an API or database) customer_data = { "id": 123, "name": "Alice", "subscription": "Pro" } # Return the customer data; it can also be a JSON string if needed. return customer_data client_tools = ClientTools() client_tools.register("getCustomerDetails", get_customer_details) conversation = Conversation( client=ElevenLabs(api_key="your-api-key"), agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6", requires_auth=True, client_tools=client_tools, # ... ) conversation.start_session() ``` **`JavaScript`** ```javascript title="JavaScript" const clientTools = { getCustomerDetails: async () => { // Fetch customer details (e.g., from an API) const customerData = { id: 123, name: "Alice", subscription: "Pro" }; // Return data directly to the agent. return customerData; } }; // Start the conversation with client tools configured. const conversation = await Conversation.startSession({ clientTools }); ``` W tym przykładzie, gdy agent wywoła **getCustomerDetails**, funkcja wykona się po stronie klienta, a agent otrzyma zwrócone dane, które zostaną użyte jako część kontekstu rozmowy. Wartości z odpowiedzi można też opcjonalnie przypisać do zmiennych dynamicznych, podobnie jak w przypadku [narzędzi webhook](https://elevenlabs.io/docs/eleven-agents/customization/tools/webhook-tools). Pamiętaj, że narzędzia systemowe nie mogą aktualizować zmiennych dynamicznych. ### Rozwiązywanie problemów #### Narzędzia nie są wywoływane * Upewnij się, że nazwy narzędzia i parametrów w konfiguracji agenta odpowiadają nazwom zarejestrowanym w kodzie. * Wyświetl transkrypcję rozmowy w panelu agenta, aby sprawdzić, czy narzędzie jest wykonywane. #### Błędy konsoli * Otwórz konsolę przeglądarki, aby sprawdzić błędy. * Upewnij się, że kod zawiera niezbędną obsługę błędów dla niezdefiniowanych lub nieoczekiwanych parametrów. ## 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.