> For the complete documentation index, see [llms.txt](https://docs.visdom.virtuslab.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.visdom.virtuslab.com/visdom-orchestrator/user-guide/humans-in-the-loop.md).

# Humans in the loop

There are four distinct ways a person meets a running flow, and they are genuinely different mechanisms rather than four skins on the same thing. Confusing them is the usual cause of "why did nobody notice this run was waiting".

## 1. Approvals: the flow stops

An `approval` node is part of the graph. It names an approver **role**, a title, the context to show the approver, a TTL, and what to do when that TTL runs out. The engine consults the active version of the workspace's approval policy when the node dispatches, so policy changes apply to future dispatches rather than rewriting decisions already made.

An expiry is a real outcome, not an error state: the node takes the configured expiry branch. Cancelling a run cascades to the approvals it raised, so a cancelled run does not leave a stale request sitting in somebody's queue.

## 2. Questions: the agent asks mid-turn

An agent can raise an `ask_user` question **during** its own turn, without the flow having planned for it. The question carries its own visibility and TTL; answering is race-safe, so two people clicking at once cannot both win, and unanswered questions are swept when they expire.

This is the path for "I need one decision to continue", as opposed to an approval, which is the path for "somebody must sign off before this proceeds".

## 3. Comments: people talk about the run

Run comments support threads two levels deep, edit history, and reactions, with per-action authorisation. They do not affect execution. Their value is that the discussion about a run lives next to the run's evidence instead of in a chat thread nobody can find in three months.

## 4. Chat: a conversation as a first-class object

Chat sessions persist, carry their own message history, time out when idle, and can be forced to produce an output. A run can sit in an `AwaitingChat` status while that happens.

This is the least finished of the four. The chat agent runtime image, the in-flow chat node and the output MCP are not shipped: the persistence and the API are there, the pod that would hold the conversation is not.

## Notifications sit underneath all of it

Rather than each feature sending its own message, the platform records a **notification intent** (an approval is waiting, a flow run failed) and a delivery layer takes it outward. Intents can be listed, cancelled and retried, and delivery attempts are recorded separately from the intent, which is what makes "was this actually sent" answerable.

{% hint style="danger" %}
**No first-party channel adapter ships yet.** Slack, SMTP, GitHub, GitLab and Jira are all unbuilt. The generic outbound webhook works, so notifications can leave the system, but a message arriving in a chat tool is a webhook plus an integration somebody wrote, not a feature of the platform.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.visdom.virtuslab.com/visdom-orchestrator/user-guide/humans-in-the-loop.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.