> 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. # Client-Tools **Client-Tools** ermöglichen Ihrem Assistenten, clientseitige Funktionen auszuführen. Im Gegensatz zu [Webhook-Tools](/docs/de/eleven-agents/customization/tools/webhook-tools) können Client-Tools Aktionen wie das Auslösen von Browserereignissen, das Ausführen clientseitiger Funktionen oder das Senden von Benachrichtigungen an eine UI durchführen. ## Überblick Anwendungen benötigen möglicherweise Assistenten, die direkt mit der Umgebung des Benutzers interagieren. Clientseitige Tools geben Ihrem Assistenten die Möglichkeit, clientseitige Vorgänge auszuführen. Hier sind einige Beispiele, bei denen Client-Tools nützlich sein können: * **UI-Ereignisse auslösen**: Ermöglichen Sie einem Assistenten, Browserereignisse wie Warnungen, Modals oder Benachrichtigungen auszulösen. * **Mit dem DOM interagieren**: Ermöglichen Sie einem Assistenten, das Document Object Model (DOM) für dynamische Inhaltsaktualisierungen zu bearbeiten oder Benutzer durch komplexe Oberflächen zu führen. > **Info** > > Verwenden Sie zum Aufrufen serverseitiger APIs stattdessen [Webhook- Tools](/docs/de/eleven-agents/customization/tools/webhook-tools). ## Anleitung ### Voraussetzungen * Ein [ElevenLabs-Konto](https://elevenlabs.io) * Ein konfigurierter ElevenLabs Conversational Agent ([hier erstellen](https://elevenlabs.io/app/agents)) #### Neues clientseitiges Tool erstellen Konfigurieren Sie ein Client-Tool namens `logMessage` mit dem erforderlichen String-Parameter `message` ("Die in der Konsole zu protokollierende Nachricht"). #### Über das Dashboard hinzufügen Navigieren Sie zum Dashboard Ihres Agenten. Klicken Sie im Bereich **Tools** auf **Tool hinzufügen**. Stellen Sie sicher, dass der **Tool-Typ** auf **Client** gesetzt ist. Konfigurieren Sie dann Folgendes: | Einstellung | Parameter | | ------------ | ------------------------------------------------------------------------------------------------------- | | Name | logMessage | | Beschreibung | Verwenden Sie dieses clientseitige Tool, um eine Nachricht beim Client des Benutzers zu protokollieren. | Erstellen Sie dann einen neuen Parameter `message` mit der folgenden Konfiguration: | Einstellung | Parameter | | ------------ | --------------------------------------------------------------------------------------------------------------------- | | Datentyp | String | | Bezeichner | message | | Erforderlich | true | | Beschreibung | Die in der Konsole zu protokollierende Nachricht. Stellen Sie sicher, dass die Nachricht informativ und relevant ist. | ![Einrichtung des logMessage-Client-Tools](/docs/_fern-img/f7ed25d49a2a814b76112f3e385d471e0dc8444705e11f2f6fad0bd23f1eae12.webp) #### Über die CLI hinzufügen #### Tool-Konfigurationsdatei erstellen Speichern Sie Folgendes als `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"] } } ``` #### Tool hinzufügen ```bash elevenlabs tools add "logMessage" --type "client" --config-path ./tool_configs/log_message.json ``` #### Tool in Ihrem Agenten referenzieren Bearbeiten Sie `agent_configs/.json`, um die ID des Tools zu `conversation_config.agent.prompt.tool_ids` hinzuzufügen, und übertragen Sie die Änderungen: ```bash elevenlabs agents push --agent "" ``` #### Über die API hinzufügen ```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] } }, }, }); ``` #### Client-Tool in Ihrem Code registrieren Im Gegensatz zu Webhook-Tools müssen Client-Tools in Ihrem Code registriert werden. Verwenden Sie den folgenden Code, um das Client-Tool zu registrieren: **`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** > > Bei den Tool- und Parameternamen in der Agentenkonfiguration wird zwischen Groß- und Kleinschreibung unterschieden. Sie **müssen** mit den in Ihrem Code registrierten Namen übereinstimmen. #### Testen Starten Sie eine Unterhaltung mit Ihrem Agenten und sagen Sie beispielsweise: > *Protokolliere eine Nachricht mit dem Text „Hello World“ in der Konsole* In Ihrer Konsole sollte ein `Hello World`-Log angezeigt werden. #### Nächste Schritte Nachdem Sie ein einfaches clientseitiges Ereignis eingerichtet haben, können Sie: * Komplexere Client-Tools erkunden, etwa zum Öffnen von Modals, Navigieren zu Seiten oder Interagieren mit dem DOM. * Client-Tools mit serverseitigen Webhooks für Full-Stack-Interaktionen kombinieren. * Client-Tools verwenden, um die Benutzerinteraktion zu verbessern und während Unterhaltungen Echtzeit-Feedback bereitzustellen. ### Ergebnisse von Client-Tools an den Unterhaltungskontext übergeben Wenn Ihr Agent Daten von einem Client-Tool zurückerhalten soll, aktivieren Sie in der Tool-Konfiguration die Option **Auf Antwort warten**. ![Option „Auf Antwort warten“ in der Konfiguration des Client-Tools](/docs/_fern-img/0ecc615fc9f25446b67369fd3e010e34b39549a22146a2483ea17251206caf1e.webp) Nachdem das Client-Tool hinzugefügt wurde, wartet der Agent beim Aufruf der Funktion auf deren Antwort und fügt diese dem Unterhaltungskontext hinzu. **`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 }); ``` In diesem Beispiel wird die Funktion auf dem Client ausgeführt, wenn der Agent **getCustomerDetails** aufruft. Der Agent erhält die zurückgegebenen Daten, die dann als Teil des Unterhaltungskontexts verwendet werden. Die Werte aus der Antwort können optional auch dynamischen Variablen zugewiesen werden, ähnlich wie bei [Webhook-Tools](https://elevenlabs.io/docs/eleven-agents/customization/tools/webhook-tools). Beachten Sie, dass System-Tools keine dynamischen Variablen aktualisieren können. ### Fehlerbehebung #### Tools werden nicht ausgelöst * Stellen Sie sicher, dass die Tool- und Parameternamen in der Agentenkonfiguration mit den in Ihrem Code registrierten Namen übereinstimmen. * Sehen Sie sich das Gesprächstranskript im Agenten-Dashboard an, um zu prüfen, ob das Tool ausgeführt wird. #### Konsolenfehler * Öffnen Sie die Browserkonsole, um auf Fehler zu prüfen. * Stellen Sie sicher, dass Ihr Code die notwendige Fehlerbehandlung für nicht definierte oder unerwartete Parameter enthält. ## Best Practices #### Tools intuitiv benennen und detailliert beschreiben Wenn der Assistent nicht die richtigen Tools aufruft, müssen Sie möglicherweise die Namen und Beschreibungen Ihrer Tools aktualisieren, damit der Assistent klarer versteht, wann er welches Tool auswählen soll. Vermeiden Sie Abkürzungen oder Akronyme, um Tool- und Argumentnamen zu verkürzen. Sie können auch detailliert beschreiben, wann ein Tool aufgerufen werden soll. Bei komplexen Tools sollten Sie jedes Argument beschreiben, damit der Assistent weiß, welche Angaben er vom Nutzer erfragen muss. #### Tool-Parameter intuitiv benennen und detailliert beschreiben Verwenden Sie klare und aussagekräftige Namen für Tool-Parameter. Geben Sie in der Beschreibung gegebenenfalls das erwartete Format eines Parameters an (z. B. YYYY-mm-dd oder dd/mm/yy für ein Datum). #### Erwägen Sie, im System-Prompt Ihres Assistenten zusätzliche Informationen dazu bereitzustellen, wie und wann Tools aufgerufen werden sollen Klare Anweisungen in Ihrem System-Prompt können die Genauigkeit von Tool-Aufrufen des Assistenten deutlich verbessern. Leiten Sie den Assistenten beispielsweise mit Anweisungen wie den folgenden an: ```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?'. ``` Geben Sie Kontext für komplexe Szenarien. Zum Beispiel: ```plaintext Before scheduling a meeting with `schedule_meeting`, check the user's calendar for availability using check_availability to avoid conflicts. ``` #### LLM-Auswahl > **Warning** > > Bei der Verwendung von Tools empfehlen wir intelligente Modelle wie GPT 6 oder Claude Sonnet 5.5. Die Wahl des LLM ist entscheidend für den Erfolg von Funktionsaufrufen. Einige LLMs haben möglicherweise Schwierigkeiten, die relevanten Parameter aus dem Gespräch zu extrahieren.