Ferramenta de Código Personalizado n8n

Quando Usar

Use esta habilidade especificamente para código executado pela Ferramenta de Código Personalizado n8n que pode ser chamada por um agente de IA. Use as habilidades separadas de Código JavaScript ou Código Python para nós de Código de fluxo de trabalho comuns.

Não codifique segredos diretamente e não aceite código executável arbitrário de entradas não confiáveis. Restrinja as entradas com um esquema, valide as saídas, permita apenas destinos de rede específicos e pergunte antes de testar uma ferramenta cujo código pode escrever dados ou invocar um serviço externo.

Orientação especializada para escrever código dentro de @n8n/n8n-nodes-langchain.toolCode — a ferramenta que um Agente de IA pode invocar, não o nó de Código regular do fluxo de trabalho.

⚠️ Isso NÃO é o nó de Código

A Ferramenta de Código Personalizado se parece com um nó de Código no editor — mesmo editor JavaScript, layout semelhante — mas é um nó completamente diferente de um pacote diferente com um contrato de tempo de execução diferente.

Se você tratá-lo como um nó de Código, ele falhará. O restante desta habilidade cobre o contrato real da Ferramenta de Código.

Início Rápido

Ferramenta de Código Personalizado JavaScript Mínima

// `query` is whatever the AI sent (a string by default)
return `You asked: ${query}`;

Ferramenta de Código Personalizado Python Mínima

# `_query` is whatever the AI sent (a string by default)
return f"You asked: {_query}"

Regras Essenciais

1. Retorne uma string. Números são convertidos automaticamente. Qualquer outra coisa gera um "The response property should be a string, but it is an object".
2. Variável de entrada é fixa: query (JS), _query (Python). Você não pode renomeá-la.
3. NÃO use $fromAI() dentro do sandbox da Ferramenta de Código — ele gera "No execution data available".
4. NÃO use o formato de retorno [{json: {...}}] — isso é para nós de Código. Gera "Wrong output type returned".
5. Use um nome de ferramenta descritivo (letras/números/sublinhados, v1.1+). O agente chama a ferramenta pelo seu nome.
6. Escreva uma descrição precisa — o LLM decide se invoca a ferramenta com base nela.

Os Dois Modos de Entrada

A Ferramenta de Código tem duas formas de entrada, controladas por specifyInputSchema:

Modo 1: Não Estruturado (padrão, specifyInputSchema: false)

A IA passa uma única string como query. Se você precisar de vários campos, a IA terá que colocá-los nessa única string e você os analisará. Na prática, os LLMs passarão felizmente uma string JSON se sua descrição instruir a fazê-lo.

// Parse a JSON string the AI sent
let params;
try {
  params = typeof query === 'string' ? JSON.parse(query) : query;
} catch (e) {
  throw new Error('Expected a JSON object. Parser said: ' + e.message);
}
const price = Number(params.price);
const months = Number(params.months);
// ...
return JSON.stringify({ monthly_payment: /* ... */ });

Prós: mais simples de configurar, um campo para descrever. Contras: sem validação de esquema — se o LLM esquecer um campo, a ferramenta falhará em tempo de execução.

Melhor para: protótipos rápidos, ferramentas com uma entrada natural (uma pergunta, um URL, um bloco de texto).

Modo 2: Estruturado (specifyInputSchema: true)

A ferramenta se torna uma DynamicStructuredTool LangChain. O LLM vê um esquema de argumento tipado e passa um objeto validado como query. Você acessa os campos diretamente.

// query is now an object matching your schema
const price = query.price;
const months = query.months;
const residual_percent = query.residual_percent;

const monthly = computeAnnuity(price, months, residual_percent);
return JSON.stringify({ monthly_payment: monthly });

O esquema é definido por meio de:

• schemaType: "fromJson" + jsonSchemaExample (n8n v≥1.3) — cole um exemplo JSON, o n8n infere o esquema
• schemaType: "manual" + inputSchema — escreva um JSON Schema completo você mesmo

Prós: LLM recebe dicas de tipo, chamadas inválidas rejeitadas antes que seu código seja executado, código mais limpo.

…