{"_id":"@andreswagner/node-red-contrib-wxo-agent","_rev":"3-4fa4433285c6616db7eace166d2fdac4","name":"@andreswagner/node-red-contrib-wxo-agent","dist-tags":{"latest":"0.1.6"},"versions":{"0.1.4":{"name":"@andreswagner/node-red-contrib-wxo-agent","version":"0.1.4","keywords":["node-red","node-red-contrib","watsonx","orchestrate","ibm","ai","agent"],"author":{"name":"Andres Wagner","email":"andres.wagner@gmail.com"},"license":"Apache-2.0","_id":"@andreswagner/node-red-contrib-wxo-agent@0.1.4","maintainers":[{"name":"andreswagner","email":"andres.wagner@gmail.com"}],"homepage":"https://github.com/andreswagner/spec_kit_nodered_test#readme","bugs":{"url":"https://github.com/andreswagner/spec_kit_nodered_test/issues"},"dist":{"shasum":"97a3e5db4c95df803a020f5a0d0d122c48eef8e5","tarball":"https://registry.npmjs.org/@andreswagner/node-red-contrib-wxo-agent/-/node-red-contrib-wxo-agent-0.1.4.tgz","fileCount":13,"integrity":"sha512-fonSU7m8oQAg6PTUx00mLrZvhJtKoGTbAfSaTK+8MuEg2hdcsPTTnLDP0ldsDqc1DqvdkVBGMakMqaaodH286g==","signatures":[{"sig":"MEYCIQD+EBZ0Yujc/8KP21RF0EoDPtVt9VMeKs+KfnzJ4x7xBwIhANa7i1K57vJdgJ6GnMzF22n7K4gNfX3rphUSuIqw8ikb","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":54200},"engines":{"node":">=18.0.0"},"gitHead":"e9cdeec205983da045e86f6693d9a5ac26e3a3e0","scripts":{"test":"mocha \"tests/**/*.test.js\"","verify-npm":"node scripts/verify-npm-package.js","setup-metadata":"node scripts/setup-package-metadata.js","verify-library":"node scripts/verify-nodered-library.js"},"_npmUser":{"name":"andreswagner","email":"andres.wagner@gmail.com"},"node-red":{"nodes":{"wxo-agent":"nodes/wxo-agent/wxo-agent.js","wxo-credentials":"nodes/wxo-credentials/wxo-credentials.js"},"version":">=3.0.0"},"repository":{"url":"git+https://github.com/andreswagner/spec_kit_nodered_test.git","type":"git"},"_npmVersion":"11.12.1","description":"Node-RED node for invoking IBM watsonx Orchestrate agents","directories":{},"_nodeVersion":"22.11.0","_hasShrinkwrap":false,"devDependencies":{"mocha":"^10.2.0","node-red":"^3.1.0","node-red-node-test-helper":"^0.3.3"},"_npmOperationalInternal":{"tmp":"tmp/node-red-contrib-wxo-agent_0.1.4_1776271111190_0.5719279774629771","host":"s3://npm-registry-packages-npm-production"}},"0.1.5":{"name":"@andreswagner/node-red-contrib-wxo-agent","version":"0.1.5","keywords":["node-red","node-red-contrib","watsonx","orchestrate","ibm","ai","agent"],"author":{"name":"Andres Wagner","email":"andres.wagner@gmail.com"},"license":"Apache-2.0","_id":"@andreswagner/node-red-contrib-wxo-agent@0.1.5","maintainers":[{"name":"andreswagner","email":"andres.wagner@gmail.com"}],"homepage":"https://github.com/andreswagner/spec_kit_nodered_test#readme","bugs":{"url":"https://github.com/andreswagner/spec_kit_nodered_test/issues"},"dist":{"shasum":"8b3ea805a1f593b004265bf79ae98f5e08c1e2fb","tarball":"https://registry.npmjs.org/@andreswagner/node-red-contrib-wxo-agent/-/node-red-contrib-wxo-agent-0.1.5.tgz","fileCount":13,"integrity":"sha512-NDzSMKoBXAp2MLZxPHyjR6F+TQwONxB2JyofU59Zhve9ZnHzQpYqpKHjQUEVPIZfP2oc8Rld/vBQMKCpo7sSoA==","signatures":[{"sig":"MEUCIQDMMAdagjENsarXPEUS/nPMXSKh+12LpjYfoNYwDCrfMgIgVrQ/s3tl3NGu1R99+tcuLGZBhqHVz99BYRFyWeqgvPI=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":54736},"engines":{"node":">=18.0.0"},"gitHead":"e868d6607102494970cbd290b833fbf34745622f","scripts":{"test":"mocha \"tests/**/*.test.js\"","verify-npm":"node scripts/verify-npm-package.js","setup-metadata":"node scripts/setup-package-metadata.js","verify-library":"node scripts/verify-nodered-library.js"},"_npmUser":{"name":"andreswagner","email":"andres.wagner@gmail.com"},"node-red":{"nodes":{"wxo-agent":"nodes/wxo-agent/wxo-agent.js","wxo-credentials":"nodes/wxo-credentials/wxo-credentials.js"},"version":">=3.0.0"},"repository":{"url":"git+https://github.com/andreswagner/spec_kit_nodered_test.git","type":"git"},"_npmVersion":"11.12.1","description":"Node-RED node for invoking IBM watsonx Orchestrate agents","directories":{},"_nodeVersion":"22.11.0","_hasShrinkwrap":false,"devDependencies":{"mocha":"^10.2.0","node-red":"^3.1.0","node-red-node-test-helper":"^0.3.3"},"_npmOperationalInternal":{"tmp":"tmp/node-red-contrib-wxo-agent_0.1.5_1776319386893_0.21967487940760466","host":"s3://npm-registry-packages-npm-production"}},"0.1.6":{"name":"@andreswagner/node-red-contrib-wxo-agent","version":"0.1.6","description":"Node-RED node for invoking IBM watsonx Orchestrate agents","keywords":["node-red","node-red-contrib","watsonx","orchestrate","ibm","ai","agent"],"author":{"name":"Andres Wagner","email":"andres.wagner@gmail.com"},"license":"Apache-2.0","repository":{"type":"git","url":"git+https://github.com/andreswagner/node-red-contrib-wxo-agent.git"},"engines":{"node":">=18.0.0"},"node-red":{"version":">=3.0.0","nodes":{"wxo-agent":"nodes/wxo-agent/wxo-agent.js","wxo-credentials":"nodes/wxo-credentials/wxo-credentials.js"}},"devDependencies":{"mocha":"^10.2.0","node-red":"^3.1.0","node-red-node-test-helper":"^0.3.3"},"scripts":{"test":"mocha \"tests/**/*.test.js\"","verify-npm":"node scripts/verify-npm-package.js","verify-library":"node scripts/verify-nodered-library.js","setup-metadata":"node scripts/setup-package-metadata.js"},"gitHead":"825d55fa1c931652b55b482439ff335cff9f7490","_id":"@andreswagner/node-red-contrib-wxo-agent@0.1.6","bugs":{"url":"https://github.com/andreswagner/node-red-contrib-wxo-agent/issues"},"homepage":"https://github.com/andreswagner/node-red-contrib-wxo-agent#readme","_nodeVersion":"22.11.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-FaA1H5mzvMH8kBUdg0j8utQbY7Zw5f2TIDQGcglRBHf8fAx+CKGklCvPhuf1GTTP+PUZyAKEk8FAW8oV3RmG7Q==","shasum":"cf088c036ca48ea7590d0a230414051f2b32a5ed","tarball":"https://registry.npmjs.org/@andreswagner/node-red-contrib-wxo-agent/-/node-red-contrib-wxo-agent-0.1.6.tgz","fileCount":13,"unpackedSize":54741,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQD9E0M76kp1/ihMBdqzrKb2t1KwdTfgUTHFO9wkZJmq4wIhAPWmgwUKdkD7AGMkBCmgWGY+0U/bIDNX+dAFhUaQ5ySI"}]},"_npmUser":{"name":"andreswagner","email":"andres.wagner@gmail.com"},"directories":{},"maintainers":[{"name":"andreswagner","email":"andres.wagner@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/node-red-contrib-wxo-agent_0.1.6_1776441280862_0.24000546370163023"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-15T16:38:31.073Z","modified":"2026-04-17T15:54:41.117Z","0.1.4":"2026-04-15T16:38:31.398Z","0.1.5":"2026-04-16T06:03:07.026Z","0.1.6":"2026-04-17T15:54:41.001Z"},"bugs":{"url":"https://github.com/andreswagner/node-red-contrib-wxo-agent/issues"},"author":{"name":"Andres Wagner","email":"andres.wagner@gmail.com"},"license":"Apache-2.0","homepage":"https://github.com/andreswagner/node-red-contrib-wxo-agent#readme","keywords":["node-red","node-red-contrib","watsonx","orchestrate","ibm","ai","agent"],"repository":{"type":"git","url":"git+https://github.com/andreswagner/node-red-contrib-wxo-agent.git"},"description":"Node-RED node for invoking IBM watsonx Orchestrate agents","maintainers":[{"name":"andreswagner","email":"andres.wagner@gmail.com"}],"readme":"# node-red-contrib-wxo-agent\n\nNode-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.\n\n## Installation\n\nInstall from npm:\n\n```bash\nnpm install node-red-contrib-wxo-agent\n```\n\nOr install via Node-RED's Manage Palette:\n1. Open Node-RED\n2. Go to ☰ → Manage palette\n3. Search for `node-red-contrib-wxo-agent`\n4. Click Install\n\nAfter installation, restart Node-RED to load the new nodes.\n\n## Quick Start\n\n1. **Install the package** (see Installation above)\n2. **Add credentials**: Drag the WxO Agent node to your flow, edit it, and configure your IBM Cloud API Key and Watson Orchestrate instance URL\n3. **Select an agent**: The agent dropdown will populate automatically\n4. **Send a message**: Use `msg.payload = \"Hello\"` to send a simple message\n\n## Usage\n\n### 1. Configure Credentials\n\n1. Drag the **WxO Agent** node onto your flow\n2. Double-click to edit\n3. Click the pencil icon next to Credentials to add new credentials\n4. Enter your IBM Cloud API Key\n5. Enter your Watson Orchestrate API URL (full instance URL, e.g., `https://api.us-south.watson-orchestrate.cloud.ibm.com/instances/your-instance-id`)\n\n### 2. Select an Agent\n\nAfter configuring credentials, the Agent dropdown will automatically populate with available agents. Click the refresh button to reload the list.\n\n### 3. Send Messages\n\nYou can send messages in two formats:\n\n**Simple string** (recommended for basic use):\n```javascript\nmsg.payload = \"What can you help me with?\";\nreturn msg;\n```\n\n**Full API request object** (for advanced use with additional parameters):\n```javascript\nmsg.payload = {\n  \"messages\": [\n    {\n      \"role\": \"user\",\n      \"content\": \"Hello\"\n    }\n  ],\n  \"additional_parameters\": {\n    \"id\": 4013386960470016\n  },\n  \"context\": {\n    \"id\": 4234274192490496\n  },\n  \"stream\": false\n};\nreturn msg;\n```\n\n### 4. Multi-turn Conversations\n\nThe node outputs `msg.topic` with the thread ID, which is automatically used in subsequent messages to continue the conversation:\n\n```javascript\n// First message starts a new conversation\nmsg.payload = \"Hello\";\nreturn msg;\n\n// Subsequent messages use the thread ID from msg.topic\nmsg.payload = \"Tell me more\";\n// msg.topic is automatically preserved for conversation continuity\nreturn msg;\n```\n\nTo force a new conversation:\n```javascript\nmsg.wxo_new_session = true;\nmsg.payload = \"Start fresh\";\nreturn msg;\n```\n\n## Example Flows\n\n### Multi-turn Conversation Example\n\nThis example demonstrates a complete multi-turn conversation with automatic thread ID preservation and error handling.\n\n**To use this flow:**\n\n1. Copy the flow JSON below\n2. In Node-RED, go to ☰ → Import\n3. Paste the JSON and click \"Import\"\n4. Configure the flow:\n   - Edit each **WxO Agent** node\n   - Replace `YOUR_CREDENTIALS_ID` with your actual credentials configuration ID\n   - Replace `YOUR_AGENT_ID` with your agent ID\n   - Update `Your Agent Name` with your agent's display name\n5. Deploy and click the **Start Conversation** inject button\n\n**What this flow demonstrates:**\n- Simple string input to start a conversation\n- Automatic thread ID preservation in `msg.topic` for conversation continuity\n- Multi-turn conversation where the agent remembers context from previous messages\n- Error handling with a Catch node\n- Debug output showing just the agent's response text\n\n**Flow JSON:**\n\n```json\n[\n  {\n    \"id\": \"flow-example-1\",\n    \"type\": \"tab\",\n    \"label\": \"WxO Agent Example - Multi-turn Conversation\",\n    \"disabled\": false,\n    \"info\": \"Example flow demonstrating multi-turn conversation with thread ID preservation\",\n    \"env\": []\n  },\n  {\n    \"id\": \"inject-1\",\n    \"type\": \"inject\",\n    \"z\": \"flow-example-1\",\n    \"name\": \"Start Conversation\",\n    \"props\": [{\"p\": \"payload\"}],\n    \"repeat\": \"\",\n    \"crontab\": \"\",\n    \"once\": false,\n    \"onceDelay\": 0.1,\n    \"topic\": \"\",\n    \"payload\": \"Hi, my name is Bob!\",\n    \"payloadType\": \"str\",\n    \"x\": 140,\n    \"y\": 100,\n    \"wires\": [[\"wxo-agent-1\"]]\n  },\n  {\n    \"id\": \"wxo-agent-1\",\n    \"type\": \"wxo-agent\",\n    \"z\": \"flow-example-1\",\n    \"name\": \"WxO Agent\",\n    \"wxoCredentials\": \"YOUR_CREDENTIALS_ID\",\n    \"agentId\": \"YOUR_AGENT_ID\",\n    \"agentName\": \"Your Agent Name\",\n    \"timeout\": 30000,\n    \"x\": 350,\n    \"y\": 100,\n    \"wires\": [[\"debug-1\", \"function-1\"]]\n  },\n  {\n    \"id\": \"debug-1\",\n    \"type\": \"debug\",\n    \"z\": \"flow-example-1\",\n    \"name\": \"Agent Response\",\n    \"active\": true,\n    \"tosidebar\": true,\n    \"console\": false,\n    \"tostatus\": false,\n    \"complete\": \"payload.choices[0].message.content\",\n    \"targetType\": \"msg\",\n    \"statusVal\": \"\",\n    \"statusType\": \"auto\",\n    \"x\": 550,\n    \"y\": 100,\n    \"wires\": []\n  },\n  {\n    \"id\": \"function-1\",\n    \"type\": \"function\",\n    \"z\": \"flow-example-1\",\n    \"name\": \"Continue Conversation\",\n    \"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;\",\n    \"outputs\": 1,\n    \"timeout\": 0,\n    \"noerr\": 0,\n    \"initialize\": \"\",\n    \"finalize\": \"\",\n    \"libs\": [],\n    \"x\": 200,\n    \"y\": 180,\n    \"wires\": [[\"wxo-agent-2\"]]\n  },\n  {\n    \"id\": \"wxo-agent-2\",\n    \"type\": \"wxo-agent\",\n    \"z\": \"flow-example-1\",\n    \"name\": \"WxO Agent\",\n    \"wxoCredentials\": \"YOUR_CREDENTIALS_ID\",\n    \"agentId\": \"YOUR_AGENT_ID\",\n    \"agentName\": \"Your Agent Name\",\n    \"timeout\": 30000,\n    \"x\": 350,\n    \"y\": 180,\n    \"wires\": [[\"debug-2\"]]\n  },\n  {\n    \"id\": \"debug-2\",\n    \"type\": \"debug\",\n    \"z\": \"flow-example-1\",\n    \"name\": \"Follow-up Response\",\n    \"active\": true,\n    \"tosidebar\": true,\n    \"console\": false,\n    \"tostatus\": false,\n    \"complete\": \"payload.choices[0].message.content\",\n    \"targetType\": \"msg\",\n    \"statusVal\": \"\",\n    \"statusType\": \"auto\",\n    \"x\": 570,\n    \"y\": 180,\n    \"wires\": []\n  },\n  {\n    \"id\": \"catch-1\",\n    \"type\": \"catch\",\n    \"z\": \"flow-example-1\",\n    \"name\": \"Error Handler\",\n    \"scope\": [\"wxo-agent-1\", \"wxo-agent-2\"],\n    \"uncaught\": false,\n    \"x\": 350,\n    \"y\": 260,\n    \"wires\": [[\"debug-error\"]]\n  },\n  {\n    \"id\": \"debug-error\",\n    \"type\": \"debug\",\n    \"z\": \"flow-example-1\",\n    \"name\": \"Error Output\",\n    \"active\": true,\n    \"tosidebar\": true,\n    \"console\": false,\n    \"tostatus\": false,\n    \"complete\": \"error\",\n    \"targetType\": \"msg\",\n    \"statusVal\": \"\",\n    \"statusType\": \"auto\",\n    \"x\": 550,\n    \"y\": 260,\n    \"wires\": []\n  }\n]\n```\n\n**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.\n\n## Input\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `payload` | string/object | Message to send to the agent. Can be:<br>- Simple string (e.g., `\"Hello\"`)<br>- Full API request object with `messages` array (see official API docs) |\n| `topic` | string | (Optional) Thread ID for conversation continuation |\n| `wxo_new_session` | boolean | (Optional) Force new conversation |\n\n## Output\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `payload` | object | Full API response object (OpenAI-compatible format) |\n| `topic` | string | Thread ID for conversation continuation |\n\nThe `payload` object is the complete API response and includes:\n- `id`: string - Unique response identifier\n- `object`: string - Response type (e.g., \"chat.completion\")\n- `created`: number - Unix timestamp\n- `model`: string - Model used for response\n- `choices`: array - Response choices containing:\n  - `message`: object with `role` and `content` (the agent's response text)\n  - `finish_reason`: string\n- `thread_id`: string - Conversation thread ID for multi-turn\n\nAccess the agent's response text via: `msg.payload.choices[0].message.content`\n\n## Error Handling\n\nOn error, the node outputs:\n\n```javascript\nmsg.error = {\n  code: \"ERROR_CODE\",\n  message: \"Human readable message\",\n  details: { /* API response */ },\n  recoverable: true/false\n}\n```\n\nUse a Catch node to handle errors in your flow.\n\n## Features\n\n- ✅ Simple string or full API request object input\n- ✅ Automatic authentication with IBM Cloud IAM\n- ✅ Multi-turn conversation support via `msg.topic`\n- ✅ Agent selection from dropdown\n- ✅ Comprehensive error handling\n- ✅ OpenAI-compatible response format\n\n## Requirements\n\n- Node-RED 3.0.0 or higher\n- Node.js 18.0.0 or higher\n- IBM Cloud account with watsonx Orchestrate access\n- Valid IBM Cloud API Key\n\n## Development\n\nFor developers contributing to this package:\n\n### Running Tests\n\n1. Copy the environment template:\n   ```bash\n   cp .env.example .env\n   ```\n\n2. Edit `.env` with your actual credentials:\n   ```\n   # Required for API integration tests\n   IBM_CLOUD_API_KEY=your-api-key\n   WXO_BASE_URL=https://api.us-south.watson-orchestrate.cloud.ibm.com/instances/your-instance-id\n   \n   # Optional: Required only for NPM publication testing (T031)\n   NPM_USERNAME=your-npm-username\n   NPM_TOKEN=your-npm-token\n   # NPM_REGISTRY=https://registry.npmjs.org/  # Optional: if using private registry\n   ```\n\n3. Run the tests:\n   ```bash\n   npm install\n   npm test\n   ```\n\n### Test Structure\n\nThe test suite includes:\n\n- **Unit Tests** (`tests/unit/`): Component/library tests for underlying logic\n  - Token manager, API client, input parsing, etc.\n  - These test the core functionality without Node-RED runtime\n\n- **Integration Tests** (`tests/integration/`): Node-RED node tests using `node-red-node-test-helper`\n  - Test the actual node behavior in Node-RED runtime\n  - Create test flows and assert node properties and output\n  - Follow Node-RED's recommended testing approach\n\nThe tests use real API calls to verify functionality. Tests will skip gracefully if credentials are not configured.\n\n### NPM Publication\n\nFor instructions on testing and publishing the package to NPM, see [NPM_PUBLICATION.md](./NPM_PUBLICATION.md).\n\nQuick verification:\n```bash\n# Setup package metadata (author and repository) - auto-detects from git\nnpm run setup-metadata\n\n# Verify NPM publication requirements\nnpm run verify-npm\n\n# Verify Node-RED Library requirements (includes LICENSE, author, repository)\nnpm run verify-library\n```\n\n**Important**: After publishing to NPM, register your node with the [Node-RED Flow Library](https://flows.nodered.org/add/node) to make it discoverable in Node-RED's Manage Palette.\n\n## Support\n\nFor issues, questions, or contributions, please visit the [GitHub repository](https://github.com/your-username/node-red-contrib-wxo-agent) (update with actual repository URL when available).\n\n## License\n\nApache-2.0\n\n---\n\n**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.\n\n","readmeFilename":"README.md"}