n8n-nodes-2kw

n8n community node for the 2kw.ai platform (engineering name: Backbone).

Use 2kw.ai inside n8n workflows: extract structured data with schemas, fetch and compile prompts, convert documents to markdown, transcribe audio, and append items to datasets.

Installation

The package is published on npm as n8n-nodes-2kw.

In n8n (recommended). Open Settings → Community Nodes → Install, enter n8n-nodes-2kw, accept the community-node risk prompt, and confirm. n8n installs it from npm and the 2kw node appears in the node picker.

Manually into ~/.n8n/custom. npm install n8n-nodes-2kw inside ~/.n8n/custom/ and restart n8n. The node loader picks it up by the n8n field in package.json.

From source. cd n8n && npm install && npm run build && npm pack produces a tarball you can point the same install dialog at. Useful for testing an unreleased change.

Releases are cut from the backbone monorepo, so the package version tracks the platform version rather than counting up on its own — see "Versioning" below.

Configure credentials

In n8n, open Credentials → New → 2kw API and provide:

• Base URL: https://api.2kw.ai (or your self-hosted Backbone URL)
• API Key: a personal access token created in the 2kw.ai dashboard under Settings → API Keys

n8n's credential test calls GET /v1/models against your base URL — if it succeeds, the key is valid.

Usage

Drop the 2kw node into a workflow. Pick a Resource and Operation.

Agent, Label, Schema, Prompt, Schema Version, and Prompt Label fields are searchable dropdowns populated from the 2kw API on demand. Switch a field to its manual mode (By ID, By ID or Name, or By Name) to paste a value or use an n8n expression instead.

Resource	Operation	Notes
Agent	Decide Approval	Approves or rejects every pending approval of a paused run and continues it. Required: Agent, Response ID, Decision (Approve All / Reject All, default reject). Optional: Label (the one the run used), Reason, Remember for Conversation (approvals only). Options: Mode, Return Paused Runs, Simplify Output. See Human approval from a workflow.
Agent	Send Message	Runs one turn of a stored agent. Agent and Label are pickers (empty label = latest). Options: Binary Properties (comma-separated, uploaded as attachments), Conversation ID, Mode, Previous Response ID, Return Paused Runs, Simplify Output. Fails if the agent pauses unless Return Paused Runs is on — see Agents in n8n.
Schema	Get	Searchable picker. Returns schema metadata + active version.
Prompt	Get	Searchable picker. Returns prompt metadata.
Prompt	Compile	Compiles a prompt with a Variables JSON map. Optional Version ID (string) or Label (picker, depends on prompt).
Prompt	Resolve	Returns the active prompt content (no variable interpolation). Optional Label (picker, depends on prompt).
Extraction	Run	Sync or async-with-polling (toggle Wait For Completion, default on). Schema and Schema Version are searchable pickers.
Extraction	Get	Look up a previous extraction by ID.
Extraction	Estimate	Estimate token usage + recommended strategy without running.
Document	Convert	Multipart upload from a binary property. Output Formats selects which representations to include. Returns one item per converted document.
Document	Convert From Source	URL or base64 (no binary upload). Same Output Formats + per-document item split as Convert. Pipeline option: fast / ocr / vlm.
Transcription	Transcribe	Multipart audio upload. Required: Model. Optional: Language, Prompt, Response Format, Temperature.

Agents in n8n

Agent › Send Message runs one turn of an agent you built in 2kw and returns its answer as text, together with commentary (what the agent said on its way to a tool call, one string per message, oldest first; when a run pauses before it answers, text is empty and what it said so far is here), status, responseId, conversationId, conversationMode, model and usage. conversationMode is the conversation mode the turn ran under: plan, ask, auto, or null when none is set. Pass conversationId (or responseId as Previous Response ID) to a later Send Message to continue the thread. Files from binary properties are uploaded and attached to the message; images reach the model as pixels.

n8n runs agents unattended by default. When an agent's policy wants a human to approve a tool call, the run pauses and this operation fails with the tools that are waiting, for example Agent paused for approval: create_invoice (apreq_…). To ask a person instead, see Human approval from a workflow. For agents you call from n8n, use tools their policy lets run without a human decision — once auto-approval is available, set classes.write to auto in the agent's policy. A run that asks for a client-side tool fails the same way (Agent requested client-side tool …), because n8n cannot execute it. A run that stops early (status: incomplete, e.g. too many tool iterations) is returned, not failed; check incompleteReason. Leave Retry On Fail off for agents with write tools: a timed-out turn may still be running, and a retry repeats its tool calls.

Conversation mode

The Mode option of Send Message and Decide Approval sets the conversation's mode, which narrows what the agent may do without touching the agent:

• Plan: read only. Anything that could change something is refused.
• Ask: no automatic approver. Calls that need approval wait for a person.
• Auto: the operator's policy as written, automatic approver included.

Leave the option out to keep the conversation's mode; the node then sends nothing. Once added, it defaults to Ask, and the node appends a backbone:mode item to the request. The mode is stored on the conversation and applies to its later turns too. A mode only tightens the agent's policy, never loosens it. See Conversation Mode in the API docs.

Human approval from a workflow

To put a person in the loop instead of failing, turn on Return Paused Runs in Send Message. A run that pauses for approval then comes out as an item with status: requires_action, its responseId, and pendingApprovals — one entry per waiting call, with approvalId, tool, arguments, policyClass and reason (why the auto-approver escalated it, or null). Route on a non-empty pendingApprovals with an IF node, not on status alone (a run waiting for a connector's question has the same status and is answered in chat, see below), ask a person with any Send-and-Wait node (Slack, email, Telegram), and pass the answer to Agent › Decide Approval:

• Agent and Label: the same agent and label the run used. The platform resolves the approved calls' tools from the continued version.
• Response ID: {{ $json.responseId }} from the paused item.
• Decision: Approve All or Reject All, or an expression returning approve or reject. It applies to every pending approval of the response; the platform accepts a continuation only when all of them are decided.
• Reason: optional. It is recorded on each decision, and on a rejection the agent reads it.
• Remember for Conversation: approvals only. Later calls of the same tools in this conversation run without asking. Destructive tools are approved once and never remembered.

Decide Approval reads the pending approvals from GET /v1/agents/{agentId}/approvals?status=pending, sends one backbone:approval_response per approval on POST /v1/responses with previous_response_id, and returns the continued run in Send Message's output shape. A continued run can pause again; with Return Paused Runs on it comes out the same way, so a loop back to the person works.

It fails the item when:

• nothing is pending on the response: already decided by a person, a conversation grant or the auto-approver, or the ID is not a paused run of this agent;
• the platform refuses the decision, for example because an approval was decided automatically (2kw refused the decision on response …) or is no longer pending;
• the conversation is in Plan and an approval is not read-only (conversation_in_plan_mode). The approval stays pending. Setting Mode to Ask on the same Decide Approval leaves Plan and approves in one request; leaving Plan is the person's decision, so ask them first;
• the continued run asks for a client-side tool, which n8n still cannot execute. A turn can wait for approvals and a client-side tool at once; deciding the approvals does not run the client-side tool.

Approvals remain a human decision. Do not give Decide Approval to an AI Agent as a tool, and do not wire it to approve without asking someone. For tools that should run without a person, set classes.write to auto in the agent's policy once auto-approval is available.

Connectors that need a person's sign-in

An agent can use an MCP connector that acts as a person, through their own OAuth sign-in. When nobody is connected yet, or the agent is not yet allowed to use the connection, the run pauses with a backbone:connector_auth_request item instead of calling the connector. n8n cannot sign in for anyone, so by default the item fails with Agent paused until you connect <label> (<host>) in https://chat.2kw.ai/connectors. The error says allow the agent to use instead of connect when the connection exists but this agent is not allowed yet, and reconnect when the sign-in expired.

To handle the pause in the workflow, turn on Return Paused Runs. The paused item then carries pendingConnections, one entry per connector: serverLabel, host, reason (connect, allow or reconnect), destinations (the hosts an allow is asked for again, or null) and connectUrl, the Connectors page of chat.2kw.ai that belongs to the credential's base URL. Send the person the link, wait until they have connected, then continue the run with Send Message and Previous Response ID {{ $json.responseId }}; the message can be anything, for example "connected". The platform checks the connection again on that turn: if the person connected, the agent goes on; if not, it is told so and may ask once more. Never answer the connect call yourself.

Connectors that ask the user a question

A connector can ask the person who started the run something in the middle of a call: pick one of two matching customers, fill in a missing field, or confirm a step on the service's own page. Only that person can answer, and only in chat.2kw.ai, so by default the item fails with <label> needs the user's input — answer in chat: https://chat.2kw.ai/c/<conversationId>. With Return Paused Runs on, the paused item carries pendingInputs, one entry per question: inputRequestId, serverLabel, tool, mode (form, url, mixed or unknown) and answerUrl, the conversation to answer in. Send the person the link; the run continues in chat once they answer. The simplified output never carries the question itself. A question outranks every other pause: when the same run also waits for an approval or a connection, the item fails (or is returned) for the question with pendingApprovals and pendingConnections empty, and the answer in chat resolves the rest. Neither Decide Approval nor Send Message continues a run that waits for a question.

Using n8n's OpenAI node instead. With the OpenAI credential set up as below, OpenAI › Message a Model (n8n 1.117 or later) can call an agent too: pick the model By ID and enter agent/<name> or agent/<name>@<label>. That is fine for text-only turns with agents that never pause. It cannot attach files, and its default Simplify setting hides a paused run — the workflow receives empty output and carries on. The OpenAI Chat Model inside n8n's AI Agent is not supported for agents yet. With a streaming trigger it requests streaming, which the 2kw Responses API now answers with Server-Sent Events, but that node has not been verified against agent turns.

Chat completions (via n8n's OpenAI node)

The 2kw API exposes an OpenAI-compatible /v1/chat/completions endpoint. To use chat models, embeddings, vision, tool calling, or n8n's AI Agent against 2kw, use n8n's built-in OpenAI node rather than this package — that gives you the full OpenAI surface for free.

Setup (one-time):

1. In n8n, Credentials → New → OpenAI.
2. Base URL: https://api.2kw.ai/v1
3. API Key: your 2kw PAT (the same key your 2kw API credential uses).
4. Save.

After that, any n8n node that consumes an OpenAI credential — Chat Model, Embeddings, AI Agent, Tools — works against 2kw with no further setup. Use 2kw's provider/model format in the model field (e.g. openai/gpt-4o-mini).

Local development with Docker Compose

The repository's compose.yaml includes an off-by-default n8n service under the n8n profile. It bind-mounts ./n8n/dist and ./n8n/package.json into the container's custom-node folder so a npm run build is all that's needed to pick up code changes.

cd n8n && npm install && npm run build      # build the package once
docker compose --profile n8n up -d n8n      # start n8n on http://localhost:5678
# iterate:
cd n8n && npm run build                     # after edits
docker compose --profile n8n restart n8n    # reload the bind-mounted dist

n8n's first launch asks you to create an owner account in the UI. After that, Credentials → New → 2kw API and the 2kw node are immediately available.

Smoke test (required before each release)

1. Build the package: cd n8n && npm install && npm run build.
2. Either install a locally packed tarball into your existing n8n, or start the local Docker n8n: docker compose --profile n8n up -d n8n.
3. Configure a 2kw API credential pointing at dev backbone with your API key.
4. Build a 2-node workflow: a manual trigger → 2kw (Schema → Get) using a known schema ID. Run it. Confirm the output JSON contains the schema definition.
5. Repeat with Extraction → Run against a small schema and a one-line inputText. Confirm the output contains a result object.

Versioning

The published version is the backbone platform version, stamped by release CI — the same scheme @2kw/ai (CLI) and @2kw/ai-mcp-server already use. The version field committed here is a placeholder and is never what ships.

The first npm release therefore jumps from the internal 0.3.0 to the platform's current major. There were no 1.x–4.x releases of this node; the numbers are shared with the platform, not skipped.

Prereleases publish under the dev dist-tag (npm install n8n-nodes-2kw@dev), stable releases under latest.

Changelog

Unreleased

• Added Agent › Send Message: agent and label pickers, file attachments, loud failure when the agent pauses for approval.
• Added Agent › Decide Approval: approve or reject every pending approval of a paused run and continue it. Send Message and Decide Approval gained Return Paused Runs, which returns an approval pause as an item with pendingApprovals instead of failing.
• Added the Mode option (Plan, Ask, Auto) to Agent › Send Message and Decide Approval, which sets the conversation mode, and conversationMode to the simplified output.
• A run paused on a connector the user must connect in chat.2kw.ai now fails with the connector's label, host and the Connectors link instead of "client-side tool mcp____connect". With Return Paused Runs on it is returned with pendingConnections; the simplified output of every paused run now carries pendingConnections (empty when none).
• A run paused on a connector's question to the user now fails with the connector's label and the chat link to answer in. With Return Paused Runs on it is returned with pendingInputs; the simplified output of every paused run now carries pendingInputs (empty when none).

Entries below 1.0.0 predate npm publication and use the node's own numbering.

0.3.0

• Resource locators for Schema, Prompt, Schema Version, Prompt Label (searchable dropdowns).
• Document conversion: Output Formats multi-select (MD, TEXT, JSON, HTML); response split into one n8n item per converted document.
• Breaking: removed Dataset resource. Workflows using Dataset.AppendItem will fail to load. Replace with a generic HTTP Request node hitting POST /v1/datasets/{id}/versions/{versionId}/items.

0.2.0

• Added Extraction.Get, Extraction.Estimate, Prompt.Resolve, Document.Convert From Source.
• Extraction.Run gained Wait For Completion toggle (default on) — submits to async + polls.

0.1.0

• Initial release: Schema.Get, Prompt.Get/Compile, Extraction.Run (sync), Document.Convert, Transcription.Transcribe, Dataset.AppendItem.

Roadmap

• n8n verified-community-node submission.
• Trigger nodes (require backend webhook events).
• Async document conversion + Wait For Completion (sync covers most cases today).

Development

Source of truth is the n8n/ directory of the backbone monorepo. github.com/2kw-ai/n8n-nodes-2kw is a one-way mirror written only by release CI — pull requests and direct commits there are overwritten by the next release. Report issues there; send patches against the monorepo.

cd n8n
npm install
npm run sync-types       # copy OpenAPI types from mcp/
npm run dev              # tsc --watch
npm test                 # vitest
npm run lint             # tsc --noEmit + n8n community-package scan
npm run scan             # the scan on its own
npm run build            # tsc + gulp icons

npm run scan runs n8n's own @n8n/scan-community-package rule set against this
working tree. Passing it is a requirement of n8n's verified-node programme, and
the published npx @n8n/scan-community-package n8n-nodes-2kw form of it only
accepts an already-published package — so this is the pre-merge equivalent, run
on the source the scanner would otherwise fetch from the mirror. Two consequences
worth knowing:

• Tests live in test/, not next to the code. The scanner lints
  {nodes,credentials}/** with inline configuration disabled, so a fixture like
  { name: 'prod (v9)', value: 'v-9' } under nodes/ is read as a node
  parameter and fails a naming rule that cannot be suppressed.
• The timer globals are off limits. Use sleep from n8n-workflow rather
  than setTimeout; n8n Cloud restricts them for community nodes.

Type drift check fails the build if generated/openapi.d.ts no longer matches mcp/src/generated/openapi.d.ts. Run npm run sync-types after any MCP regeneration. In a standalone checkout of the mirror there is no mcp/ to compare against, so the check accepts the committed copy and the drift guard runs in the monorepo pipeline only.

The connect-pause decoder works the same way. nodes/TwoKw/operations/connect-pause.ts and test/fixtures/connect-pause-cases.json are copies of the CLI's cli/src/lib/connect-pause.ts and its golden fixture, so the CLI, the MCP server and this node read a paused run's connector requests by one rule. npm test runs npm run check-connect-pause first and fails when either copy has drifted; run npm run sync-connect-pause after changing the CLI's files, never edit the copies. The mirror has no cli/ either, so there the check accepts the committed copies.

License

MIT — see LICENSE. Note that this applies to the n8n node package only; the rest of the 2kw.ai platform is proprietary.