`<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

Attribute	Required	Description	Example
`key-name`	Yes	Identifies which agent / workflow to load. Must match a configured agent key in your ai12z portal.	`key-name="LocalRestaurants"`
`instance-id`	Yes	A unique string that distinguishes this element when multiple containers exist on the same page.	`instance-id="1234"`
`data-key`	Yes	Your agent API key. Can be set via HTML attribute or JavaScript. See Agent Settings for your key.	`data-key="YOUR_API_KEY"`
`data-mode`	Yes	Runtime environment. Use `dev` for testing, `prod` (default) for production.	`data-mode="dev"`
`parameters`	Optional	A JSON-stringified object of dynamic values passed to the agent at runtime (e.g., pre-fill form fields).	`parameters='{"termYears":"15"}'`
`render-type`	Optional	Controls how the widget response is rendered.	`render-type="integration"`
`content-template`	Optional	Custom Handlebars template used to render the content response	`content-template="<div>{{{answer}}}</div>"`

Note: When setting render-type from JavaScript, use the renderType property (el.renderType = "content"). When using setAttribute(), use the HTML attribute name render-type.

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>

Render Types

Controls how the widget response is rendered.

Type: content | carousel | template | integration

Default: integration

Content rendering

Use render-type="content" to render knowledge-base content.

For this render type, you can customize the response using the content-template attribute. The template supports Handlebars syntax.

Use {{{answer}}} to render the answer as HTML without escaping the markup.

<ai12z-container
  render-type="content"
  data-key="YOUR_API_KEY"
  instance-id="12345"
  key-name="6ab321a25d3d3b8b3f439976"
>
  <!-- Knowledge-base article key name -->
</ai12z-container>

Custom content template

You can dynamically set the content-template attribute using JavaScript:

const kbInstance = document.querySelector(
  'ai12z-container[instance-id="12345"]'
)

const template = [
  '<div style="color: red; background: grey">',
  '  {{{answer}}}',
  '</div>',
].join('\n')

kbInstance.setAttribute("content-template", template)

The content-template value determines how the knowledge-base answer is rendered.

Template rendering

Use render-type="template" to render widget content using a custom template integration.

<ai12z-container
  render-type="template"
  data-key="YOUR_API_KEY"
  instance-id="12345"
  key-name="hbstform"
>
  <!-- Template integration key -->
</ai12z-container>

The key-name identifies the template integration to render.

Integration rendering

Use render-type="integration" to render an integration such as a mortgage calculator.

<ai12z-container
  render-type="integration"
  data-key="YOUR_API_KEY"
  instance-id="12345"
  key-name="Mortgageratecalculator"
>
  <!-- Integration key -->
</ai12z-container>

The key-name identifies the integration to render.

Carousel rendering

Use render-type="carousel" to render a carousel response, such as a food or restaurant carousel.

<ai12z-container
  render-type="carousel"
  data-key="YOUR_API_KEY"
  instance-id="12345"
  key-name="LocalRestaurants"
>
  <!-- Carousel integration key -->
</ai12z-container>

The key-name identifies the carousel configuration to render.

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

Scenario	`key-name` value	Example `parameters`
Local restaurant finder	`LocalRestaurants`	`{ "city": "Austin", "cuisine": "Italian"}`
Mortgage rate calculator	`Mortgageratecalculator`	`{ "termYears": "15", "amount": "300000" }`
Product recommender	`ProductRecommender`	`{ "category": "laptops" }`
Support ticket form	`SupportTicket`	`{ "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.

Agent Settings — Obtain your API key and configure agents
Knowledge Box Control — Embed AI answers inline with search results
Bot Control — Full conversational chat interface

Overview​

Setup​

Attributes​

Basic Usage​

Single Container​

Multiple Containers Side-by-Side​

Render Types​

Content rendering​

Custom content template​

Template rendering​

Integration rendering​

Carousel rendering​

Passing Parameters via JavaScript​

Configure Attributes via JavaScript​

Complete Example​

Use Cases​

Troubleshooting​

Container Does Not Render​

Parameters Not Applied​

Multiple Containers Interfering​

Related Documentation​