Embedding the agent with web applications

Embedded chat enables applications to integrate agents directly into web and client experiences. This integration supports secure communication, flexible UI customization, and event handling to deliver rich conversational experiences, and introduces important security considerations to ensure that access, identity, and user context are handled correctly.

This procedure defines the prerequisites and steps that you need to follow to embed the agent into a web application.

Draft and Live environments for embedded chat

Draft and Live environments affect which version of your agent you want to invoke by the embedded script and how changes are reflected at runtime. Understanding which environment your embedded script targets helps prevent unintentional testing against production or showing unfinished behavior to users.

  • Draft
    The draft environment is intended for development and validation.
    Embedded scripts that you copy from Draft explicitly target the draft variant, where you can test configuration changes, conversation logic, and UI behavior without impacting users.

  • Live
    The live environment represents the deployed, production-ready version of your agent. Live embeds provide stable, versioned behavior appropriate for production environments. Changes that you make in the draft are not reflected in live until you explicitly deploy your agent.

Prerequisites

To successfully run the agent within the embedded chat, your application must meet the following requirements:

  • Include a server-side component (local or cloud-based)
    A server is required to securely store and use private keys, sign requests, and interact with watsonx Orchestrate APIs.

  • Include an HTML root container
    The embedding page must contain an HTML element with the ID root.

  • Use HTML strict mode
    The page that embeds the web chat must declare HTML strict mode by including the <!DOCTYPE html> directive.

  • Configure embedded chat security
    Security is enabled by default in both Draft and Live environments but not configured. You must explicitly configure it as described in the Configuring security for embedded chat section. You might be able to see the chat widget in the web application, but it does not initialize unless the required cryptographic keys are configured and validated by the service.

  • Embed the script within the <body> element
    Place the script inside the <body> tag to ensure that the DOM is available when the script runs, and that the root element can be resolved correctly at initialization time.

Procedure to embed agents with web applications

You can embed the chat widget for an agent into your application by using the generated embedded script from the agent UI. If you prefer to generate the script by using a CLI command, see Integrating agents with web applications in the IBM watsonx Orchestrate Agent Development Kit documentation. The following procedure focuses on the UI-based workflow.

Notes:

  • For IBM watsonx Orchestrate On-premises deployment:
  • Version 5.2.1: Copying the embedded script from the agent UI is not supported. Use the ADK docs to get the embedded script. For more details, see Embedding Agent Web Chat.
  • Versions 5.2.2 and later: You can directly copy the embedded scripts from the agent UI.

  1. Access the agent configuration:

    • Go to the agent configuration page.
    • Navigate to Channels > Embedded agent.

  2. Select the environment:

    • Use Draft mode for testing and previewing the chat widget in the web application.
    • Use Live mode to get the script for the deployed agent. This tab remains disabled until the agent is deployed.

  3. Copy the embedded script:

    • Click Copy to clipboard to copy the generated script.

    The following code is an example of the embedded script:

    <script>
  window.wxOConfiguration = {
    orchestrationID: "your-orgID_orchestrationID", // Adds control over chat display mode (e.g., fullscreen)
    hostURL: "https://dl.watson-orchestrate.ibm.com", // or region-specific host
    rootElementID: "root",
    showLauncher: false,
    deploymentPlatform: "ibmcloud", // Required for IBM Cloud embed, can be skipped for other embed scenarios
    crn: "your-org-crn", // Required for IBM Cloud embed, can be skipped for other embed scenarios. For more information, see https://cloud.ibm.com/docs/key-protect?topic=key-protect-retrieve-instance-ID&interface=ui
    chatOptions: {
      agentId: "your-agent-id",
      agentEnvironmentId: "your-agent-env-id",
    },
  };
  setTimeout(function () {
    const script = document.createElement("script");
    script.src = `${window.wxOConfiguration.hostURL}/wxochat/wxoLoader.js?embed=true`;
    script.addEventListener("load", function () {
      wxoLoader.init();
    });
    document.head.appendChild(script);
  }, 0);
</script>

  4. Add the script to your web page:

    • Edit the HTML source of the page where you want the chat widget to appear.
    • Paste the embedded script inside the <body> tag, as close as possible to the closing </body> tag for optimal page load performance.
    • Ensure the root element is present.

    Example HTML structure:

    <body>
  <div id="root"></div>
  <script src="path-to-embed-script.js"></script>
</body>

You can now open the website to preview the chat widget and test the integration.

What to do next

Paste the same script into each page where you want the agent chat to appear. Do not include the script more than once on the same page to avoid loading conflicts.

Use the APIs available to apply custom styling and layout to the chat UI, enable feedback, or handle context variables to customize users' conversations with an agent. For more information, see the following resources: