Human Approval (HUMAN_APPROVAL)

Pauses the run and asks the user in the agent chat to approve before the next step runs — for example before an e-mail is sent. Add a Validator after it to go different ways on yes and no.

Category: Human Interaction · Deployed: yes · Tool-capable: no, deliberately

Ports

Port Kind Purpose

Input (in_input)

Input

What the user is asked to approve — the result of the previous module

Output (out_output)

Output

The user’s decision as a short JSON result (see below)

There is no Tool port.

Properties

Field Required Meaning

Prompt (promptTemplate)

No

The question the user sees. {{input}} is replaced with the previous module’s result, so the user sees what they approve. Empty → the question "Do you approve this action?"

Allow Free-Text Response (allowFreeTextResponse)

No

On (default, the box starts checked): the user can also write an answer in their own words, not only Yes or No. Off: only Yes or No

Placeholders in Prompt. {{input}} is always the whole previous result. When that result is a JSON object, {{fieldName}} is replaced with one of its fields, for example {{subject}}. A placeholder that matches no field is also replaced with the whole result — check the spelling.

In the chat

When the run reaches this module, the agent chat shows the question with the buttons Yes and No. With Allow Free-Text Response, there is also a text field ("Or type your own judgment…") and Submit.

  • The run really waits. Nothing after this module runs until the user answers.

  • The question survives leaving the chat. Open the chat again, or reload the page, and the question is still there with the note "This question is still waiting for your answer".

  • A new message while a question is open opens the dialog "Still waiting for an answer". Keep Answering It goes back to the question. Discard & Send New Message ends the paused run and sends the new message.

  • The stop button (×) next to the input (or Esc) ends the paused run.

  • The waiting time is limited. The agent server waits 30 minutes by default. Without an answer in that time, the run ends with an error.

Result

The Output passes on a JSON object:

Field Meaning

approved

true for Yes, false for No

userComment

Only when the user typed an answer: the text they wrote

originalInput

The previous module’s result, so the next steps can still use it

A typed answer counts as not approved. It gives approved: false together with the text in userComment. Only Yes gives approved: true.

Use cases

  • Approve a real action: Agent writes an e-mail → Human Approval → Validator (checks approved) → Pass → API Call sends it.

  • Approve a step that changes data, for example before File Write overwrites a file.

  • Spot checks while you build trust in a new pipeline.

Notes

  • It does not branch. Unlike Validator and Guardrails, it has no Pass and Fail outputs. Put a Validator after it that checks the field approved.

  • It cannot be a tool. An agent cannot pause in the middle of its own work and wait for a person. To ask only in some cases, put an Agent and a Validator in front of the approval, so the run reaches it only when it matters.

  • An agent does not need this module to ask a question. Its answer can be the question, and the user’s next message is the reply. Use this module only to hold back a real step that comes after it.

  • Only someone in the chat can answer. In a run started by a Scheduler, nobody sees the question. The run waits until the time limit and then ends with an error.

  • A restart of the agent ends every paused run.