Ferramentas de código

Ferramentas de código permitem que seu agente execute JavaScript personalizado em um ambiente isolado no servidor, sem que você precise configurar 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.

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, portanto a ferramenta pode fazer tanto quanto ou tão pouco quanto a tarefa exigir:

• Cálculos personalizados: aplique regras de preços, conversões de unidades, lógica de pontuação ou cálculos de datas usando apenas os parâmetros de 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 concilie os resultados antes de retornar uma única resposta.
• Ramificação condicional: execute lógicas diferentes dependendo dos parâmetros de 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 do serviço de origem.

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:

export default async (ctx) => {
  // ctx.args.<paramName> — 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.

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 somente se você os mapear na seção Context object da ferramenta.

Configuração de 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 Parameters do formulário de configuração da ferramenta ou, no editor de código, na aba Params, na subaba Define Params. Cada parâmetro tem 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.

Configuração do objeto de contexto

Adicione segredos, valores de configuração e conexões de autenticação na seção Context object da ferramenta. Cada entrada tem um tipo e um nome. O painel mostra o acessador exato para cada entrada, como ctx.secrets.DEMO_KEY abaixo.

Acesso à rede

O código executado no sandbox só pode acessar domínios que seu workspace permitiu explicitamente. Adicione os domínios que seu código precisa chamar em General Settings do seu workspace, em Code tool allowed domains. Uma solicitação para qualquer outro domínio falhará.

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: no momento, as ferramentas de código são executadas sem dependências do npm.

Teste do seu código

Antes de salvar, use Run no editor de código para executar seu código com valores de parâmetro de exemplo:

• Params — defina valores de teste para cada parâmetro que sua ferramenta define.
• Output — veja o resultado retornado ou o erro, caso a execução falhe.
• Logs — veja tudo o que foi escrito com console.log, console.warn ou console.error, além dos tempos de compilação e execução.

Guia

Neste guia, criaremos uma ferramenta de código que converte uma temperatura e retorna uma string formatada e amigável:

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` };
};

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.

Exemplos de autenticação

Chamar uma API com um segredo

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 Context object da ferramenta e adicione api.example.com a Code tool allowed domains para que a solicitação tenha permissão de saída. O valor que você referencia é um placeholder: o segredo real é substituído no cabeçalho na saída e nunca fica visível para seu código.

Chamar uma API com uma conexão de autenticação OAuth

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 configurada na seção Context object da ferramenta. O valor que você referencia é um placeholder: a credencial real é substituída no cabeçalho na saída e nunca fica visível para seu código.

Boas práticas

Nomeie as ferramentas de forma intuitiva e com descrições detalhadas

Se o assistente não estiver fazendo chamadas às 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 os nomes das ferramentas e dos argumentos.

Você também pode incluir descrições detalhadas sobre quando uma ferramenta deve ser chamada. Para ferramentas complexas, inclua descrições de cada argumento para ajudar o assistente a saber o que precisa perguntar ao usuário para coletar esse argumento.

Nomeie os parâmetros das ferramentas de forma intuitiva e com descrições detalhadas

Use nomes claros e descritivos para os parâmetros das ferramentas. Quando aplicável, especifique na descrição o formato esperado para um parâmetro (por exemplo, YYYY-mm-dd ou dd/mm/yy para uma data).

Considere fornecer informações adicionais sobre como e quando chamar ferramentas no prompt do sistema do seu assistente

Fornecer instruções claras no prompt do sistema pode melhorar significativamente a precisão das chamadas de ferramentas do assistente. Por exemplo, oriente o assistente com instruções como estas:

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:

Before scheduling a meeting with `schedule_meeting`, check the user's calendar for availability using check_availability to avoid conflicts.

Seleção de LLM

É 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.