Agent In

agent-in creates the message shape expected by an agent node. Use it for normal messages, tool results, and sequential agent pipelines.

The node preserves other root-level message properties and replaces msg.payload with the generated agent payload.

Modes

Mode	Purpose
Message	Creates an agent.request from a normal message.
Tool Response	Creates a tool.response from skill output.
Agent Response	Converts one agent’s response into a request for another.

Message Mode

Property	Sources	Behavior
Session ID	msg, flow, global, or fixed string	Identifies the conversation. A random UUID is used when the value cannot be resolved.
Message	msg or fixed string	Must resolve to a string or an object with a string text property.
User ID	msg, fixed string, or disabled	Optional identity used by user-scoped memory and non-session budgets.

The default configuration reads the session from msg.topic and the message from msg.payload.

A string becomes:

{
  "text": "The incoming string"
}

An object is preserved, which allows integrations to supply additional content such as supported images.

Tool Response Mode

Tool Response reads the configured Data value and requires these root message fields:

• msg.callId
• msg.tool
• msg.sessionId

These fields are added when the agent invokes an agent-skill. Preserve them through the tool flow.

Only the correlation fields are required by Agent In. The node does not check that Data contains a useful result, so validate tool output in the flow before returning it to the agent.

Return both successful results and handled failures through this mode. A Catch node, Debug node, or application log does not notify the waiting agent by itself. Route the failure into a Tool Response with the original correlation fields and useful error data.

The output content has this shape:

{
  "callId": "call-1",
  "tool": "skill-node::action",
  "data": {
    "result": "Tool output"
  }
}

Agent Response Mode

Agent Response is intended for a final agent.response message containing:

• msg.payload.params.sessionId
• msg.payload.params.content.text

It preserves the content and session ID while changing the method to agent.request. Place it between two agent nodes to create a sequential pipeline.

This mode validates the message structure, not msg.payload.method. An Agent node can emit acknowledgement, warning, clarification, error, and final-response messages, so filter its output before Agent In to ensure only the final response continues:

agent
  -> switch: msg.payload.method == "agent.response"
  -> agent-in (Agent Response)
  -> next agent

Agent Response mode does not copy params.userId into the new request. Root-level properties already present on the Node-RED message, including msg.user, remain available because Agent In preserves the surrounding message. Set identity deliberately when the downstream agent uses user-scoped memory or budgets.

The same session ID is forwarded to the next agent. This correlates the pipeline but does not by itself combine the agents’ histories; history and memory still depend on each agent’s configuration.

Errors

The node reports an error when the message content, agent response, or required tool-correlation fields cannot be resolved. Attach a Catch node to handle malformed input and missing correlation data.

For a skill flow, catching an error is only the first step. Preserve or restore the original msg.callId, msg.tool, and msg.sessionId, create a concise failure result, and send it through another Agent In node in Tool Response mode.