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;

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

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.