> 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. # Ferramentas do cliente As **ferramentas do cliente** permitem que seu assistente execute funções no lado do cliente. Ao contrário das [ferramentas de webhook](/docs/pt/eleven-agents/customization/tools/webhook-tools), as ferramentas do cliente permitem que o assistente realize ações como acionar eventos do navegador, executar funções no lado do cliente ou enviar notificações para uma UI. ## Visão geral As aplicações podem exigir que os assistentes interajam diretamente com o ambiente do usuário. As ferramentas no lado do cliente dão ao seu assistente a capacidade de executar operações nesse lado. Veja alguns exemplos em que as ferramentas do cliente podem ser úteis: * **Acionamento de eventos da UI**: permite que um assistente acione eventos do navegador, como alertas, modais ou notificações. * **Interação com o DOM**: permite que um assistente manipule o Document Object Model (DOM) para atualizações dinâmicas de conteúdo ou para orientar usuários em interfaces complexas. > **Info** > > Para chamar APIs no lado do servidor, use [ferramentas de webhook](/docs/pt/eleven-agents/customization/tools/webhook-tools). ## Guia ### Pré-requisitos * Uma [conta da ElevenLabs](https://elevenlabs.io) * Um Agente Conversacional da ElevenLabs configurado ([crie um aqui](https://elevenlabs.io/app/agents)) #### Crie uma nova ferramenta no lado do cliente Configure uma ferramenta do cliente chamada `logMessage` com um parâmetro de string obrigatório `message` ("A mensagem a registrar no console"). #### Adicionar pelo painel Acesse o painel do seu agente. Na seção **Tools**, clique em **Add Tool**. Verifique se o **Tool Type** está definido como **Client**. Em seguida, configure o seguinte: | Configuração | Parâmetro | | ------------ | ----------------------------------------------------------------------------------------- | | Nome | logMessage | | Descrição | Use esta ferramenta no lado do cliente para registrar uma mensagem no cliente do usuário. | Depois, crie um novo parâmetro `message` com a seguinte configuração: | Configuração | Parâmetro | | ------------- | --------------------------------------------------------------------------------------- | | Tipo de dado | String | | Identificador | message | | Obrigatório | true | | Descrição | A mensagem a registrar no console. Garanta que a mensagem seja informativa e relevante. | ![configuração da ferramenta do cliente logMessage](/docs/_fern-img/f7ed25d49a2a814b76112f3e385d471e0dc8444705e11f2f6fad0bd23f1eae12.webp) #### Adicionar pela CLI #### Crie um arquivo de configuração da ferramenta Salve o conteúdo a seguir como `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"] } } ``` #### Adicione a ferramenta ```bash elevenlabs tools add "logMessage" --type "client" --config-path ./tool_configs/log_message.json ``` #### Faça referência à ferramenta no seu agente Edite `agent_configs/.json` para adicionar o ID da ferramenta a `conversation_config.agent.prompt.tool_ids` e envie: ```bash elevenlabs agents push --agent "" ``` #### Adicionar pela 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] } }, }, }); ``` #### Registre a ferramenta do cliente no seu código Ao contrário das ferramentas de webhook, as ferramentas do cliente precisam ser registradas no seu código. Use o código a seguir para registrar a ferramenta do cliente: **`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** > > Os nomes da ferramenta e dos parâmetros na configuração do agente diferenciam maiúsculas de minúsculas e **devem** corresponder aos registrados no seu código. #### Teste Inicie uma conversa com seu agente e diga algo como: > *Registre no console uma mensagem dizendo Olá, mundo* Você verá um registro `Hello World` aparecer no seu console. #### Próximas etapas Agora que você configurou um evento básico no lado do cliente, é possível: * Explorar ferramentas do cliente mais complexas, como abrir modais, navegar para páginas ou interagir com o DOM. * Combinar ferramentas do cliente com webhooks no lado do servidor para interações full-stack. * Usar ferramentas do cliente para aumentar o engajamento dos usuários e fornecer feedback em tempo real durante as conversas. ### Como enviar resultados de ferramentas do cliente ao contexto da conversa Quando quiser que seu agente receba dados de volta de uma ferramenta do cliente, marque a opção **Wait for response** na configuração da ferramenta. ![Opção Wait for response na configuração da ferramenta do cliente](/docs/_fern-img/0ecc615fc9f25446b67369fd3e010e34b39549a22146a2483ea17251206caf1e.webp) Depois que a ferramenta do cliente for adicionada, quando a função for chamada, o agente aguardará a resposta e a incluirá no contexto da conversa. **`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 }); ``` Neste exemplo, quando o agente chama **getCustomerDetails**, a função é executada no cliente e o agente recebe os dados retornados, que são usados como parte do contexto da conversa. Os valores da resposta também podem, opcionalmente, ser atribuídos a variáveis dinâmicas, de forma semelhante às [ferramentas de webhook](https://elevenlabs.io/docs/eleven-agents/customization/tools/webhook-tools). Observe que as ferramentas do sistema não podem atualizar variáveis dinâmicas. ### Solução de problemas #### As ferramentas não são acionadas * Verifique se os nomes da ferramenta e dos parâmetros na configuração do agente correspondem aos registrados no seu código. * Consulte a transcrição da conversa no painel do agente para confirmar que a ferramenta está sendo executada. #### Erros no console * Abra o console do navegador para verificar se há erros. * Verifique se seu código tem o tratamento de erros necessário para parâmetros indefinidos ou inesperados. ## Boas práticas #### Dê nomes intuitivos às ferramentas e inclua descrições detalhadas Se o assistente não estiver fazendo chamadas para as ferramentas corretas, talvez seja necessário atualizar os nomes e as descrições das ferramentas para que ele entenda com mais clareza quando deve selecionar cada uma. Evite usar abreviações ou siglas para encurtar nomes de ferramentas e argumentos. Você também pode incluir descrições detalhadas de quando uma ferramenta deve ser chamada. Para ferramentas complexas, inclua descrições para cada argumento para ajudar o assistente a saber o que precisa pedir ao usuário para obter esse argumento. #### Dê nomes intuitivos aos parâmetros das ferramentas e inclua descrições detalhadas Use nomes claros e descritivos para os parâmetros das ferramentas. Quando aplicável, especifique na descrição o formato esperado de um parâmetro (por exemplo, AAAA-mm-dd ou dd/mm/aa para uma data). #### Considere fornecer informações adicionais sobre como e quando chamar ferramentas no prompt de sistema do seu assistente Fornecer instruções claras no prompt de sistema pode melhorar significativamente a precisão das chamadas de ferramenta do assistente. Por exemplo, oriente o assistente com instruções como estas: ```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?'. ``` Forneça contexto para cenários complexos. Por exemplo: ```plaintext Before scheduling a meeting with `schedule_meeting`, check the user's calendar for availability using check_availability to avoid conflicts. ``` #### Seleção de LLM > **Warning** > > Ao usar ferramentas, recomendamos escolher modelos de alta capacidade, como GPT 6 ou Claude Sonnet 5.5. É importante observar que a escolha do LLM influencia o sucesso das chamadas de função. Alguns LLMs podem ter dificuldade para extrair os parâmetros relevantes da conversa.