@andreswagner/node-red-contrib-wxo-agent

v0.1.6

Published

15 days ago

Node-RED node for invoking IBM watsonx Orchestrate agents

0High
0Medium
0Low

andreswagner

node-red node-red-contrib watsonx orchestrate ibm ai agent

node-red-contrib-wxo-agent

Node-RED node for invoking IBM watsonx Orchestrate agents. Easily integrate AI orchestration capabilities into your Node-RED flows with support for multi-turn conversations and flexible input formats.

Installation

Install from npm:

npm install node-red-contrib-wxo-agent

Or install via Node-RED's Manage Palette:

Open Node-RED
Go to ☰ → Manage palette
Search for node-red-contrib-wxo-agent
Click Install

After installation, restart Node-RED to load the new nodes.

Quick Start

Install the package (see Installation above)
Add credentials: Drag the WxO Agent node to your flow, edit it, and configure your IBM Cloud API Key and Watson Orchestrate instance URL
Select an agent: The agent dropdown will populate automatically
Send a message: Use msg.payload = "Hello" to send a simple message

Usage

1. Configure Credentials

Drag the WxO Agent node onto your flow
Double-click to edit
Click the pencil icon next to Credentials to add new credentials
Enter your IBM Cloud API Key
Enter your Watson Orchestrate API URL (full instance URL, e.g., https://api.us-south.watson-orchestrate.cloud.ibm.com/instances/your-instance-id)

2. Select an Agent

After configuring credentials, the Agent dropdown will automatically populate with available agents. Click the refresh button to reload the list.

3. Send Messages

You can send messages in two formats:

Simple string (recommended for basic use):

msg.payload = "What can you help me with?";
return msg;

Full API request object (for advanced use with additional parameters):

msg.payload = {
  "messages": [
    {
      "role": "user",
      "content": "Hello"
    }
  ],
  "additional_parameters": {
    "id": 4013386960470016
  },
  "context": {
    "id": 4234274192490496
  },
  "stream": false
};
return msg;

4. Multi-turn Conversations

The node outputs msg.topic with the thread ID, which is automatically used in subsequent messages to continue the conversation:

// First message starts a new conversation
msg.payload = "Hello";
return msg;

// Subsequent messages use the thread ID from msg.topic
msg.payload = "Tell me more";
// msg.topic is automatically preserved for conversation continuity
return msg;

To force a new conversation:

msg.wxo_new_session = true;
msg.payload = "Start fresh";
return msg;

Example Flows

Multi-turn Conversation Example

This example demonstrates a complete multi-turn conversation with automatic thread ID preservation and error handling.

To use this flow:

Copy the flow JSON below
In Node-RED, go to ☰ → Import
Paste the JSON and click "Import"
Configure the flow:
- Edit each WxO Agent node
- Replace YOUR_CREDENTIALS_ID with your actual credentials configuration ID
- Replace YOUR_AGENT_ID with your agent ID
- Update Your Agent Name with your agent's display name
Deploy and click the Start Conversation inject button

What this flow demonstrates:

Simple string input to start a conversation
Automatic thread ID preservation in msg.topic for conversation continuity
Multi-turn conversation where the agent remembers context from previous messages
Error handling with a Catch node
Debug output showing just the agent's response text

Flow JSON:

[
  {
    "id": "flow-example-1",
    "type": "tab",
    "label": "WxO Agent Example - Multi-turn Conversation",
    "disabled": false,
    "info": "Example flow demonstrating multi-turn conversation with thread ID preservation",
    "env": []
  },
  {
    "id": "inject-1",
    "type": "inject",
    "z": "flow-example-1",
    "name": "Start Conversation",
    "props": [{"p": "payload"}],
    "repeat": "",
    "crontab": "",
    "once": false,
    "onceDelay": 0.1,
    "topic": "",
    "payload": "Hi, my name is Bob!",
    "payloadType": "str",
    "x": 140,
    "y": 100,
    "wires": [["wxo-agent-1"]]
  },
  {
    "id": "wxo-agent-1",
    "type": "wxo-agent",
    "z": "flow-example-1",
    "name": "WxO Agent",
    "wxoCredentials": "YOUR_CREDENTIALS_ID",
    "agentId": "YOUR_AGENT_ID",
    "agentName": "Your Agent Name",
    "timeout": 30000,
    "x": 350,
    "y": 100,
    "wires": [["debug-1", "function-1"]]
  },
  {
    "id": "debug-1",
    "type": "debug",
    "z": "flow-example-1",
    "name": "Agent Response",
    "active": true,
    "tosidebar": true,
    "console": false,
    "tostatus": false,
    "complete": "payload.choices[0].message.content",
    "targetType": "msg",
    "statusVal": "",
    "statusType": "auto",
    "x": 550,
    "y": 100,
    "wires": []
  },
  {
    "id": "function-1",
    "type": "function",
    "z": "flow-example-1",
    "name": "Continue Conversation",
    "func": "// msg.topic contains the thread ID from the previous response\n// This is automatically preserved for conversation continuity\nmsg.payload = \"What's my name?\";\nreturn msg;",
    "outputs": 1,
    "timeout": 0,
    "noerr": 0,
    "initialize": "",
    "finalize": "",
    "libs": [],
    "x": 200,
    "y": 180,
    "wires": [["wxo-agent-2"]]
  },
  {
    "id": "wxo-agent-2",
    "type": "wxo-agent",
    "z": "flow-example-1",
    "name": "WxO Agent",
    "wxoCredentials": "YOUR_CREDENTIALS_ID",
    "agentId": "YOUR_AGENT_ID",
    "agentName": "Your Agent Name",
    "timeout": 30000,
    "x": 350,
    "y": 180,
    "wires": [["debug-2"]]
  },
  {
    "id": "debug-2",
    "type": "debug",
    "z": "flow-example-1",
    "name": "Follow-up Response",
    "active": true,
    "tosidebar": true,
    "console": false,
    "tostatus": false,
    "complete": "payload.choices[0].message.content",
    "targetType": "msg",
    "statusVal": "",
    "statusType": "auto",
    "x": 570,
    "y": 180,
    "wires": []
  },
  {
    "id": "catch-1",
    "type": "catch",
    "z": "flow-example-1",
    "name": "Error Handler",
    "scope": ["wxo-agent-1", "wxo-agent-2"],
    "uncaught": false,
    "x": 350,
    "y": 260,
    "wires": [["debug-error"]]
  },
  {
    "id": "debug-error",
    "type": "debug",
    "z": "flow-example-1",
    "name": "Error Output",
    "active": true,
    "tosidebar": true,
    "console": false,
    "tostatus": false,
    "complete": "error",
    "targetType": "msg",
    "statusVal": "",
    "statusType": "auto",
    "x": 550,
    "y": 260,
    "wires": []
  }
]

Note: The msg.topic property is automatically set by the WxO Agent node with the thread ID from the API response. When you pass msg to the next agent node, the thread ID is automatically preserved, enabling conversation continuity. The function node in this example demonstrates this - it receives the message with msg.topic already set and simply updates the payload for the follow-up question.

Input

| Property | Type | Description | |----------|------|-------------| | payload | string/object | Message to send to the agent. Can be:- Simple string (e.g., "Hello")- Full API request object with messages array (see official API docs) | | topic | string | (Optional) Thread ID for conversation continuation | | wxo_new_session | boolean | (Optional) Force new conversation |

Output

| Property | Type | Description | |----------|------|-------------| | payload | object | Full API response object (OpenAI-compatible format) | | topic | string | Thread ID for conversation continuation |

The payload object is the complete API response and includes:

id: string - Unique response identifier
object: string - Response type (e.g., "chat.completion")
created: number - Unix timestamp
model: string - Model used for response
choices: array - Response choices containing:
- message: object with role and content (the agent's response text)
- finish_reason: string
thread_id: string - Conversation thread ID for multi-turn

Access the agent's response text via: msg.payload.choices[0].message.content

Error Handling

On error, the node outputs:

msg.error = {
  code: "ERROR_CODE",
  message: "Human readable message",
  details: { /* API response */ },
  recoverable: true/false
}

Use a Catch node to handle errors in your flow.

Features

✅ Simple string or full API request object input
✅ Automatic authentication with IBM Cloud IAM
✅ Multi-turn conversation support via msg.topic
✅ Agent selection from dropdown
✅ Comprehensive error handling
✅ OpenAI-compatible response format

Requirements

Node-RED 3.0.0 or higher
Node.js 18.0.0 or higher
IBM Cloud account with watsonx Orchestrate access
Valid IBM Cloud API Key

Development

For developers contributing to this package:

Running Tests

Copy the environment template:
```
cp .env.example .env
```

Edit .env with your actual credentials:

# Required for API integration tests
IBM_CLOUD_API_KEY=your-api-key
WXO_BASE_URL=https://api.us-south.watson-orchestrate.cloud.ibm.com/instances/your-instance-id
   
# Optional: Required only for NPM publication testing (T031)
NPM_USERNAME=your-npm-username
NPM_TOKEN=your-npm-token
# NPM_REGISTRY=https://registry.npmjs.org/  # Optional: if using private registry

Run the tests:
```
npm install
npm test
```

Test Structure

The test suite includes:

Unit Tests (tests/unit/): Component/library tests for underlying logic
- Token manager, API client, input parsing, etc.
- These test the core functionality without Node-RED runtime
Integration Tests (tests/integration/): Node-RED node tests using node-red-node-test-helper
- Test the actual node behavior in Node-RED runtime
- Create test flows and assert node properties and output
- Follow Node-RED's recommended testing approach

The tests use real API calls to verify functionality. Tests will skip gracefully if credentials are not configured.

NPM Publication

For instructions on testing and publishing the package to NPM, see NPM_PUBLICATION.md.

Quick verification:

# Setup package metadata (author and repository) - auto-detects from git
npm run setup-metadata

# Verify NPM publication requirements
npm run verify-npm

# Verify Node-RED Library requirements (includes LICENSE, author, repository)
npm run verify-library

Important: After publishing to NPM, register your node with the Node-RED Flow Library to make it discoverable in Node-RED's Manage Palette.

Support

For issues, questions, or contributions, please visit the GitHub repository (update with actual repository URL when available).

License

Apache-2.0

Note: This package is published to npm as node-red-contrib-wxo-agent. For development installation from a local path, see the Development section above.