WxO Builder (Watsonx Orchestrate Development Tool)

WxO Builder is the essential toolkit for developers building on IBM Watsonx Orchestrate. It integrates directly into Visual Studio Code, allowing you to create, test, deploy, and manage your AI tools, agents, and connections without leaving your IDE.

🚀 Key Features

🛠️ Tool Creator & Manager

Build robust tools from scratch or templates.

• Visual & Code Editors: Toggle between a user-friendly Form view and a powerful JSON editor for your OpenAPI specs.
• Start Fast: Use built-in templates (Weather, Finance, Time, etc.) or import existing OpenAPI files.
• Import from URL: Quickly onboard public APIs.
• Auto-create Connection: Paste a full URL with an API key (e.g. ...?key=xxx&q=London) and automatically create both the connection and the tool with proper binding. The Form view fills in servers, path, and API key param name from the URL.

🧪 Advanced Testing (Local & Remote)

Verify your tools before deployment.

• Test and Generate Tool: Test endpoints and generate OpenAPI specs from responses. After generating, the view switches to Form View so you can review and edit.
• Run Local: Test the API endpoint directly from VS Code to ensure the backend is working.
• Run Remote: Execute the tool through Watson Orchestrate's engine. This verifies authentication, parameter mapping, and agent response generation.
• Copy as cURL: Debug easily by copying the exact request as a cURL command.

🤖 Agent Management

Create and orchestrate AI agents.

• Drag & Drop: Easily assign tools to agents.
• Export as MCP Server: Right-click an agent → Export as MCP Server to generate a self-contained MCP server project for Cursor, Claude Desktop, or other MCP clients. Includes chat, run_tool, list_tools, and get_agent tools.
• Full Agent Config: Edit name, description, instructions, model, Agent style (default, react, planner, react_intrinsic), Welcome message, Quick prompts (starter prompts), Tags, Hidden (hide from list), Hide reasoning.
• JSON Editor Tab: Edit the full agent JSON (including welcome_message, quick_prompts, tags, hidden, hide_reasoning) and save. Subset of API fields; note lists additional supported fields.
• Chat Interface: Interact with your agents and tools directly within VS Code to test the end-user experience.

📦 Installation

1. From Repository:
   • Clone the repository.
   • Run npm install and npm run compile.
   • Press F5 to launch the Extension Development Host.
2. From VSIX: Build with npm run package and install via "Install from VSIX..." in VS Code.

⚡ Getting Started Workflow

1. Configure the Extension

Open the Status & Diagnostics view.

1. Click Configure.
2. Enter your IBM Cloud API Key and Watson Orchestrate Instance URL.
3. Select your scope: draft (for development) or live (for production). (Tip: Use draft to avoid affecting production users.)

2. Create a Tool

1. Go to the Tools view.
2. Click the + (Create Tool) icon.
3. Choose OpenAPI Tool or Python Tool (for Python code upload).
4. OpenAPI: Pick a template (e.g., "World Time"), import from URL/file, or use Auto-create connection from URL — paste a full URL with API key to auto-fill servers, path, and API key param, then create connection and tool in one step.
5. Edit the specification in Form view or JSON editor.
6. Click Create Tool to register with Watson Orchestrate.

3. Test the Tool

1. Right-click your new tool and select Test Tool (or use the Test and Generate Tool tab when creating).
2. Generate: Paste a URL and params, run "Run Local", then click Generate from Response to infer an OpenAPI spec. The view switches to Form View for editing.
3. Local Test: Click "Run Local" to hit the API directly.
4. Remote Test: Click "Run Remote" to have Watson Orchestrate invoke it. (Requires an Agent ID configured in settings).

4. Create an Agent & Assign Tools

1. Go to the Agents view.
2. Click + (Create Agent).
3. Drag your tool from the Tools view and drop it onto the Agent.
4. Start a chat to test the agent's ability to use the tool.

🌐 Embedding Web Chat in Your App

You can embed your Watson Orchestrate agent into a web application using the official embed chat. See the IBM watsonx Orchestrate Web Chat documentation for full details.

Requirements

1. HTML: Add <!DOCTYPE html> and a mount point: <div id="root"></div>.
2. Configuration: Set window.wxOConfiguration with your orchestrationID, hostURL, crn, deploymentPlatform, and chatOptions.agentId before loading the script.
3. JWT token: Security is enabled by default. You must fetch a JWT from a backend and set window.wxOConfiguration.token before calling wxoLoader.init(). Without a valid token, the chat will not initialize.
4. Server-side JWT creation: A backend is required to store your RSA private key, sign JWTs with RS256, and optionally encrypt user_payload with IBM’s public key.

Minimal embed script example

<!DOCTYPE html>
<html>
<head>
  <script>
    window.wxOConfiguration = {
      orchestrationID: "your-orgID_orchestrationID",
      hostURL: "https://us-south.watson-orchestrate.cloud.ibm.com",
      rootElementID: "root",
      deploymentPlatform: "ibmcloud",
      crn: "your-org-crn",
      chatOptions: { agentId: "your-agent-id" },
    };

    async function getIdentityToken() {
      const response = await fetch('https://your-server.com/createJWT', {
        method: 'GET',
        credentials: 'include',
      });
      const token = await response.text();
      window.wxOConfiguration.token = token;
    }

    getIdentityToken().then(() => {
      const script = document.createElement('script');
      script.src = `${window.wxOConfiguration.hostURL}/wxochat/wxoLoader.js?embed=true`;
      script.addEventListener('load', () => wxoLoader.init());
      document.head.appendChild(script);
    });
  </script>
</head>
<body>
  <div id="root"></div>
</body>
</html>

Backend setup

Your server must expose an endpoint (e.g. /createJWT) that:

• Loads your RSA private key and IBM’s public key.
• Signs a JWT with RS256 containing claims such as sub, user_payload, and context.
• Returns the signed JWT as plain text.

IBM provides a full Node.js/Express example with key generation, JWT signing, and encryption in Getting Started.

Optional configuration

• agentEnvironmentId: Add to chatOptions for environment-specific agents.
• layout: Control display with form (float | fullscreen-overlay | custom), width, height, and showOrchestrateHeader.

🔧 Configuration Reference

❓ Troubleshooting

📚 Documentation

• DOCUMENTATION.md — Technical details and architecture
• CONTRIBUTING.md — How to contribute to WxO Builder
• CHANGELOG.md — Release history and version notes

📝 License

Apache-2.0 — See LICENSE for details.

👨‍💻 Author

Markus van Kempen — markus.van.kempen@gmail.com
19-Feb-2026