> 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 código As **ferramentas de código** permitem que seu agente execute JavaScript personalizado em um ambiente isolado no servidor, sem que você precise criar e hospedar seu próprio endpoint de webhook. Escreva a lógica uma vez no editor de código integrado, e a ElevenLabs a executará sempre que o agente chamar a ferramenta. > **Note** > > Este recurso está disponível apenas no plano Enterprise. ## Visão geral Uma ferramenta de código é uma função JavaScript executada quando o agente a chama. Você escreve todo o corpo da função, então a ferramenta pode fazer tanto quanto — ou tão pouco quanto — a tarefa exigir: * **Cálculos personalizados**: aplique regras de precificação, conversões de unidades, lógica de pontuação ou cálculos de datas usando apenas os parâmetros da chamada da ferramenta. Não é necessário acesso à rede. * **Chamada de APIs externas**: use `fetch` em domínios permitidos, com segredos do workspace e conexões de autenticação inseridos no contexto da função. * **Combinação de várias fontes**: chame duas ou três APIs e una, compare ou reconcilie os resultados antes de retornar uma única resposta. * **Ramificação condicional**: execute lógicas diferentes conforme os parâmetros da chamada da ferramenta, sem precisar de uma ferramenta separada para cada ramificação. * **Reformatação de dados**: retorne exatamente a estrutura que você quer que o agente veja, em vez de uma resposta bruta da fonte. > **Info** > > Para uma única chamada de API externa sem lógica personalizada, as [ferramentas de webhook](/docs/pt/eleven-agents/customization/tools/webhook-tools) normalmente são mais simples de configurar. Para > acionar ações no navegador ou app de um usuário, use as [ferramentas de cliente](/docs/pt/eleven-agents/customization/tools/client-tools). ## Como funciona Seu código é um módulo JavaScript que exporta uma única função assíncrona padrão. A função recebe um objeto `ctx` e retorna o resultado da ferramenta: ```javascript export default async (ctx) => { // ctx.args. — the parameters the agent passed to this tool call const { city } = ctx.args; return { message: `Hello from ${city}!` }; }; ``` O valor retornado se torna o resultado da ferramenta. Ele é enviado de volta ao agente, exibido na transcrição da conversa e pode ser usado para [atribuição dinâmica de variáveis](/docs/pt/eleven-agents/customization/tools/webhook-tools#tool-configuration). ### O objeto `ctx` `ctx` é seu ponto de entrada para tudo o que a ferramenta pode acessar no momento da chamada. Os parâmetros fornecidos pelo agente sempre chegam em `ctx.args`; segredos, valores de configuração e conexões de autenticação são opcionais e aparecem apenas se você mapeá-los na seção **Objeto de contexto** da ferramenta. | Propriedade | Descrição | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `ctx.args` | Os parâmetros da chamada da ferramenta fornecidos pelo agente. | | `ctx.config` | Variáveis de texto simples que você mapeou para o contexto desta ferramenta. | | `ctx.secrets` | Segredos do workspace que você mapeou para o contexto desta ferramenta para uso nos cabeçalhos de solicitação. O segredo bruto nunca é exposto ao seu código; a inserção ocorre na saída e exclusivamente nos cabeçalhos. | | `ctx.auth_connections` | Referências a [conexões de autenticação](/docs/pt/eleven-agents/customization/tools/webhook-tools#supported-authentication-methods) configuradas que você mapeou para o contexto desta ferramenta, para uso no cabeçalho de solicitação `X-With-Auth-Connection`. A credencial subjacente nunca é exposta ao seu código; a inserção ocorre na saída e exclusivamente nos cabeçalhos. | > **Note** > > Apenas `ctx.args` fica visível para o agente quando ele chama a ferramenta. Segredos, valores de configuração e conexões de autenticação nunca são revelados ao agente. #### Configurando parâmetros Os parâmetros são os valores que o agente fornece ao chamar a ferramenta, e eles chegam em `ctx.args`. Defina-os na seção **Parâmetros** do formulário de configuração da ferramenta ou, no editor de código, na aba **Parâmetros**, na subaba **Definir parâmetros**. Cada parâmetro recebe um tipo de dado, um identificador e uma descrição que o agente usa para determinar o valor correto com base na conversa. Seu código lê esse valor pelo identificador, como `ctx.args.appointment_datetime` abaixo. ![Definindo um parâmetro de ferramenta de código](/docs/_fern-img/d492e864ae15f3a355251faae3b719544e1ab56b703c02740b51be6c6769ccf7.webp) #### Configurando o objeto de contexto Adicione segredos, valores de configuração e conexões de autenticação na seção **Objeto de contexto** da ferramenta. Cada entrada recebe um tipo e um nome. O painel mostra o acessador exato de cada entrada, como `ctx.secrets.DEMO_KEY` abaixo. ![Mapeando um segredo do workspace para o objeto de contexto de uma ferramenta de código](/docs/_fern-img/ad58ee53f3591f447b108191aff760f1134350911933b968b06798fa6d42f438.webp) ### Acesso à rede O código executado no ambiente isolado só pode acessar domínios que seu workspace permitiu explicitamente. Adicione os domínios que seu código precisa chamar em **Configurações do ElevenAgents**, em **Acesso à rede para ferramentas de código**. Uma solicitação para qualquer outro domínio falhará. > **Warning** > > Editar o **Acesso à rede para ferramentas de código** exige permissões de administrador do workspace. ### Limites de execução * **Tempo limite**: cada execução deve ser concluída dentro do tempo limite de resposta configurado para a ferramenta, de 1 a 30 segundos. * **Sem pacotes externos**: as ferramentas de código atualmente são executadas sem dependências npm. ### Testando seu código Antes de salvar, use **Executar** no editor de código para executar seu código com valores de parâmetro de exemplo: * **Parâmetros** — defina valores de teste para cada parâmetro que sua ferramenta define. * **Saída** — veja o resultado retornado ou o erro, caso a execução falhe. * **Logs** — veja tudo o que foi gravado com `console.log`, `console.warn` ou `console.error`, além dos tempos de compilação e execução. ## Guia Neste guia, vamos criar uma ferramenta de código que converte uma temperatura e retorna uma string formatada e amigável: #### Crie uma nova ferramenta de código Na seção **Agente** da página de configurações do agente, escolha **Adicionar ferramenta**. Selecione **Código** como o tipo de ferramenta e defina um nome e uma descrição: | Campo | Valor | | --------- | --------------------------------------------------- | | Nome | convert_temperature | | Descrição | Converte uma temperatura entre Celsius e Fahrenheit | #### Defina os parâmetros Adicione dois parâmetros para que o LLM saiba o que fornecer: | Tipo de dado | Identificador | Obrigatório | Descrição | | ------------ | ------------- | ----------- | ----------------------------------- | | number | value | true | O valor da temperatura a converter | | string | from_unit | true | A unidade de origem: `"C"` ou `"F"` | #### Escreva o código Abra o editor de código e substitua o código-fonte padrão por: ```javascript export default async (ctx) => { const { value, from_unit } = ctx.args; if (from_unit === "C") { const fahrenheit = (value * 9) / 5 + 32; return { result: `${value}°C is ${fahrenheit.toFixed(1)}°F` }; } const celsius = ((value - 32) * 5) / 9; return { result: `${value}°F is ${celsius.toFixed(1)}°C` }; }; ``` Use **Executar** com alguns valores de exemplo (por exemplo, `value: 100, from_unit: "C"`) para confirmar a saída antes de salvar. #### Orquestração Atualize o prompt de sistema do seu agente para que ele saiba quando usar a ferramenta: **`Prompt do sistema`** ```plaintext Prompt do sistema When the user asks to convert a temperature, call convert_temperature with the value and its unit ("C" or "F"), and read back the result naturally. ``` #### Teste Inicie uma conversa e experimente: > *Quanto são 100 graus Celsius em Fahrenheit?* O agente deve chamar a ferramenta e informar o valor convertido. ### Exemplos de autenticação **Chamando uma API com um segredo** ```javascript export default async (ctx) => { const { order_id } = ctx.args; const response = await fetch(`https://api.example.com/orders/${order_id}`, { headers: { Authorization: `Bearer ${ctx.secrets.EXAMPLE_API_KEY}`, }, }); if (!response.ok) { throw new Error(`Upstream error: ${response.status}`); } return await response.json(); }; ``` Mapeie `EXAMPLE_API_KEY` para um segredo do workspace na seção **Objeto de contexto** da ferramenta e adicione `api.example.com` ao **Acesso à rede para ferramentas de código** para que a solicitação possa sair. O valor referenciado é um placeholder: o segredo real é substituído no cabeçalho durante a saída e nunca fica visível para seu código. **Chamando uma API com uma conexão de autenticação OAuth** ```javascript export default async (ctx) => { const { customer_id } = ctx.args; const response = await fetch(`https://api.example.com/customers/${customer_id}`, { headers: { "X-With-Auth-Connection": ctx.authConnections.EXAMPLE_CRM, }, }); if (!response.ok) { throw new Error(`Upstream error: ${response.status}`); } return await response.json(); }; ``` Mapeie `EXAMPLE_CRM` para uma [conexão de autenticação](/docs/pt/eleven-agents/customization/tools/webhook-tools#supported-authentication-methods) configurada na seção **Objeto de contexto** da ferramenta. O valor referenciado é um placeholder: a credencial real é substituída no cabeçalho durante a saída e nunca fica visível para seu código. ## 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.