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

Node-RED node for invoking IBM watsonx Orchestrate agents

npm install @andreswagner/node-red-contrib-wxo-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:

1. Open Node-RED
2. Go to ☰ → Manage palette
3. Search for node-red-contrib-wxo-agent
4. Click Install

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

Quick Start

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

Usage

1. Configure Credentials

1. Drag the WxO Agent node onto your flow
2. Double-click to edit
3. Click the pencil icon next to Credentials to add new credentials
4. Enter your IBM Cloud API Key
5. 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:

1. Copy the flow JSON below
2. In Node-RED, go to ☰ → Import
3. Paste the JSON and click "Import"
4. 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
5. 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

Output

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

1. Copy the environment template:

   cp .env.example .env
   

2. 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
   

3. 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.