# Human-in-the-loop

*Human in the Loop* adds a mandatory human approval step to an automated workflow. Before an agent or orchestrator executes a sensitive action, a person can **approve**, **decline**, or **comment** on that action.

***

### Why Add a Human Step?

* **Security & Compliance** – stop unauthorized or risky actions.
* **Error Prevention** – catch mistakes that automated logic might miss.
* **Accountability** – every approved action has a human decision-maker.

***

### Where HITL Fits in Buildspace

| Layer             | Typical Use                                                 | How HITL Works                                                                                                                                   |
| ----------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Agents**        | Calling external APIs, sending emails, writing to databases | Enable approval on individual *tools* (nodes) inside the agent. Each time that tool is invoked, execution pauses and waits for a human decision. |
| **Orchestrators** | Coordinating multiple agents or long chains                 | Add approval to a *workflow step* so the entire branch pauses until it is reviewed.                                                              |

***

### Configuring HITL on an Agent Node

1. Open the agent in **Workflows → Editor**.
2. Select the node (e.g., *ReAct* agent, API call, DB write).
3. Select the tool which you would like the agent to use and ensure the tool is selected.
4. In the **Configuration** panel, check **Enable execution approval**.
5. (Optional) Edit the **Approval message**—this is what the reviewer will see.
6. Save and redeploy your workflow.

<figure><img src="https://4279757243-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTbBxR0Ob7RUmbvHZkQi2%2Fuploads%2F1dcjYQGcQGDTtrWCe07h%2Fimage.png?alt=media&#x26;token=3d4a4e63-0ae0-4b35-8dc5-e4a6058bebc5" alt=""><figcaption></figcaption></figure>

***

### Runtime Experience

To view the functionality of HITL:

* Go to the **chat** tab in the header navigation bar.
* Open the workflow where you enabled HITL and shubmit a prompt to your agent.&#x20;

<figure><img src="https://4279757243-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTbBxR0Ob7RUmbvHZkQi2%2Fuploads%2FzdxWpabtjSZ27K9KbSyM%2Fimage.png?alt=media&#x26;token=3bc43094-0d5e-42f3-8421-59edca9f05c4" alt=""><figcaption></figcaption></figure>

* When the agent reaches the guarded step, the chat displays:

  ```
  Node <name>: Approve or cancel execution. Send nothing for approval; provide feedback to cancel.
  ```
* The reviewer clicks **Approve** or **Reject**.

<figure><img src="https://4279757243-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTbBxR0Ob7RUmbvHZkQi2%2Fuploads%2FN995ACkE1Xl5QXkdFmdb%2Fimage%20(1).png?alt=media&#x26;token=3d67663b-1190-4f2d-8275-5cd8df22d87b" alt=""><figcaption></figcaption></figure>

* Execution continues (or stops) based on that choice.

***

### Common Use Cases

<table><thead><tr><th width="233.9921875">Scenario</th><th>Reason to Use HITL</th></tr></thead><tbody><tr><td>Querying internal databases</td><td>Prevent data leaks or large accidental extractions</td></tr><tr><td>Sending outbound emails</td><td>Double-check message content and recipients</td></tr><tr><td>Triggering payments</td><td>Verify amount, payee, and authorization</td></tr><tr><td>Posting public updates</td><td>Ensure brand voice and accuracy before publishing</td></tr></tbody></table>

***

### Best Practices

* **Limit scope**: Enable HITL only on actions that truly need it to avoid approval fatigue.
* **Keep messages clear**: The approval prompt should state *what* will run and *why* it needs review.
* **Audit everything**: Store timestamps, approver IDs, and decisions for compliance.

***

### Benefits Recap

* Security guardrail for critical operations.
* Human oversight without fully blocking automation benefits.
* Immediate feedback loop to improve future agent behavior.

***