Ferramentas personalizadas

Ferramentas personalizadas permitem escrever suas próprias funções JavaScript e disponibilizá-las como ferramentas invocáveis em blocos Agent. Isso é útil quando você precisa de funcionalidade que as integrações nativas do Zoen não cobrem — por exemplo, chamar uma API interna, fazer um cálculo customizado ou transformar dados de uma forma específica.

Como as ferramentas personalizadas funcionam

Uma ferramenta personalizada tem duas partes:

1. Schema — Uma definição JSON descrevendo o nome, a descrição e os parâmetros da ferramenta (no formato de function-calling da OpenAI). Isso diz ao agente de IA o que a ferramenta faz e quais entradas espera.
2. Code — Um corpo de função JavaScript que roda quando o agente chama a ferramenta. Os parâmetros definidos no schema ficam disponíveis como variáveis no seu código.

Quando um bloco 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 — como nas 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 bloco Agent:

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

Ambiente de código

Recursos disponíveis

• Async/await — Seu código roda em um contexto async, então você pode usar await diretamente
• fetch() — Faça requisições HTTP a APIs externas
• Built-ins do Node.js — Acesso a crypto, Buffer e outros módulos padrão
• Variáveis de ambiente — Use a sintaxe {{KEY}} para injetar segredos

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 — Parâmetros do schema ficam disponíveis diretamente como variáveis (ex.: city), não via 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:

• Buscar ferramentas por nome, nome da função ou descrição
• Editar o schema ou o código de qualquer ferramenta
• Excluir ferramentas que não são mais necessárias

Permissões