> 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 de webhook As **ferramentas** permitem que seu assistente se conecte a dados e sistemas externos. Você pode definir um conjunto de ferramentas às quais o assistente tem acesso, e ele as usará quando apropriado com base na conversa. ## Visão geral Muitos aplicativos exigem que os assistentes chamem APIs externas para obter informações em tempo real. As ferramentas permitem que seu assistente faça chamadas de funções externas para aplicativos de terceiros, para que você possa obter informações em tempo real. Veja alguns exemplos em que as ferramentas podem ser úteis: * **Busca de dados**: permite que um assistente recupere dados em tempo real de qualquer banco de dados compatível com REST ou integração de terceiros antes de responder ao usuário. * **Realização de ações**: permite que um assistente acione ações autenticadas com base na conversa, como agendar reuniões ou iniciar devoluções de pedidos. > **Info** > > Para interagir com interfaces de aplicativos ou acionar eventos no lado do cliente, use as [ferramentas do cliente](/docs/pt/eleven-agents/customization/tools/client-tools). ## Configuração de ferramentas Os agentes da ElevenLabs podem ser equipados com ferramentas para interagir com APIs externas. Ao contrário das solicitações tradicionais, o assistente gera parâmetros de consulta, corpo e caminho dinamicamente com base na conversa e nas descrições de parâmetros fornecidas por você. Todas as configurações de ferramentas e descrições de parâmetros ajudam o assistente a determinar **quando** e **como** usar essas ferramentas. Para orquestrar o uso de ferramentas de forma eficaz, atualize o prompt de sistema do assistente para especificar a sequência e a lógica dessas chamadas. Isso inclui: * **Qual ferramenta** usar e em quais condições. * **Quais parâmetros** a ferramenta precisa para funcionar corretamente. * **Como lidar** com as respostas. \ #### Configuração Defina um `Nome` e uma `Descrição` de alto nível para descrever a finalidade da ferramenta. Isso ajuda o LLM a entender a ferramenta e saber quando chamá-la. > **Info** > > Se a API exigir parâmetros de caminho, inclua variáveis no caminho da URL envolvendo-as em chaves > `{}`, por exemplo: `/api/resource/{id}`, em que `id` é um parâmetro de caminho. ![Configuração](/docs/_fern-img/fb6e6619e4e7a5f19c2a86f9c2a489f5cb33cfb0883c14a06f0eec3cb35d71d5.webp) #### Autenticação Configure a autenticação adicionando cabeçalhos personalizados ou usando métodos de autenticação prontos por meio de conexões de autenticação. ![Autenticação da ferramenta](/docs/_fern-img/5ffae070945a86b74975cd9b56679c2bb76f0ce70d05fe7b10e8e5dff6ddd630.webp) #### Cabeçalhos Especifique todos os cabeçalhos que precisam ser incluídos na solicitação. ![Cabeçalhos](/docs/_fern-img/9c8c3f2d42f84a6e40922a4c777199e79646b174fa51b9e4d5b21695d7da3f66.webp) #### Parâmetros de caminho Inclua variáveis no caminho da URL envolvendo-as em chaves `{}`: * **Exemplo**: `/api/resource/{id}`, em que `id` é um parâmetro de caminho. ![Parâmetros de caminho](/docs/_fern-img/12dde95654a12f8fd5894eefe2bdbebb8b819072d3589ed32ddd578997f53c1d.webp) #### Parâmetros do corpo Especifique todos os parâmetros do corpo que devem ser incluídos na solicitação. ![Parâmetros do corpo](/docs/_fern-img/17627460d24323cc40f461196625d34a5825dbe85d684618be0bc46b11ff9205.webp) ### Tipo de conteúdo Configure o formato de codificação do corpo da solicitação: * **JSON** (padrão): envia parâmetros do corpo como `application/json` * **Codificado em URL**: envia parâmetros do corpo como `application/x-www-form-urlencoded` O formato codificado em URL é útil ao integrar APIs que exigem o envio de dados de formulário, como: * Sistemas legados que aceitam apenas solicitações codificadas em formulário * Endpoints de token OAuth * APIs de processamento de pagamentos * Integrações de terceiros com requisitos específicos de tipo de conteúdo > **Info** > > A configuração de tipo de conteúdo se aplica apenas a solicitações POST, PUT e PATCH com parâmetros de corpo. #### Parâmetros de consulta Especifique todos os parâmetros de consulta que devem ser incluídos na solicitação. ![Parâmetros de consulta](/docs/_fern-img/4127f87fe066cdaa71df0e6f75caa24ec8174e7d156c74b3c62ea9df98b9712e.webp) #### Atribuição de variáveis dinâmicas Especifique variáveis dinâmicas a serem atualizadas a partir da resposta da ferramenta para uso posterior na conversa. ![Parâmetros de consulta](/docs/_fern-img/95ff0cae8613eafa8bc4312e7cafa39ac0eab34d2fd2b21f0894a30775366110.webp) ## Guia Neste guia, criaremos um assistente meteorológico que pode fornecer informações sobre o tempo em tempo real para qualquer local. O assistente usará seu conhecimento geográfico para converter nomes de locais em coordenadas e buscar dados meteorológicos precisos. #### Configure a ferramenta de previsão do tempo A ferramenta de previsão do tempo envia solicitações GET para `https://api.open-meteo.com/v1/forecast` com `latitude` e `longitude` como parâmetros de caminho fornecidos pelo LLM. #### Adicionar pelo painel Na seção **Agente** da página de configurações do seu agente, escolha **Adicionar ferramenta**. Selecione **Webhook** como o tipo de ferramenta e configure a integração com a API meteorológica com estes valores: | Campo | Valor | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Nome | get_weather | | Descrição | Obtém a previsão do tempo atual para um local | | Método | 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) | Adicione dois parâmetros de caminho com o tipo de valor `LLM Prompt`: | Tipo de dados | Identificador | Descrição | | ------------- | ------------- | --------------------------------------------- | | string | latitude | A coordenada de latitude do local solicitado | | string | longitude | A coordenada de longitude do local solicitado | #### Adicionar pela CLI #### Crie um arquivo de configuração da ferramenta Salve o conteúdo a seguir como `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" } } } } ``` #### Adicione a ferramenta ```bash elevenlabs tools add "get_weather" --type "webhook" --config-path ./tool_configs/get_weather.json ``` #### Faça referência à ferramenta no seu agente Edite `agent_configs/.json` e adicione o ID da ferramenta a `conversation_config.agent.prompt.tool_ids`. Em seguida, 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": "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** > > Uma chave de API não é necessária para esta ferramenta. Se for necessária, ela deve ser enviada nos cabeçalhos e armazenada como um segredo. #### Orquestração Configure seu assistente para lidar de forma inteligente com consultas sobre o tempo usando este prompt de sistema: **`Prompt do sistema`** ```plaintext Prompt do sistema 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** > > Teste seu assistente perguntando sobre o tempo em diferentes locais. O assistente deve lidar > com locais específicos ("Como está o tempo em Tóquio?") e pedir esclarecimentos após consultas gerais ("Como > está o tempo hoje?"). ## Métodos de autenticação compatíveis O ElevenLabs Agents oferece suporte a vários métodos de autenticação para conectar suas ferramentas a APIs externas com segurança. Os métodos de autenticação são configurados nas configurações do seu agente e, depois, conectados a ferramentas individuais conforme necessário. ![Conexão de autenticação do espaço de trabalho](/docs/_fern-img/131f7e017f01eaba444cddc672efdb77415db1a4c3a39f05b92a1678c5cd68f1.webp) Depois de configurados, você pode conectar esses métodos de autenticação às suas ferramentas e gerenciar cabeçalhos personalizados na configuração da ferramenta: ![Conexão de autenticação da ferramenta](/docs/_fern-img/c018c5bf11266512a6d6157e33274b1a12f8c20768e5ab18da0f20f933f8aea9.webp) #### Credenciais de cliente OAuth2 Gerencia automaticamente o fluxo de credenciais de cliente OAuth2. Configure com seu ID de cliente, segredo de cliente e URL do token (por exemplo, `https://api.example.com/oauth/token`). Opcionalmente, especifique escopos como valores separados por vírgulas e parâmetros JSON adicionais. Configure clicando em **Adicionar autenticação** em **Conexões de autenticação do espaço de trabalho**, na seção **Agente** da página de configurações do seu agente. #### OAuth2 JWT Usa autenticação JSON Web Token para o fluxo OAuth 2.0 JWT Bearer. Exige seu segredo de assinatura JWT, URL do token e algoritmo (padrão: HS256). Configure as declarações JWT, incluindo emissor, público e sujeito. Opcionalmente, defina o ID da chave, a expiração (padrão: 3.600 segundos), escopos e parâmetros extras. Configure clicando em **Adicionar autenticação** em **Conexões de autenticação do espaço de trabalho**, na seção **Agente** da página de configurações do seu agente. #### Autenticação básica Autenticação simples de nome de usuário e senha para APIs que oferecem suporte a HTTP Basic Auth. Configure clicando em **Adicionar autenticação** em **Conexões de autenticação do espaço de trabalho**, na seção **Agente** da página de configurações do seu agente. #### Tokens Bearer Autenticação baseada em token que adiciona o valor do seu token bearer ao cabeçalho da solicitação. Configure adicionando um cabeçalho à configuração da ferramenta, selecionando **Segredo** como o tipo de cabeçalho e clicando em **Criar novo segredo**. #### Cabeçalhos personalizados Adicione cabeçalhos de autenticação personalizados com qualquer nome e valor para métodos de autenticação proprietários. Configure adicionando um cabeçalho à configuração da ferramenta e especificando seu **nome** e **valor**. ## 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. ## Sons de chamadas de ferramentas Você pode configurar áudio ambiente para tocar durante a execução da ferramenta e melhorar a experiência do usuário. Saiba mais sobre [Sons de chamadas de ferramentas](/docs/pt/eleven-agents/customization/tools/tool-configuration/tool-call-sounds).