@cloudbase/agent-adapter-n8n

n8n adapter for AG-Kit - Connect to n8n workflows via Streaming Webhook.

Features

• Streaming Support: Real-time text streaming via n8n Webhook
• Basic AGUI Events: Supports RUN_STARTED, TEXT_MESSAGE_*, RUN_FINISHED, RUN_ERROR
• Flexible Authentication: Pass any HTTP headers for n8n webhook authentication (Basic Auth, Header Auth, JWT)
• Zero Configuration: No special scripts required in n8n workflow

Installation

npm install @cloudbase/agent-adapter-n8n

Quick Start

Using Environment Variables (Recommended)

# .env
N8N_WEBHOOK_URL=https://n8n.example.com/webhook/chat

import { N8nAgent } from "@cloudbase/agent-adapter-n8n";

// Automatically reads N8N_WEBHOOK_URL from env
const agent = new N8nAgent();

agent.run({
  threadId: "thread-xxx",
  runId: "run-xxx",
  messages: [{ role: "user", content: "Hello, how are you?" }]
}).subscribe(event => {
  console.log(event);
});

Using Explicit Configuration

import { N8nAgent } from "@cloudbase/agent-adapter-n8n";

const agent = new N8nAgent({
  agentId: "my-n8n-agent",
  n8nConfig: {
    webhookUrl: "https://n8n.example.com/webhook/chat",
    // Optional: Basic Auth if n8n webhook has authentication enabled
    request: {
      headers: {
        Authorization: `Basic ${Buffer.from("user:pass").toString("base64")}`,
      },
    },
  }
});

agent.run({
  threadId: "thread-xxx",
  runId: "run-xxx",
  messages: [{ role: "user", content: "Hello, how are you?" }]
}).subscribe(event => {
  console.log(event);
});

Configuration

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | N8N_WEBHOOK_URL | Yes* | n8n Webhook URL |

* Required if not provided via n8nConfig.webhookUrl

n8nConfig

interface N8nConfig {
  /** n8n Webhook URL (falls back to N8N_WEBHOOK_URL env var) */
  webhookUrl?: string;

  /** Request configuration */
  request?: {
    timeout?: number;      // default: 120000ms
    headers?: Record<string, string>;
  };
}

Authentication

n8n webhooks support multiple authentication methods. Pass the appropriate headers via request.headers.

Basic Auth（推荐，n8n 中最易配置）：

const agent = new N8nAgent({
  n8nConfig: {
    webhookUrl: "https://n8n.example.com/webhook/chat",
    request: {
      headers: {
        Authorization: `Basic ${Buffer.from("user:pass").toString("base64")}`,
      },
    },
  },
});

n8n 配置：Webhook 节点 → Authentication → Basic Auth → 填入用户名和密码。

其他认证方式（Header Auth、JWT Auth）同理，通过 request.headers 传入对应的 HTTP Header 即可。

n8n Workflow Setup

Step 1: Create a Webhook Node

1. Add a Webhook node to your workflow
2. Configure:
   • Method: POST
   • Response Mode: Streaming (Important!)
   • Path: Your webhook path (e.g., chat)

Step 2: Add Authentication (Optional)

Configure authentication on the n8n Webhook node:

1. Set Authentication to Basic Auth（推荐）
2. Fill in username and password
3. Pass the matching Authorization header via request.headers in the adapter config

Step 3: Add AI Agent Node

1. Add an AI Agent node after the Webhook
2. Configure your LLM and tools as needed
3. Connect the AI Agent output to the webhook response

Step 4: No Special Configuration Required

Unlike other adapters, no special scripts or formats are required in n8n. The adapter handles plain text streaming automatically.

Supported Events

| Event | Description | |-------|-------------| | RUN_STARTED | Emitted when the request starts | | TEXT_MESSAGE_START | Emitted on first chunk received | | TEXT_MESSAGE_CONTENT | Emitted for each text chunk | | TEXT_MESSAGE_END | Emitted when stream ends | | RUN_FINISHED | Emitted when run completes | | RUN_ERROR | Emitted on HTTP or processing errors |

Limitations

• No Tool Call Events: Tool calls are handled internally within n8n workflow
• No Thinking Events: n8n does not output reasoning/thinking content
• Plain Text Only: Supports text streaming only

License

ISC