How to Add Human Approval to n8n Agent Builder Tools

Introduction

An agent that can read is helpful. An agent that can send, delete, or spend without asking is a liability. The n8n Agent Builder lets you draw that line tool by tool: a lookup can run on its own, while a tool that emails a customer or updates a CRM record must wait for a person to say yes. This tutorial shows how to set up that gate, rehearse it in a draft test run before anyone real is affected, and carry the same discipline into production. You will gate one dangerous tool on a small support triage agent, and prove the approval path twice: once when you approve, and once when you deny.

Quick answer

Mark the sensitive tool as requiring approval, add a denial rule to the instructions, then test the draft in Preview: approve once, deny once, and publish only after both paths behave.

Evidence

The approval model in the Agent Builder is a named feature with a named change behind it. Pull request 35731 in the n8n repository is titled “feat(core): Add HITL to agent builder test runs”, and it was merged on August 6, 2026. Its test plan describes exactly the rehearsal this tutorial follows: configure an agent whose tool requires approval, let the builder test the draft, approve or deny the target-tool confirmation in chat, verify the same test run continues, and then trigger a second approval and verify the next confirmation appears only after the first decision. The same change notes that target-tool details are rendered as one-time approvals, with no session-level auto-approval. That sentence is the whole safety model: approving one call never silently approves the next one.

n8n states the production rule just as plainly in its Agents announcement: “Approvals on sensitive tools. Mark a tool as requiring approval and the agent pauses for your Approve or Reject before it runs, then picks up where it left off.” The pause is the point. The agent does not guess its way around a missing reviewer, and it does not run the tool while it waits. For the classic in-workflow version of the same idea, the human-in-the-loop documentation for AI tool calls explains the approve and deny semantics in the same terms: on approval, the tool executes with the input specified by the AI, and on denial, the action is cancelled and does not run. The pull request that added approval to Agent Builder test runs is the primary source for the test-run behavior, including the one-time approval rule and the sequential second-confirmation check.

As of November 2, 2026, the n8n repository on GitHub reports 209,340 stars, so a very large number of instances can put an agent in front of real systems. A gate tested in a draft is cheap, and a gate discovered missing after the agent has already emailed a customer is not.

Prerequisites

• An n8n instance with the Agents surface available. Agents launched in Preview on n8n Cloud, and on self-hosted n8n from version 2.32.3, so confirm the Agents tab exists before you start.
• A language model credential already connected in n8n, such as an OpenAI or Anthropic key stored as a credential, never pasted into chat.
• One read-only tool workflow, for example an account lookup that returns a status for a test account ID, and one write tool workflow, for example a test CRM updater that writes only to a sandbox record.
• A test account and a test record you are happy to change, plus a reviewer who will actually watch the approval channel during your test.
• Basic familiarity with the n8n Agent Builder tutorial, which covers creating the agent, attaching workflows as tools, and publishing a draft.

Step-by-step guide

Step 1: Build a draft agent with one safe tool and one dangerous tool

Open the Agents surface and create a draft agent named for a narrow job, such as “Support Triage Agent”. Give it plain-language instructions that name the job, the tools, and the boundary in the same paragraph, for example: “You are a support triage agent. Classify each message as billing, technical, or general. Use the lookup tool to fetch account details, then draft a reply. Never send a customer message or update a CRM record without human approval. If you are unsure which tool fits, ask the user instead of guessing.”

Attach the lookup tool first and leave it ungated. Then attach the write tool, such as the test CRM updater, and keep it as the only gated tool for this exercise. Name the tools with verbs and narrow descriptions, such as “lookup_account_status” and “update_test_crm_record”. Tool names and descriptions carry the design weight here, because the model sees the instructions and the tool list rather than your canvas wiring.

Step 2: Mark the write tool as requiring approval

Find the connection from the agent to the write tool and add a human review step on that connection, following the same pattern used for AI Agent tool calls: the agent pauses before the gated tool, and a reviewer sees the tool name and the parameters the AI wants to use. Do not gate the lookup tool in this test.

Decide the approval channel before you test, and pick a channel your reviewer already watches. In the Agents feature, the approval appears as Approve or Reject buttons in the chat, so for a draft test the builder chat itself is the simplest reviewer surface.

Step 3: Write the denial rule into the instructions

Add one explicit sentence to the agent instructions before you test anything: “If a tool call is denied, explain what was blocked and offer a safe alternative instead of retrying the same action.” Denial cancels the tool call, but it does not by itself teach the agent what to do next. Without this sentence, the most common approval failure is an agent that retries the blocked action with slightly different parameters, turning one denial into a loop of new approval requests.

Step 4: Run the draft test and approve the gated tool

Open the draft in Preview and send a test message that should trigger the lookup first and the gated write second, for example: “A test customer asks about their billing status. Look up test account T-100, then update the test CRM record to note that billing was explained.” The lookup should complete without a pause. When the agent reaches the gated tool, the run should pause and present an approval request showing the tool and the parameters the AI chose. Read those parameters before you decide, because that is the reviewer’s real job: a correct tool with a wrong account ID is still a wrong action.

Select Approve. The tool should then run with the parameters the AI specified, and the same test run should continue to its reply, rather than restarting from the beginning. Check the test CRM record afterwards and confirm that exactly one update landed, with the values from the approval request.

Step 5: Run the draft test again and deny the gated tool

Start a fresh draft test with the same prompt, and this time select Reject or Deny when the approval request appears. The write tool must not run, and the test CRM record must stay unchanged. The agent should then follow your denial rule: explain what was blocked and offer a safe alternative, such as drafting the update text for a human to send later, instead of retrying the tool.

If the agent retries the denied tool, stop and fix the instructions before you go further. That retry is not a cosmetic flaw. Fix the sentence, re-run the denial test, and only move on when a denial ends the action cleanly.

Step 6: Test the second approval and the one-time rule

Approving once must never approve twice. Run a draft test that asks the agent to perform two gated writes, for example updating two different test records, or updating one record and then sending one test message. The first approval request should appear, and the second confirmation should appear only after you decide the first one. Do not expect both requests at once, and do not approve the first request assuming the second is covered.

Decide the first request, then decide the second request separately, and check both test records afterwards. Each gated call needs its own decision, every time, in the draft test and in production. Also treat an approval as bound to its own test run: if you close the test and come back later, restart it with a clean prompt.

Step 7: Publish only after both paths pass, then re-test in production

Publishing creates a versioned release, and editing the draft afterwards does not silently change the published agent, so publish deliberately once the approve path, the deny path, and the second-approval path have all passed in the draft. Then re-test the published agent with safe data in its real channel, because a draft test proves the gate logic, not the production routing. Send the same two-step prompt through the real channel, approve once, deny once on a second run, and check the Sessions tab afterwards

Your production checklist is short, and every item should be true before the agent touches real records. First, only irreversible tools are gated, and read tools stay automatic. Second, approvals go to a reviewer who watches that channel during working hours, with a named backup for absences. Third, the denial sentence is in the published instructions, not only in the draft you tested last week. Fourth, every gated tool writes to a system where you can audit who approved what. Fifth, you have a fallback for approvals outside the builder chat: a workflow-level Wait node that pauses on a webhook call or form submission can carry an approval link to a reviewer who does not live in the agent chat, with a wait limit so an unanswered approval resumes into a branch you chose instead of waiting forever. Re-run the full draft test after every n8n upgrade, since Preview behavior can shift without changing your instructions.

Troubleshooting

No approval request appears in the draft test. Check that the write tool is actually the gated one, and that the agent chose the gated tool rather than answering from its own knowledge or calling the ungated lookup instead. Rewrite the test prompt so the gated action is unavoidable, for example by naming the test record and the exact update.

The agent retries an action after a denial. This is an instructions problem, not a reviewer problem. Add the denial sentence from Step 3, worded as a rule rather than a suggestion, and re-run the denial test. If the retry continues, narrow the agent’s job or remove the tool from the agent until the denial path is clean.

The approval request goes to nobody. Check the channel first and the agent second. A reviewer who does not monitor the approval channel is the same as no reviewer at all, so route approvals to a channel with a named owner during the hours the agent runs. In the Sessions tab, look for the pending approval on the run itself

The second approval never appears. Decide the first approval before judging the second. The test-run design shows confirmations sequentially, so the second request appears only after the first decision. If you approved the first request and the run still stalls, check the Sessions tab for an error in the first tool execution

The Agents surface is missing on a self-hosted instance. Agents are available on self-hosted n8n from version 2.32.3, and the feature launched as a Preview, so an older instance may simply not have the tab. Upgrade to a version that includes Agents, and if the surface is still absent, stay on the classic in-workflow AI Agent node pattern, which n8n continues to support and which has its own human review step for tool calls. The n8n Agents overview explains how the two patterns interoperate.

FAQ

Does an approval in a draft test run also approve the published agent? No. Test-run approvals are one-time decisions for one tool call in one test run, and the published agent still asks again the next time it wants the gated tool.

Can I gate only one tool and leave the rest automatic? Yes. Approval is per tool, not per agent. Leave read-only tools automatic, and gate only the tools that send, delete, update, or spend, since gating everything creates approval fatigue.

What happens when a reviewer denies a tool call? The action is cancelled and does not run. The agent should explain what was blocked and offer a safe alternative, which is why your instructions need an explicit denial rule before you publish.

What if the reviewer never answers an approval request? The test run does not proceed past the gated tool. End that test, fix the routing or the reviewer assignment, and run the test again with a prompt that clearly triggers the gated tool.

Is the n8n Agents feature still in Preview? Yes. n8n marks Agents as a Preview feature, and its documentation warns that Agents can make mistakes and their behavior may change while the feature is in development. Test after every upgrade, and keep the classic AI Agent node pattern as your fallback.

Do I need approval on every agent, or only on some? Only where the cost of a wrong action is high. Gate tools that send customer messages, write to production systems, delete records, or spend money, and keep research and drafting tools ungated.

Conclusion

Human approval in the Agent Builder is a small feature with an outsized effect: it turns an agent from something that acts into something that asks, exactly where asking matters. Mark the irreversible tools, write the denial rule, and prove both the approve path and the deny path in a draft test before you publish. Then prove them again in production, and again after every upgrade, because each gated call needs its own decision and no approval carries forward on its own. If you are still choosing between the builder and the classic canvas, start with the n8n Agent Builder tutorial for the full build, and keep the Message an Agent pattern in mind for designs where a workflow stays in charge and calls a published agent for one AI-driven step.

Frequently asked questions