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.

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.

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 apenas se você mapeá-los na seção Objeto de contexto da ferramenta.

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.

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.

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

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:

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

Chamando 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 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

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 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:

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.