> Source: https://builder.ema.ai/v2/builder-guides/designing-hitl-forms
> Title: Designing Human-in-the-Loop Forms

# Designing Human-in-the-Loop Forms

Human-in-the-loop (HITL) pauses an agent mid-run so a person can answer a question, fill in a form, or approve a step. The agent collects what it needs, the run resumes with that input, and the agent continues. This guide covers the three HITL modes — conversation, inline form, and external form — and how to design each one.

HITL is configured per agent, under **Advanced settings**, on the LLM-driven agent types (intent classification, search and respond, extraction, rule validation, respond, document agent, and custom).

## How HITL works

When HITL is enabled, the agent gets an `ask_human` capability. As it reasons through a run, the agent decides when it needs human input and pauses. The platform records the pause as a first-class request, notifies the assigned person, and waits. When the person responds, the agent resumes with their answer folded into its context — and it can pause again if it needs more. Multiple rounds per step are supported.

Because HITL is driven by the agent rather than a fixed step in the graph, you control _what_ to collect and _when_ through the HITL configuration and your [Instructions](/builder/v2/builder-guides/writing-instructions), not by adding a node.

## Enabling HITL

1.  Open the agent in the AI Employee builder and expand **Advanced settings**.
2.  Turn on the **Human in the loop** toggle.
3.  Choose a **Mode**. The modes available depend on the AI Employee's interaction type:
    -   **Chat** (and most builds): **Conversation**, **Form**, or **External form**.
    -   **Dashboard**: **Form** or **External form** (no free-form conversation).
    -   **Voice**: **Conversation** only (a phone caller can't fill a visual form).

## Mode 1 — Conversation

The simplest mode. The agent asks the person a question in natural language and waits for a free-text reply.

1.  Set the mode to **Conversation**.
2.  In **HITL Instructions**, tell the agent what information to collect and when it has enough to proceed — for example, "Ask the user for their order number and a description of the issue before continuing. If they don't have an order number, ask for the email used at checkout."

The agent can present the question as free text, and may offer a short list of choice buttons when the answer space is small and mutually exclusive. The person can always type a free-text answer even when buttons are shown.

Use conversation mode when the input is open-ended or conversational, or when you're building for voice.

## Mode 2 — Inline form

A structured form rendered in the chat or dashboard UI. Use this when you need several named fields at once.

1.  Set the mode to **Form**.
2.  Choose **Add Form** to open the form editor.
3.  Give the form a **Title** (required) and an optional **Description** and **Submit label**.
4.  Add fields with **Add field**. For each field set:
    -   **Name** — the key returned to the agent. Names must be unique within the form.
    -   **Type** — see the field types below.
    -   **Label** and **Placeholder** — what the person sees.
    -   **Required** — whether the field must be filled.
    -   For option-based types, the **Options** (each a value plus a label).
    -   For number fields, an optional **Min** and **Max**.
5.  Save the form.

You can attach more than one inline form to an agent; the agent picks the right form for the situation based on its Instructions.

### Inline field types

Type

Renders as

Notes

`text`

Single-line text input

—

`email`

Email input

—

`tel`

Phone input

—

`number`

Number input

Supports Min / Max.

`date`

Date picker

—

`textarea`

Multi-line text area

—

`select`

Dropdown

Requires options.

`radio`

Radio group

Requires options.

`checkbox`

Checkbox

—

`card_select`

Selectable cards

Requires options.

`slot_select`

Time-slot picker

Requires options.

When the person submits, each field's value is returned to the agent keyed by its **Name**, and the run resumes.

## Mode 3 — External form

Embeds a form hosted at a URL (in an iframe) instead of rendering native fields. Use this when the form already exists in another system, or needs logic the inline builder can't express.

1.  Set the mode to **External form**.
2.  Choose **Add External Form** and configure:
    -   **Display name** (required) and optional **Description**.
    -   **URL** — where the form is hosted.
    -   **Button label** / **Cancel label** and optional **Max width** / **Max height** for the embedded frame.
    -   **Data schema (JSON)** — an optional JSON Schema describing the small metadata the agent should pass when it opens the form (for example, `flowType`, `patientId`). The platform fetches large data separately, so keep this to identifiers and flags.
    -   **Data sources** — integration functions the platform calls when the form opens, whose results are injected into the form. Each source has a function id, an output key, and an input mapping (map form-data keys to function parameters; prefix a value with `=` to pass a literal).
    -   **Post-submit function** — optionally name an integration function to run deterministically when the form is submitted, instead of letting the agent decide what to do with the submission. The named function must be one of the agent's selected Tools. Leave it blank to keep the agent-driven path.

> [TIP]
> Use the **post-submit function** when submitting the form should always do one fixed thing (for example, "submit timesheet"). It removes the model from the decision and guarantees the action runs.

## Assigning the request

Each HITL pause is assigned to a person to respond. The assignee resolves at run time — typically to the user who triggered the run, or to a specific user you configure. Publishing is blocked if a HITL configuration references an invalid assignee, so the request always lands on a real person.

## Designing reliable HITL

-   **Keep questions specific.** "What is the order number?" beats "Can you give me more details?"
-   **Tell the agent when to stop.** In conversation mode, state the stopping condition explicitly so the agent doesn't loop ("Once you have the order number and the issue description, proceed").
-   **Prefer forms for structured data.** If you need three named fields, a form collects them in one round instead of three back-and-forth turns.
-   **Mark only truly required fields.** Required fields block submission; optional fields let the person move on.
-   **Match the channel.** Forms render in chat and dashboards; voice callers get conversation mode. Don't design a form for a phone-only AI Employee.

## What happens on resume

When the person responds, the agent receives their input and continues from where it paused — re-resolving any templated values and incorporating the answer. The run's step trace records the pause and the response, so you can see exactly what was asked and answered in the run history.

## What's next

-   [Writing effective Instructions](/builder/v2/builder-guides/writing-instructions) — HITL Instructions follow the same principles.
-   [Build your first workflow](/builder/v2/builder-guides/build-your-first-workflow) — add a HITL-enabled agent to a workflow.
-   [Core concepts](/builder/v2/core-concepts) — how human-in-the-loop fits into run execution.