Skip to main content

<ai12z-container> Web Control

Overview​

The ai12z-container is a web component that embeds an ai12z-powered experience — such as a mortgage rate calculator, restaurant finder, product recommender, or any custom agent workflow — directly into your web page. Each container is identified by a key-name that maps to a configured custom integration, and an instance-id that uniquely identifies it when multiple containers appear on the same page.

You can place several containers side-by-side, each running a completely independent agent, and pass dynamic runtime parameters to any of them via JavaScript.

Setup​

Add the following to the <head> of every page that uses the container control:

<script
  type="module"
  src="https://cdn.ai12z.net/pkg/ai12z@latest/dist/esm/library.js"
></script>
<link
  rel="stylesheet"
  href="https://cdn.ai12z.net/pkg/ai12z@latest/dist/library/library.css"
/>

You can then place one or more <ai12z-container> tags anywhere in your HTML.

Attributes​

AttributeRequiredDescriptionExample
key-nameYesIdentifies which agent / workflow to load. Must match a configured agent key in your ai12z portal.key-name="LocalRestaurants"
instance-idYesA unique string that distinguishes this element when multiple containers exist on the same page.instance-id="1234"
data-keyYesYour agent API key. Can be set via HTML attribute or JavaScript. See Agent Settings for your key.data-key="YOUR_API_KEY"
data-modeYesRuntime environment. Use dev for testing, prod (default) for production.data-mode="dev"
parametersOptionalA JSON-stringified object of dynamic values passed to the agent at runtime (e.g., pre-fill form fields).parameters='{"termYears":"15"}'

Basic Usage​

Single Container​

<ai12z-container data-key="YOUR_API_KEY" key-name="LocalRestaurants" instance-id="1234">
</ai12z-container>

Multiple Containers Side-by-Side​

Place independent containers in a flex layout — each loads its own agent and operates independently:

<div style="display:flex;">

  <div style="width:50%;">
    <ai12z-container data-key="YOUR_API_KEY" key-name="LocalRestaurants" instance-id="1234">
    </ai12z-container>
  </div>

  <div style="width:50%;">
    <ai12z-container data-key="YOUR_API_KEY" key-name="Mortgageratecalculator" instance-id="5678">
    </ai12z-container>
  </div>

</div>

Passing Parameters via JavaScript​

Use setAttribute("parameters", JSON.stringify({...})) to pass dynamic data to a specific container instance after the page loads. Target the correct instance using the instance-id attribute selector.

<script>
  document.addEventListener("DOMContentLoaded", function () {
    const instance2 = document.querySelector('ai12z-container[instance-id="5678"]')
    instance2.setAttribute("parameters", JSON.stringify({ termYears: "15" }))
  })
</script>

This is useful when values come from user interactions, URL parameters, or other page state — such as pre-filling a mortgage calculator with a specific loan term.

Configure Attributes via JavaScript​

All attributes can be set or updated dynamically in JavaScript after the component mounts:

<script>
  document.addEventListener("DOMContentLoaded", function () {
    const container = document.querySelector('ai12z-container[instance-id="1234"]')
    container.setAttribute("data-key", "YOUR_API_KEY")
    container.setAttribute("data-mode", "dev")
    container.setAttribute("parameters", JSON.stringify({ city: "Austin" }))
  })
</script>

Complete Example​

The example below renders two containers side-by-side: a local restaurant finder on the left and a mortgage rate calculator on the right. The mortgage calculator is pre-configured with a 15-year term via JavaScript.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>ai12z Container Control</title>

    <!-- ai12z web components -->
    <script
      type="module"
      src="https://cdn.ai12z.net/pkg/ai12z@latest/dist/esm/library.js"
    ></script>
    <link
      rel="stylesheet"
      href="https://cdn.ai12z.net/pkg/ai12z@latest/dist/library/library.css"
    />
  </head>

  <body>

    <div style="display:flex;">

      <div style="width:50%;">
        <ai12z-container data-key="YOUR_API_KEY" key-name="LocalRestaurants" instance-id="1234">
        </ai12z-container>
      </div>

      <div style="width:50%;">
        <ai12z-container data-key="YOUR_API_KEY" key-name="Mortgageratecalculator" instance-id="5678">
        </ai12z-container>
      </div>

    </div>

    <script>
      document.addEventListener("DOMContentLoaded", function () {
        const instance2 = document.querySelector('ai12z-container[instance-id="5678"]')
        instance2.setAttribute("parameters", JSON.stringify({ termYears: "15" }))
      })
    </script>

  </body>
</html>

Use Cases​

Scenariokey-name valueExample parameters
Local restaurant finderLocalRestaurants{ "city": "Austin", "cuisine": "Italian"}
Mortgage rate calculatorMortgageratecalculator{ "termYears": "15", "amount": "300000" }
Product recommenderProductRecommender{ "category": "laptops" }
Support ticket formSupportTicket{ "priority": "high" }

Troubleshooting​

Container Does Not Render​

  • Verify key-name exactly matches the custom integration key configured in your ai12z portal.
  • Confirm the CDN script and stylesheet are loaded in <head> before the container tag.
  • Check the browser console for network or JavaScript errors.

Parameters Not Applied​

  • Ensure setAttribute is called inside a DOMContentLoaded listener so the element is available.
  • Confirm instance-id in the JavaScript selector matches the attribute on the HTML element exactly.
  • parameters must be a valid JSON string — use JSON.stringify({...}) rather than writing JSON manually.

Multiple Containers Interfering​

  • Each container must have a unique instance-id. Using duplicate IDs causes unpredictable behaviour.
  • Use the attribute selector [instance-id="..."] (not id) to target a specific container in JavaScript.