Form tools

Overview

Form tools let you turn any HTML form on your page into a tool the AI agent can use — without writing a single line of JavaScript. Just add a few zephlo-* attributes to your existing form markup and the agent can fill in fields, select options, and optionally submit the form on behalf of the visitor. This is perfect for lead capture forms, contact forms, search filters, booking forms, and any other form-based interaction.

Quick start

Add zephlo-tool-name to any <form> element:

<form
  zephlo-tool-name="submit_contact"
  zephlo-tool-description="Submit a contact inquiry from the visitor"
>
  <input name="name" type="text" required
    zephlo-param-description="The visitor's full name" />

  <input name="email" type="email" required
    zephlo-param-description="The visitor's email address" />

  <textarea name="message"
    zephlo-param-description="The message or question"></textarea>

  <button type="submit">Send</button>
</form>

The widget automatically detects this form and registers it as a tool. When the agent decides to use it, it fills in the fields and lets the visitor review before submitting.

Form attributes

On the `<form>` element

Attribute	Required	Description
`zephlo-tool-name`	Yes	Unique name for the tool (use `snake_case`)
`zephlo-tool-description`	No	Plain-English description the agent reads to decide when to use this form
`zephlo-auto-submit`	No	If present, the agent submits the form automatically after filling it

On `<input>`, `<select>`, and `<textarea>` elements

Attribute	Required	Description
`zephlo-param-description`	No	Description of what this field is for. Helps the agent fill it correctly

Always add zephlo-param-description to your fields. Without it, the agent only sees the field’s name attribute, which may not be descriptive enough.

Fill-only vs auto-submit

By default, the agent fills in the form fields but does not submit. The visitor sees the filled form and can review or modify the values before clicking submit themselves. To let the agent submit automatically, add zephlo-auto-submit:

<!-- Fill only (default) -- visitor reviews and submits -->
<form zephlo-tool-name="search_flights"
      zephlo-tool-description="Search for available flights">
  ...
</form>

<!-- Auto-submit -- agent fills and submits -->
<form zephlo-tool-name="subscribe_newsletter"
      zephlo-tool-description="Subscribe the visitor to the newsletter"
      zephlo-auto-submit>
  ...
</form>

Handling auto-submit events

When auto-submit is enabled, the form dispatches a standard submit event with an extra agentInvoked flag. Use respondWith to return a result to the agent:

const form = document.querySelector("form[zephlo-tool-name='subscribe_newsletter']");

form.addEventListener("submit", (e) => {
  if (e.agentInvoked) {
    // The agent triggered this submission
    e.respondWith(
      fetch("/api/subscribe", {
        method: "POST",
        body: new FormData(e.target),
      })
        .then((res) => res.json())
        .then((data) => `Subscribed ${data.email} successfully`)
    );
  }
  // Otherwise, normal user-initiated submit
});

If you don’t call e.respondWith(), the agent receives a default “Form submitted successfully” confirmation.

Returning a result without JavaScript

If your form posts on its own and you just want to hand a specific message back to the agent, set a zephlo-result attribute on the form. The widget reads it after submission and clears it:

<form
  zephlo-tool-name="subscribe_newsletter"
  zephlo-tool-description="Subscribe the visitor to the newsletter"
  zephlo-auto-submit
  zephlo-result="The visitor has been subscribed to the newsletter."
>
  ...
</form>

Auto-mapped constraints

The widget automatically converts your HTML validation attributes into JSON Schema constraints that the agent understands:

HTML attribute	JSON Schema equivalent	Example
`required`	Added to `required` array	`<input required>`
`min` / `max`	`minimum` / `maximum`	`<input type="number" min="1" max="100">`
`minlength` / `maxlength`	`minLength` / `maxLength`	`<input minlength="3" maxlength="50">`
`pattern`	`pattern` (regex)	`<input pattern="[A-Z]{3}">`
`<select>` options	`enum` values	`<option value="us">US</option>`
Radio group	`enum` with collected values	`<input type="radio" value="yes">`

This means your existing validation logic doubles as instructions for the agent.

Supported input types

HTML input type	JSON Schema type	Notes
`text`, `email`, `url`, `tel`, `search`	`string`	Standard text fields
`date`, `time`, `datetime-local`	`string`	Date/time as strings
`number`, `range`	`number`	Numeric values
`checkbox`	`boolean`	True/false toggle
`radio`	`string`	With `enum` from group values
`<select>`	`string`	With `enum` from options
`<textarea>`	`string`	Long text
`file`, `submit`, `button`, `reset`, `image`	—	Skipped automatically

Only fields with a name attribute become tool parameters. A file input is always skipped — the agent can’t set files programmatically — so keep file uploads for the visitor to fill in themselves.

Examples

Lead capture form

<form
  zephlo-tool-name="capture_lead"
  zephlo-tool-description="Capture the visitor's contact information for a sales follow-up"
  zephlo-auto-submit
>
  <label>
    Name
    <input name="name" type="text" required
      zephlo-param-description="Full name of the visitor" />
  </label>

  <label>
    Email
    <input name="email" type="email" required
      zephlo-param-description="Work email address" />
  </label>

  <label>
    Company
    <input name="company" type="text"
      zephlo-param-description="Company or organization name" />
  </label>

  <label>
    Team size
    <select name="team_size" zephlo-param-description="Number of people on their team">
      <option value="1-10">1-10</option>
      <option value="11-50">11-50</option>
      <option value="51-200">51-200</option>
      <option value="200+">200+</option>
    </select>
  </label>

  <button type="submit">Get in touch</button>
</form>

Booking form

<form
  zephlo-tool-name="book_appointment"
  zephlo-tool-description="Book an appointment for the visitor"
>
  <input name="date" type="date" required
    zephlo-param-description="Preferred appointment date" />

  <input name="time" type="time" required
    zephlo-param-description="Preferred time of day" />

  <select name="service" required
    zephlo-param-description="Type of service requested">
    <option value="consultation">Consultation</option>
    <option value="demo">Product demo</option>
    <option value="support">Technical support</option>
  </select>

  <textarea name="notes"
    zephlo-param-description="Any additional notes or requests"></textarea>

  <button type="submit">Book</button>
</form>

<form
  zephlo-tool-name="filter_products"
  zephlo-tool-description="Filter the product list based on visitor preferences"
  zephlo-auto-submit
>
  <input name="query" type="search"
    zephlo-param-description="Search keywords" />

  <select name="category"
    zephlo-param-description="Product category">
    <option value="">All categories</option>
    <option value="shoes">Shoes</option>
    <option value="shirts">Shirts</option>
    <option value="accessories">Accessories</option>
  </select>

  <input name="min_price" type="number" min="0"
    zephlo-param-description="Minimum price in USD" />

  <input name="max_price" type="number" min="0"
    zephlo-param-description="Maximum price in USD" />

  <label>
    <input name="in_stock" type="checkbox"
      zephlo-param-description="Only show items currently in stock" />
    In stock only
  </label>

  <button type="submit">Apply filters</button>
</form>

Dynamic forms

The widget uses a MutationObserver to automatically detect forms added to the page after initial load. If you dynamically insert a form with zephlo-tool-name, it’s picked up automatically. If you ever need to force an immediate re-scan — for example, right after rendering a form in a framework that updates the DOM asynchronously — call:

zephlo.scanForms();

Auto-detection watches the main document. Forms rendered inside another component’s Shadow DOM are isolated and won’t be seen, so keep your zephlo-tool-name form markup in the regular (light) DOM.

Next steps

Register tools

Widget integration

Learn about embedding and customization options.

Getting started

Widget

Overview

Quick start

Form attributes

On the `<form>` element

On `<input>`, `<select>`, and `<textarea>` elements

Fill-only vs auto-submit

Handling auto-submit events

Returning a result without JavaScript

Auto-mapped constraints

Supported input types

Examples

Lead capture form

Booking form

Search / filter form

Dynamic forms

Next steps

Register tools

Widget integration

​Overview

​Quick start

​Form attributes

​On the <form> element

​On <input>, <select>, and <textarea> elements

​Fill-only vs auto-submit

​Handling auto-submit events

​Returning a result without JavaScript

​Auto-mapped constraints

​Supported input types

​Examples

​Lead capture form

​Booking form

​Search / filter form

​Dynamic forms

​Next steps

Register tools

Widget integration

Overview

Quick start

Form attributes

On the `<form>` element

On `<input>`, `<select>`, and `<textarea>` elements

Fill-only vs auto-submit

Handling auto-submit events

Returning a result without JavaScript

Auto-mapped constraints

Supported input types

Examples

Lead capture form

Booking form

Search / filter form

Dynamic forms

Next steps