Ferramentas personalizadas

Ferramentas personalizadas permitem que você escreva suas próprias funções JavaScript e as disponibilize como ferramentas chamáveis em blocks Agent. Isso é útil quando você precisa de algo que as integrações nativas do Studio não cobrem — por exemplo, chamar uma API interna, fazer um cálculo específico ou transformar dados de uma forma particular.

Como funcionam as ferramentas personalizadas

Uma ferramenta personalizada tem duas partes:

1. Schema — uma definição JSON que descreve o nome, a descrição e os parâmetros da ferramenta (no formato de function calling da OpenAI). É isso que informa ao agente de IA o que a ferramenta faz e quais entradas ela espera.
2. Código — o corpo de uma função JavaScript que executa quando o agente chama a ferramenta. Os parâmetros definidos no schema ficam disponíveis como variáveis no seu código.

Quando um block Agent tem acesso a uma ferramenta personalizada, o modelo de IA decide quando chamá-la com base na descrição do schema e no contexto da conversa — exatamente como acontece com as ferramentas nativas.

Criando uma ferramenta personalizada

{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "Get the current weather for a city",
    "parameters": {
      "type": "object",
      "properties": {
        "city": {
          "type": "string",
          "description": "The city name"
        },
        "units": {
          "type": "string",
          "enum": ["celsius", "fahrenheit"],
          "description": "Temperature units"
        }
      },
      "required": ["city"]
    }
  }
}

const response = await fetch(
  `https://api.openweathermap.org/data/2.5/weather?q=${city}&units=${units === 'celsius' ? 'metric' : 'imperial'}&appid={{OPENWEATHER_API_KEY}}`
);

const data = await response.json();

return {
  temperature: data.main.temp,
  description: data.weather[0].description,
  humidity: data.main.humidity
};

Usando ferramentas personalizadas em workflows

Depois de criadas, as ferramentas personalizadas aparecem junto com as nativas ao configurar um block Agent:

1. Abra um block Agent
2. Clique em Add Tools
3. Encontre sua ferramenta personalizada na lista de ferramentas
4. O agente chamará a ferramenta quando concluir que ela é relevante para a tarefa

Ambiente de execução do código

Recursos disponíveis

• Async/await — seu código executa em contexto assíncrono, então você pode usar await diretamente
• fetch() — faça requisições HTTP para APIs externas
• Módulos nativos do Node.js — acesso a crypto, Buffer e outros módulos padrão
• Variáveis de ambiente — use a sintaxe {{KEY}} para vincular secrets no momento da execução, sem deixar texto puro no código-fonte

Limitações

• Sem pacotes npm — bibliotecas externas como axios ou lodash não estão disponíveis. Use as APIs nativas
• Parâmetros por nome — os parâmetros do schema ficam disponíveis diretamente como variáveis (por exemplo, city), não em um objeto params

Retornando resultados

Retorne um valor do seu código para enviá-lo de volta ao agente:

const result = await fetch(`https://api.example.com/data?q=${query}`);
const data = await result.json();
return data;

O valor retornado se torna a saída da ferramenta, que o agente vê e pode usar na resposta.

Gerenciando ferramentas personalizadas

Em Settings → Custom Tools você pode:

• Search — buscar ferramentas por nome, nome da função ou descrição
• Edit — editar o schema ou o código de qualquer ferramenta
• Delete — excluir ferramentas que não são mais necessárias

Permissões