node-red-agent-ai

Drop an AI agent into any Node-RED flow — it runs a reasoning loop, calls MCP tools, and returns the final answer.

What you get

• ai-agent-config: stores provider credentials and shared defaults
• ai-agent: executes a reasoning loop, can call MCP tools, then returns final output
• Provider support: OpenAI GPT, Google Gemini, AWS Bedrock, z.ai (GLM), Azure OpenAI, Azure AI Inference

Architecture

The node runtime is organized with an hexagonal architecture to keep business logic decoupled from framework details.

• Domain layer: core reasoning loop and policies
• Application layer: use case orchestration
• Adapters layer: Node-RED I/O mapping, LangChain model factory, MCP client integration

Current structure:

nodes/
  domain/
  application/
  adapters/
    nodered/
    llm/
    tools/

Requirements

• Node.js 18+
• Node-RED 3+

Installation

From the Node-RED editor:

1. Go to Manage palette > Install tab
2. Search for @qomodome/node-red-agent-ai
3. Click Install

From the command line:

npm install @qomodome/node-red-agent-ai

Use the node

1. Add an ai-agent-config node and set credentials for the provider you want to use.
2. (Optional) Add one or more ai-mcp-server-config nodes if you want external tools.
3. Add an ai-agent node and link it to your ai-agent-config.
4. Pick provider/model in the node UI (or override from msg.ai).
5. Send a message like this:

msg.payload = {
  input: "Summarize today tickets in 5 bullet points"
};

msg.ai = {
  provider: "gemini", // openai | gemini | bedrock | zai | azure | azure-ai
  model: "gemini-3.5-flash"
};

return msg;

If msg.ai is missing, ai-agent uses the defaults configured in the node editor.

Chat Model node (recommended)

Attach an ai-chat-model config node to the ai-agent via its Chat Model field. It carries the provider, credentials, and model. Supported providers: OpenAI, Anthropic Claude (API key or OCP gateway OAuth), Google Gemini, AWS Bedrock, z.ai (GLM), Azure OpenAI, Azure AI Inference, and any OpenAI-compatible endpoint. The legacy inline provider fields on ai-agent still work when no chat model is attached.

Claude via native OAuth (beta)

For Anthropic Claude, the chat model supports three auth modes: an API key, the OCP gateway (oauth-ocp, OpenAI-compatible — recommended), and native OAuth (oauth-native, beta). Native OAuth uses a subscription token from claude setup-token: paste the access token (and, if you have it, the refresh token to enable auto-refresh) into the chat model node. The OAuth endpoint defaults target the Claude CLI client and may need adjustment for your account — native OAuth is unverified end-to-end and should be treated as beta; prefer the OCP gateway when available.

Memory node

Attach an ai-memory config node to the ai-agent via its Memory field to keep conversation history across messages. It is a buffer window: the last Window size messages per session are replayed to the model. The session id is read from msg at the configured Session key path (default msg.sessionId), falling back to "default". History is stored in the chosen Node-RED context store.

Output Parser node

Attach an ai-output-parser config node to the ai-agent via its Output Parser field to force structured JSON output. The schema is appended to the system prompt as a format instruction, and the final output is parsed into msg.payload (a JSON value). Validation is lightweight: valid JSON plus any top-level keys listed in the schema's required array. On a parse failure the raw text stays in msg.payload and the reason is reported in msg.aiAgent.parseError.

Tool nodes

Wire ai-tool nodes to the ai-agent's second output. The agent discovers them at deploy time and offers them to the model alongside any MCP tools.

• Function mode runs an inline async (args) => result body.
• Flow mode emits { payload: args } on the tool's output; build the logic downstream and wire the result back to the tool's input. The returned msg.payload becomes the tool result.

Tool name, Description, and Args schema are shown to the model. Wired tools and MCP tools are merged; on a name collision the MCP tool wins.

Node reference

ai-agent-config

• name (optional): label in editor
• openaiApiKey (optional): used when provider is openai
• googleApiKey (optional): used when provider is gemini
• awsAccessKeyId (optional): AWS key id for bedrock
• awsSecretAccessKey (optional): AWS secret for bedrock
• awsSessionToken (optional): AWS session token when needed
• zaiApiKey (optional): used when provider is zai
• azureOpenAIApiKey (optional): used when provider is azure
• azureAiApiKey (optional): used when provider is azure-ai

ai-mcp-server-config

• name (optional): label in editor
• transport (required): streamableHttp | sse | stdio
• url (required for HTTP transports): MCP endpoint URL
• command (required for stdio): executable to spawn
• argsRaw (optional): one argument per line for stdio
• envJson (optional): JSON object with env vars for stdio

ai-agent

• agent (required): reference to ai-agent-config
• provider (required): openai | gemini | bedrock | zai | azure | azure-ai
• model (optional): provider model override (z.ai defaults to glm-5.2)
• systemPrompt (optional): persistent agent instruction
• awsRegion (optional): used for bedrock (default us-east-1)
• zaiBaseUrl (optional): z.ai base URL (default https://api.z.ai/api/paas/v4)
• azureEndpoint (required for azure): e.g. https://<resource>.openai.azure.com
• azureDeployment (required for azure): Azure OpenAI deployment name
• azureApiVersion (optional for azure): default 2024-10-21
• azureAiEndpoint (required for azure-ai): e.g. https://<resource>.services.ai.azure.com/models
• azureAiApiVersion (optional for azure-ai): API version query param
• mcpServerIds (optional): linked ai-mcp-server-config nodes
• debugLogs (optional): verbose runtime logs
• advanced limits (optional): maxIterations, maxToolCalls, rateLimitRetries, rateLimitBackoffMs

Message contract

Input:

• msg.payload string or object with input
• optional overrides in msg.ai:
  • provider: openai · gemini · bedrock · zai · azure · azure-ai
  • model: model id/name
  • mcpServers: array of MCP server configs

Output on success:

• msg.payload: final assistant text
• msg.aiAgent.trace: iteration-by-iteration trace
• msg.aiAgent.usage: counters and timings

Error behavior:

• Errors are propagated with node.error(err, msg) and done(err)
• Use standard Node-RED catch nodes for handling
• Internal handling is limited to rate-limit retry/backoff

Local Docker run

From repository root:

docker compose up --build

Then open:

http://localhost:1880

Notes:

• The setup installs this local module inside /data/node_modules
• Flows persist in a named Docker volume
• Rebuild after source changes:

docker compose up --build --force-recreate

Development

Run tests:

npm test

Publishing

The publish process is automated via GitHub Actions when pushing a tag that matches the package.json version. To publish a new version:

npm version X.Y.Z
git push origin main vX.Y.Z

For manual publish (not recommended - use only for emergencies):

0. Verify you have an npm account and are logged in with npm whoami. If not, run npm login --scope=@qomodome --auth-type=web and follow the prompts.
1. Update version in package.json
2. Verify contents with npm pack --dry-run
3. Publish to npm:

npm publish --access public

Credits

This package is a fork of qomodome/node-red-agent-ai, extended by konceptnet with the n8n-style component model: a configurable Chat Model node (OpenAI, Anthropic Claude with API key / OCP gateway / native OAuth, Azure OpenAI, Azure AI Inference, z.ai, Gemini, Bedrock, and any OpenAI-compatible endpoint), Memory, Output Parser, and wired Tool nodes.

License

MIT License. See LICENSE for details.