Skills And Tool Calls

A skill exposes one or more Node-RED flow actions to an agent. For the documented workflow, create an agent-skill node on the same flow tab and select it in the agent’s Skill Set.

Skill Flow

agent chooses a skill action
  -> agent-skill emits a Node-RED message
  -> flow performs the work
  -> agent-in in Tool Response mode returns the result
  -> agent continues reasoning

Each action is listed in the model’s available-tools context. The model requests one through the runtime’s structured tool.request action.

An action’s runtime identifier combines the skill node ID and action name:

<skill-node-id>::<action-name>

This keeps actions on different skill nodes distinguishable. The integration currently uses prompt context and structured action output rather than native provider tool or function calling.

Good Action Definitions

An action needs:

A non-empty name that is unique within its Agent Skill node.
A description that explains when to use it.
Parameters with clear types and descriptions.
Required fields marked accurately.
Output wiring that matches the configured output mode.

Use distinct action names across all skills selected by the same agent when possible. This keeps model selection, event traces, and fallback name matching unambiguous.

Do not include :: in an action name. The runtime uses that sequence to separate the skill node ID from the action name.

Descriptions are part of the model prompt. Do not include API keys, credentials, private operational notes, or unnecessary customer data.

Parameters

Supported parameter types are:

string
number
boolean
object
array

A parameter can target the root message or msg.payload. Default values may be shown to the model for optional parameters.

Parameter types, required markers, and defaults currently guide model output; the agent runtime does not validate the returned arguments or insert omitted defaults before invoking the flow. Validate important inputs and apply required defaults inside the Node-RED skill flow.

Do not use these runtime-owned names for action parameters:

action
sessionId
callId
tool

The runtime adds or overwrites these fields when it invokes a skill.

Output Routing

Per action is the default and creates one output for each configured action. The output order follows the action list.

One sends every action through one shared output. The invocation preserves msg.action, so a Switch node can route by the selected action name.

Parameters targeting the message root remain at the root. Parameters targeting Payload are moved into msg.payload.

Correlation Fields

Skill invocation messages include correlation fields such as:

sessionId
callId
tool

The flow must preserve these fields until it reaches agent-in in Tool Response mode. Without them, the runtime cannot match the result to the waiting agent call.

Parallel Calls

The runtime can receive multiple tool calls in one reasoning step and track their results independently. It waits for all calls in that group before continuing the agent. Design skill flows so each invocation preserves its own correlation fields and does not overwrite another call’s state.

The current tool timeout is 30 seconds. A timed-out call is returned to the agent as a tool result so the model can decide whether to retry, use another skill, or explain the failure.

Tool Errors

A Catch node or application log does not by itself resume the waiting agent. Every success and failure path should return a result through agent-in in Tool Response mode while preserving the original correlation fields.

Return concise error data that explains what failed and whether retrying may help. If no result returns, the agent waits until the current 30-second timeout.

Agent Studio

Agent Studio can display selected agent-skill nodes and edit some existing action fields. Use Node-RED to add, remove, or reorder actions and parameters, change output mode, verify output ports, and wire the implementation flow.

Studio’s current Type and Target inputs do not enforce the runtime’s supported values. Verify edited skill definitions in Node-RED before deployment.

See Agent Skill and Agent In for field-level configuration.