n8n Message an Agent Node Tutorial: Call Published Agents from Workflows (2026)

Introduction

The Message an Agent node is the bridge between n8n’s two automation worlds. Workflows are deterministic: the same input takes the same path every time. Agents are interpretive: they read a situation, call tools, and decide what to do. Since the Agents launch in September 2026, n8n has shipped a dedicated node that lets a workflow hand one open-ended step to a published agent and keep the rest of the process fixed. This tutorial builds a real pattern: a ticket-intake workflow that validates a support request deterministically, sends the judgment call to a published triage agent, and routes the structured answer onward. It is for n8n users who already run workflows and want to add agent reasoning to one step without rebuilding the whole flow.

Quick answer

Add the Message an Agent node to a workflow, pick a published agent, and write the message from workflow data. The agent replies, and downstream nodes use the answer. Each message costs one execution; sessions carry memory across runs.

Evidence

n8n’s Agents product launched on 2026-09-25, and the Message an Agent node is its workflow-side connector. Adoption context is easy to check: the n8n repository holds 206,835 GitHub stars as of 2026-10-10 (live API check), which makes n8n one of the most-watched automation projects in the world and means the new agent surface gets scrutinized fast.

The official launch blog describes the pattern this node exists for: “add the Message an Agent node. It sends the agent a message built from your workflow data and passes the agent’s answer to the next node.” The same post notes that the agent brings its own instructions, tools, and memory, so the node itself stays simple, and that updating the published agent updates every workflow that calls it at once.

The official agents guide documents what the node can do beyond a plain call: stream the reply as the agent generates it through connected Chat and Webhook triggers, reuse a session so the agent remembers earlier messages, and constrain the reply to a JSON schema so downstream nodes receive predictable fields. Each message counts as one execution, the same as any other workflow execution.

The node’s own implementation history pins down two facts that matter in production. Agents must be published to run from a workflow; drafts are rejected with a clear error. And each input item gets an isolated thread (${executionId}-${itemIndex}), so a batch of items cannot bleed context into each other. For deeper agent architecture, ToolPilot’s n8n Agents tutorial covers creating agents from scratch, and the Agent Builder guide covers the visual builder.

Prerequisites

• An n8n instance on version 2.42 or newer (the Agents product shipped 2026-09-25; self-hosted instances need the agents setup from n8n 2.32.3 onward). Parameter labels below were verified against n8n 2.41.4’s node source in the ToolPilot lab.
• One published agent. Create it in the Agents section, give it instructions and at least one tool, and publish it. Draft agents are rejected by the node.
• A model credential attached to the agent (the agent carries its own model; the node needs none).
• Basic n8n skills: adding nodes, writing {{ }} expressions, reading execution output.

Step-by-step guide

Step 1: Publish the agent first

In the Agents section, open your agent and confirm its status reads published, not draft. This is the step everyone skips. The node cannot see drafts at all: picking a draft in the agent dropdown and running the workflow fails with an error telling you the agent must be published. If you edit instructions later, publish again; the launch blog confirms that every connected workflow picks up the new published version automatically.

Practical tip: name the agent for the workflow that calls it, for example “Support Triage Agent”, so the dropdown in Step 3 stays readable when you own ten agents.

Step 2: Build the deterministic intake

Create a new workflow. Add a Form Trigger (or a Webhook Trigger if the ticket arrives from your app) with three fields: customer email, subject, and issue description. Before the agent ever sees the ticket, validate it deterministically: a Set node that trims whitespace, an IF node that rejects empty issue text. Agents are the expensive, unpredictable part of the flow, so never let junk data reach one.

This separation is the whole point of the pattern: the workflow owns structure, the agent owns judgment.

Step 3: Add the Message an Agent node and pick the agent

Add the node (canvas search: “Message an Agent”; node type n8n-nodes-base.messageAnAgent). The first parameter is Agent, a searchable dropdown of your published agents. Pick the triage agent. You can also supply an agent ID directly, which is useful when you promote the same workflow across dev and prod instances where dropdown values differ.

Step 4: Write the message from workflow data

The Message field (“The message to send to the agent”) accepts expressions. Build it from the validated ticket:

Ticket from {{ $json.email }}
Subject: {{ $json.subject }}
Issue: {{ $json.issue }}
Classify this ticket and draft a reply.

Write the message as an instruction, not raw data. Tell the agent what you want back, not just what the ticket says. The agent runs its own reasoning loop with its own tools and skills, then returns a reply that downstream nodes can use.

Step 5: Constrain the reply with a JSON schema

Turn on Require Specific Output Format (“Whether to constrain the agent response to a JSON Schema you provide. The conforming object is returned on the structuredOutput field.”). Set Schema Type to generate a schema from an example JSON object and paste a JSON Example:

{
  "category": "billing",
  "urgency": "high",
  "draft_reply": "Thanks for writing in. I have flagged your invoice issue for the billing team and you will hear back within one business day."
}

The node returns the conforming object on structuredOutput, so the next node reads {{ $json.structuredOutput.urgency }} instead of parsing free text. One honest caveat, shown in the node’s own notice: structured output is enforced by the model provider, not by n8n. Mark every property as required, because some providers reject optional fields or advanced keywords, and a few (DeepSeek is named in the notice) do not support structured output at all. If your agent runs on such a model, leave this off and parse response yourself. ToolPilot’s agent skills tutorial shows how to tighten agent behavior when the model fights the schema.

Step 6: Give the agent memory with a session

Open Advanced and look at Session ID (“Reuse an agent session to keep memory across runs. Leave empty to start a fresh session per execution.”). Set it to the customer email: {{ $json.email }}. Now a repeat ticket from the same customer continues the previous conversation instead of starting cold, which is exactly what a support agent should do.

Two session options exist under this section: Session ID for a literal key, and Session Key From Previous Node for passing a key computed upstream. For ticket triage, the literal email is enough. Note the isolation rule from the node’s implementation: within one execution, each input item gets its own thread, so five tickets in one batch cannot read each other’s context even when the session key is identical. Memory is per execution thread plus the named session, not a shared pool.

Step 7: Control how many times the agent is invoked

Invoke Agent (“Whether to call the agent once per input item or a single time for all items”) decides the cost model. Once per item is right for triage: every ticket deserves its own reasoning pass. But if the node ever sits after an aggregator that collected fifty rows into one summary request, switch to a single call for all items, or you will burn fifty executions and fifty model calls on one summary. Each message counts as one execution, so this dropdown is a billing control.

Step 8: Route on the structured answer

After the node, add an IF node on {{ $json.structuredOutput.urgency }}. Route high to an urgent Slack/email notification and everything else to a normal queue. Send the draft_reply back to the customer through your mail node, and log toolCalls to your audit table so you can see which tools the agent actually used. The usage field (promptTokens, completionTokens, totalTokens) goes to the same log: it is your per-ticket AI cost record.

Step 9: Decide about streaming and approvals

Enable Streaming only helps when the node feeds a connected Chat or Webhook trigger that can push tokens to a user as they arrive. In a batch triage workflow with no live user watching, leave it off.

For the approval side, do the review where it belongs: in the agent. n8n lets you mark an agent’s sensitive tools as requiring approval before they run, and the launch blog recommends scoped tools plus approvals for anything that writes to a system of record. The Message an Agent node inherits whatever guardrails the published agent has, so set them once on the agent instead of rebuilding them in every workflow. The multi-agent workflows guide extends this pattern to parent and sub-agent setups.

Troubleshooting

1. “Agent must be published” error on execution

Cause: the node points at a draft agent. The node’s implementation rejects drafts with a clear error; this is by design, not a bug.

Fix: open the agent, publish it, and re-run. Make this a checklist item in your deploy process: any workflow that uses the node must reference a published agent, and re-publishing after instruction edits is part of the release.

2. Structured output returns an error or empty object

Cause: the agent’s model does not enforce structured output. The node notice names DeepSeek as unsupported and warns that OpenAI and xAI reject optional fields and advanced schema keywords.

Fix: first, mark every property in your schema as required and remove advanced keywords. If the model still refuses, turn off Require Specific Output Format and parse the response text downstream. For a permanent fix, switch the agent to a model with full structured-output support.

3. The agent forgets the customer on the second ticket

Cause: Session ID is empty, so each execution starts a fresh conversation. The default behavior is stateless.

Fix: set Session ID (or Session Key From Previous Node) to a stable identifier like the customer email. Verify by running the workflow twice with the same email and checking that the second run’s tool calls reference the first conversation.

4. One batch run burns dozens of executions

Cause: Invoke Agent defaults to once per input item, and each message counts as one execution. A node upstream that emits fifty items triggers fifty agent calls.

Fix: if the step genuinely needs one reasoning pass over the whole batch, change Invoke Agent to a single call for all items. If each item needs its own pass, keep per-item mode but move the agent call after a filter so only qualifying items reach it. Watch the usage token totals per run to confirm the change.

5. Enabling streaming changes nothing

Cause: streaming only works through connected Chat and Webhook triggers. In a scheduled or batch workflow there is no live consumer for the token stream.

Fix: leave Enable Streaming off unless the workflow ends in a chat interface. If you need live progress in a batch flow, log toolCalls per item instead; it shows the same reasoning trace after the fact.

FAQ

Does the Message an Agent node replace the AI Agent node? No. The AI Agent node is unchanged and still builds an agent inline in a workflow. The Message an Agent node does the opposite job: it calls an agent you already created and published in the Agents section, so one agent can serve chat channels, schedules, and many workflows at once.

Can I message a draft agent from a workflow? No. The node only runs published agents. If you point it at a draft, the execution fails with a clear error telling you the agent must be published first. Publish the agent, then re-run the workflow.

Does the agent remember earlier messages between workflow runs? Only if you give it a session. Leave Session ID empty and every execution starts a fresh conversation. Fill Session ID with a stable key (for example a customer email or ticket ID) and the agent keeps memory across runs.

How is each call counted and billed? Each message sent through the node counts as one workflow execution, exactly like any other execution. The node also returns token usage (promptTokens, completionTokens, totalTokens), so you can meter the model cost of every call.

What exactly does the node return to downstream nodes? Five fields: response (the agent’s final text), structuredOutput (your JSON-schema object when you enable it), usage (token counts), toolCalls (the tools the agent invoked, with inputs and results), and finishReason (why the agent stopped).

Can one agent message another agent? Yes, in the other direction: connect the Message an Agent Tool to the Tool input of an AI Agent node so a parent agent can hand work to another agent. Do not create a circle where a workflow calls an agent that is also attached to that same workflow as a tool; keep entry-point workflows and action workflows separate.

Conclusion

The Message an Agent node is a small node with a large architectural idea: keep the deterministic skeleton in the workflow and delegate exactly one interpretive step to a published agent. Publish the agent, constrain its reply with a schema, give it a session key, and control the invoke mode, and you get agent judgment inside a process you can still audit, cost, and replay. When the workflow grows into several cooperating agents, read the multi-agent sub-agents tutorial next, and if executions start failing in production, the n8n error handling guide is the companion you want.

Frequently asked questions