When Nodes Become Tools: n8n’s Agentic Loop
n8n’s AI Agent node is the point where the workflow control-plane idea is tested most directly. The question is not whether a language model can produce a tool call; many model APIs can do that. The question is whether the call can become governed n8n work—with a declared schema, a source node, execution data, failure handling, and a path back to the agent. This chapter separates model reasoning from tool execution and follows the EngineRequest/EngineResponse handoff, so the reader can judge what n8n’s agent architecture adds beyond an opaque model endpoint.
The agent is a composite node, not a model field
An n8n AI Agent is assembled from graph connections. In the current Agent V3 implementation, an AI language model is required. Memory, tools, an output parser, and a fallback model are optional inputs, and the node’s configuration can enable streaming, batching, memory limits, structured output, or a forced first tool call. That arrangement makes the agent’s capabilities explicit: the model is one dependency among several, not the whole execution environment.
This separation reflects different responsibilities. The language model proposes a response or an action. Memory supplies conversational context and can receive the resulting exchange. A tool connection exposes operations the model may request. An output parser defines whether the result must satisfy a structured format. A fallback model changes what happens when the primary model fails. The graph therefore gives each capability a place where it can be inspected, replaced, or constrained without rewriting the entire workflow.
The distinction is especially useful for a workflow that handles a customer request. The request may arrive as one input item, but the agent may need a model to interpret it, memory to preserve the conversation, a search tool to retrieve information, and a parser to return a predictable object to a downstream system. Those are different contracts. If they were collapsed into one “AI” setting, it would be difficult to tell whether a failure came from missing context, model output, tool execution, or format validation.
Agent V3 also treats input items as a real execution workload. It can process items in batches, and the executor collects ordinary outputs or engine requests from each batch. Streaming is conditional rather than magical: the execution context must support it, the node’s version and options must allow it, and the surrounding trigger must be configured to carry a streamed response. The node records execution metadata for items, tool calls, iterations, memory loads and saves, streaming, and success or failure. That record keeps agent behavior inside n8n’s observability model.
A connected output parser changes the meaning of success. A plain response can be emitted as text, while a structured response must be parsed according to the supplied schema. This matters when an AI result feeds another node: “the model answered” is not the same as “the downstream contract received valid data.” n8n’s visual composition makes that distinction visible before the run begins.
The same design appears in the code-first @n8n/agents runtime, but with a builder API rather than a canvas. An agent is configured with a model and instructions, then receives typed tools, memory, structured output, MCP clients, workspace capabilities, telemetry, deferred tools, and tool-call concurrency. The runtime supports both non-streaming and streaming calls, tracks state, and can resume a suspended run or re-drive a run from a durable step checkpoint. The interface is different, but the architectural principle is the same: capabilities are explicit inputs to a stateful agent runtime.
That code-first path also makes an important default visible. A bare memory builder uses in-process memory, which is useful for development but is lost on restart. Richer episodic or observational memory requires a backend that implements the corresponding storage contract. The agent can remember messages during a run without that memory being durable across processes. Persistence is therefore a design choice, not a side effect of calling a model.
The same caution applies to provider features. The agent sequence can use a primary model and an optional fallback, and it preserves provider-specific metadata needed to reconstruct later tool-calling turns. But a provider’s support for streaming, forced tool choice, structured output, or reasoning metadata is not uniform. n8n’s implementation contains compatibility paths because the model’s response format is part of the handoff contract. A workflow author should treat those capabilities as conditions to verify, not as interchangeable properties of “AI.”
A tool call becomes ordinary graph work
The most consequential design choice is what happens after the model decides to act. n8n can expose an ordinary node as a structured tool. A node description may mark the node as usable as a tool, while selected parameters can contain $fromAI() placeholders. The tool wrapper scans those placeholders, validates their keys and definitions, creates a Zod schema, resolves a description, and attaches metadata identifying the original node. The model is then asked to provide only the values that the workflow has declared as model-controlled.
Suppose an HTTP Request node is configured to call a particular internal service, with its authentication and method fixed by the workflow, while the destination record ID is marked as an AI-supplied field. The model may choose the record ID, but it does not thereby gain the right to redesign the request or select an arbitrary credential. The wrapper’s schema describes the allowed input, and the source-node metadata tells the runtime which node should receive it. This is constrained agency: the model fills a slot in a workflow-authored operation.
The schema is also a correctness boundary. Tool argument keys must satisfy naming rules, and repeated $fromAI() definitions must agree about their description and type. An inconsistent duplicate is rejected rather than silently merged. That protects the model-facing contract from a node configuration that says two different things about the same argument. The model still can make a bad choice within the permitted type, but the execution system has a chance to reject malformed structure before the side effect runs.
When a model emits a tool call, the agent integration maps it to an engine action. The action identifies the target node, the AI-tool connection type, the call ID, the arguments, and metadata such as the item index and tool name. Toolkit tools may carry the actual tool name inside the input, while the source-node name is retained for routing. Provider-specific reasoning or signature metadata may travel with the action so that the next model turn can be reconstructed in the format the provider expects.
The core engine then treats this request as part of the workflow execution. It checks that the target node exists, merges the agent’s input item with the tool arguments, records a display-oriented representation of the AI-provided arguments, and preserves source-overwrite information needed by expressions. It schedules the target node through an AI-tool connection and puts the requesting agent node back on the execution stack. The agent has not disappeared into a callback; it has become a paused task awaiting graph work.
The handoff looks like this:
The important relationship is the return path. After the tool node runs, the engine collects its task data into an EngineResponse. The agent receives that response as the next turn’s context, including prior requests and results. It can then finish, call another tool, or fail according to its configured behavior. The same run can therefore contain a model turn, one or more node executions, and a resumed model turn, all with identities and execution metadata.
This design preserves n8n’s existing lineage rules. Tool calls do not always have a normal main connection from the agent’s input, so the engine records source-overwrite information to help expressions resolve values from earlier workflow nodes. It also associates tool results with the requesting node for execution logs. A tool result is not merely text returned to the model; it is an output of a node that can be traced, redacted, routed, or included in the surrounding execution history.
The agent loop adds several controls around that handoff. Before a model call, the LangChain path loads memory and supplies prior steps. After a successful response, it saves the conversation, including tool-call context. The code-first runtime uses a message list and run state that can be persisted for resume. These are two forms of context with different roles: memory describes a conversation or longer-lived history, while execution state describes where the current agentic run is and which tool calls remain unsettled.
Streaming changes delivery, not the basic authority model. When streaming is available, the agent processes model events and can emit chunks as the response develops. If the stream contains tool calls, those calls are converted into engine requests just as in the non-streaming path. A streamed response therefore does not mean that the model bypasses node scheduling; it means that some output reaches the caller earlier while the control loop remains intact.
Fallback and batching create different trade-offs. A fallback model can be attached to the agent sequence so a primary model failure has another model path. That improves continuity under a particular class of failure, but it does not make the two models semantically identical or guarantee the same tool behavior. Batch execution can process multiple input items concurrently at the agent layer and merge their tool requests, while per-tool concurrency in the code-first runtime can be sequential, bounded, or unlimited. More parallel work can improve throughput, but it also increases the number of in-flight side effects that must be traced and governed.
Maximum iterations provide a termination condition for an agent that keeps requesting tools or cannot produce a final answer. On a continuation, n8n checks the prior iteration count before running the next agent step and raises a node error when the configured limit is reached. That is not a proof that the answer is correct; it is a bound on how long the model may continue driving the graph. The distinction matters operationally because an agent can be syntactically successful while still being unable to complete its task within the allowed loop.
Human approval adds another state boundary. An approval-capable tool suspends before its original handler runs and stores the information needed to resume. If approval is granted, the gated tool is turned into a later engine request and executes; if it is denied, the response sent back to the agent tells it that the call was rejected and, when no feedback is supplied, instructs it to stop rather than blindly retry. The approval wrapper validates the resume payload, but approval remains a control point, not a guarantee that the requested action is wise.
A checkpoint is mandatory for this kind of interruption. In-process checkpoint storage is suitable for a development process, while a persistent store is needed when the run must survive a restart or move across processes. The code-first runtime also distinguishes a normal suspended tool call from a crash-resume checkpoint: a suspended call has pending tool work to settle, while a step checkpoint re-enters at a model boundary and does not mechanically replay an uncertain effect. That distinction reduces the chance that a recovered process repeats an external action without knowing whether the first attempt succeeded.
Not every waiting operation belongs inside an inline agent tool. n8n explicitly excludes operations such as sendAndWait and dispatchAndWait from inline agent-node tool execution because they park a persistent workflow execution. An inline tool callback has a different lifecycle from a full workflow that waits for an external event. For human approval, the intended action can instead be configured as a gated tool and resumed through the agent’s checkpoint path. The boundary is architectural: similar-looking pauses do not share the same ownership of state.
The result is a disciplined way to talk about n8n agents. The model supplies interpretation and a proposed action. The tool schema narrows what it may supply. The engine selects and runs a workflow node. The task record carries the result and lineage. Memory and run state provide different forms of continuity. Approval, iteration limits, fallback, and concurrency shape what can happen next. n8n’s distinctive contribution is not that it makes model reasoning reliable by itself; it makes model-directed actions enter a broader, inspectable execution system.
That system still needs an external lifecycle. A webhook may start the agent, a worker may execute it, a response may stream back to a caller, or a wait may persist until a later event. The next chapter follows those operational transitions, from published webhook ingress to regular and queue-backed workers, to show where the agentic loop meets deployment reality.