Last updated on Jul 8, 2026

Tags:

n8n Integration Walkthrough

This guide shows how to add OpenBox governance to an n8n agent without rewriting it. The integration point is a single node: OpenBox: Agent replaces n8n's standard AI Agent node and accepts the same Chat Model, Memory, and Tool connections.

Existing agent?

If you only need the shortest setup path, start with Wrap an Existing Agent.

Prerequisites

n8n with Community Nodes enabled (self-hosted, or n8n Cloud with community node installs allowed)
An existing (or new) AI Agent node connected to a Chat Model sub-node
An OpenBox agent registration with an API key
The OpenBox agent DID and private key unless Require signing is disabled

Part 1: Register Your Agent In OpenBox

Open the OpenBox Dashboard
Navigate to Agents
Create or open the agent you want to govern
Generate an API key
Copy the generated DID and private key unless Require signing is disabled
Keep the credentials in your n8n credential store

Part 2: Install The Node

Package: n8n-nodes-openbox-hook

In n8n, go to Settings → Community Nodes → Install and enter:

n8n-nodes-openbox-hook

Restart n8n if prompted.

If you build your own n8n image instead of installing through the UI, install it as a regular dependency and rebuild:

npm install n8n-nodes-openbox-hook

Part 3: Add OpenBox Credentials

In n8n, go to Settings → Credentials → Add Credential and create an OpenBox API credential:

Field	Required	Description
API Key	Yes	Agent API key issued by OpenBox.
Agent DID	No	Required for agents with `signing_required = true`.
Agent Private Key	No	Base64-encoded raw 32-byte Ed25519 seed, paired with Agent DID.

Part 4: Replace The Node

n8n
OpenBox

workflow.json (node excerpt)
{
  "type": "@n8n/n8n-nodes-langchain.agent",
  "typeVersion": 1.7,
  "parameters": {
    "promptType": "auto",
    "options": {}
  }
}

workflow.json (node excerpt)
{
  "type": "n8n-nodes-openbox-hook.openBoxAgent",
  "typeVersion": 1,
  "parameters": {
    "promptType": "auto",
    "options": {}
  },
  "credentials": {
    "openBoxApi": {
      "id": "1",
      "name": "OpenBox API"
    }
  }
}

Reconnect the same Chat Model, Memory, and Tool sub-nodes the original agent had, and copy over the Prompt setting and any Options (System Message, Max Iterations, Return Intermediate Steps, Automatically Passthrough Binary Images).

Part 5: Verify A Live Run

Run one real request through the governed agent, then check OpenBox for:

a run under the registered agent
model call events with prompt and response metadata
tool call activities with started and completed events, if tools executed
HTTP and database telemetry captured during the run
governance decisions for allowed, blocked, halted, or approval-required operations
signed request authentication when Require signing is enabled

Open the OpenBox Dashboard, navigate to Agents, open the agent, and inspect the latest run.

How The Integration Works

The node runs the same four lifecycle stages as the LangChain SDK's middleware, called directly inside the node's execute() function:

Stage	Purpose
`beforeAgent`	Emits `SignalReceived(user_prompt)` and `WorkflowStarted`, and starts the OpenBox run
`wrapModelCall`	Emits `LLMStarted`, applies input-side guardrails, invokes the connected Chat Model, then emits `LLMCompleted`
`wrapToolCall`	Emits `ToolStarted`, invokes the connected Tool sub-node, then emits `ToolCompleted`
`afterAgent`	Emits `WorkflowCompleted` with a `completed` or `failed` status — this always fires, even when the agent loop errors

The node also patches Node's https module and instruments outbound database queries for the duration of the run, so HTTP and database activity during a model or tool call is captured as telemetry attached to that call.

Tool Invocation

Every Tool sub-node connected to the agent is governed automatically — there is no tool_type_map-style classification step in the node UI. The tool name the agent calls (the LangChain tool's name) is the name that appears on ToolStarted / ToolCompleted events.

Human-in-the-Loop Approvals

If OpenBox returns REQUIRE_APPROVAL, the node polls the OpenBox approval endpoint every 5 seconds for up to 5 minutes by default. If the request is rejected or the poll times out, the node raises GovernanceHaltError and the agent run stops.

See Error Handling for the exception types and recommended handling patterns.

Next Steps

Configuration — Review credential fields, node parameters, and current defaults
Error Handling — Handle governance decisions with Continue On Fail
Troubleshooting — Diagnose missing runs, credential errors, and telemetry gaps

Prerequisites​

Part 1: Register Your Agent In OpenBox​

Part 2: Install The Node​

Part 3: Add OpenBox Credentials​

Part 4: Replace The Node​

Part 5: Verify A Live Run​

How The Integration Works​

Tool Invocation​

Human-in-the-Loop Approvals​

Next Steps​