Write custom code tools for n8n AI agents

n8n Custom Code Tool explains the runtime contract for code that an AI Agent invokes through @n8n/n8n-nodes-langchain.toolCode. It focuses on local deterministic computation such as arithmetic, parsing, formatting, validation, and lightweight transformations. Although the editor resembles a regular Code node, the invocation, inputs, outputs, helpers, and state are different.

The tool receives JavaScript input through the fixed query variable and Python input through _query. It returns a string as the agent's observation. Numbers are converted to strings, but raw objects, arrays, and workflow item arrays do not satisfy the documented return contract. Structured results should be serialized as JSON strings. A minimal JavaScript tool body is:

return `You asked: ${query}`;

Use it when an agent needs inline computation that should be performed deterministically rather than improvised in a language response. Use separate JavaScript or Python Code-node guidance for ordinary workflow Code nodes. That node consumes item streams and returns workflow items, so copying its data-access patterns into the tool fails.

The Code Tool sandbox does not expose $input, $node, $json, $binary, $jmespath, this.helpers.httpRequest, getContext, or $getWorkflowStaticData. It also does not expose $fromAI, despite being callable by an agent. DateTime from Luxon is available in the documented JavaScript sandbox, but installed-version behavior still needs verification.

For an external API call, use HTTP Request Tool. For reusable multi-step logic needing other workflow nodes, helpers, or typed parameter bindings, consider toolWorkflow, the Call Sub-workflow Tool. MCP or database tools provide persistent-state alternatives. Static review cannot prove runtime permissions, network access, or external-service behavior, and this skill does not authorize arbitrary execution or production-data tests.

Unstructured mode uses specifyInputSchema set to false and receives a single string. A description can show an expected JSON-string example, but parsing and field checks remain necessary. Structured mode sets specifyInputSchema to true and exposes a typed object through LangChain DynamicStructuredTool. The schema can be inferred from a JSON example through schemaType fromJson and jsonSchemaExample, or supplied manually through inputSchema. Schema support depends on the installed node; typeVersion is not the n8n application release.

Schema hints do not replace business validation. Numeric inputs need finite-value and domain checks, not just coercion. The illustrative car-loan calculator models nominal annuity and balloon payments, not statutory APR or lending advice. Real contracts need exact minor-unit rounding, fee timing, rate conventions, and compatible principal and balloon assumptions. The displayed currency and whole-unit rounding are examples rather than universal financial rules.

Errors can be thrown or returned as informative strings. Messages should identify the invalid field and a valid call shape rather than simply say invalid input. The documented failures distinguish unavailable execution data from $fromAI use, Wrong output type returned from workflow arrays, and the string-property error from raw objects or arrays. Agent retries are possible, so error wording should guide correction without being treated as a guarantee of recovery.

A descriptive tool name and precise description form the invocation contract the agent sees. Names use letters, numbers, and underscores in the documented version, with a purpose-specific verb preferred over a generic default. Descriptions explain when to call the tool and what input to send; unstructured mode benefits from a concrete JSON example.

The tool connects to an AI Agent through ai_tool. Related n8n skills cover ordinary JavaScript nodes, conditional schema configuration, workflow patterns, and validation errors. Test the exact input shape expected from the agent. Do not hardcode secrets or accept arbitrary executable input, and review any write or external-service testing with the required authority. Network destinations, inputs, and outputs need explicit controls.