Human-in-the-loop: how to design approval gates into a multi-agent workflow

Quick answer

A human-in-the-loop gate is a schema-declared checkpoint in your multi-agent pipeline where a person must approve or reject before the next step runs. Gates are a design decision — they belong in the spec before any code is written, not bolted on after something goes wrong. The key choices: where to place the gate, what type of decision the human is making, what approve and reject each do, and what happens if no one acts within a set time.

Why HITL is a design decision, not a configuration afterthought

When builders first encounter human-in-the-loop requirements, the instinct is to treat it as a filter — something you add after the AI does its work to catch mistakes before they cause harm. This is the wrong frame, and it produces systems that behave badly under real conditions. For a broader look at why autonomy and oversight are not opposites, human-in-the-loop and the autonomous agent problem covers the underlying tension.

A gate designed in from the start changes how the surrounding agents are built. The agent whose output feeds a gate knows its job is to produce reviewable output — structured, legible, suitable for a human to evaluate quickly. The agent that receives approved records knows it is working with human-validated input and can act with appropriate confidence. The gate is not just a pause in the pipeline. It's a specification of what the human-machine handoff looks like at that moment.

Adding a gate after the fact — when something has already gone wrong, or when a compliance requirement surfaces late — means retrofitting that specification into agents that were never designed for it. The output format doesn't match what a review interface needs to surface. The rejection path doesn't exist in the downstream agent's prompt. The timeout behaviour was never thought through. The gate works, technically, but the experience is fragile and the audit trail is weak.

Design the gates in. It's not extra work — it replaces rework.

Where do approval gates belong in a workflow?

Not every step in a multi-agent pipeline warrants a human checkpoint. Adding gates indiscriminately creates operational overhead without proportionate value. The goal is placing gates where human judgment genuinely changes the outcome — and only there. Finance workflows are a good reference point for this: high-stakes, auditable, with clear consequences for errors. AI agents for finance teams shows where gates are non-negotiable and where they create unnecessary friction.

Four types of steps are strong gate candidates:

Before irreversible external actions. If an agent is about to send an email, submit a form, post content publicly, initiate a financial transaction, or modify a production database record — that action is difficult or impossible to undo. A gate before these steps gives a human the chance to catch a mistake before it costs something. The cost of the gate is latency. The cost of skipping it is whatever the mistake costs.

Before content that represents your organisation. Outbound emails, published posts, customer-facing messages, and documents sent to third parties carry reputational risk. Even when the AI produces good output most of the time, the cases where it doesn't are visible in a way that internal mistakes are not.

At decision points with downstream consequence. Some pipeline steps choose between meaningfully different paths — approve this candidate, escalate this ticket, accept this contract term. When the AI makes that call, it does so on pattern matching. When a human makes it, they bring judgment about context the AI doesn't have access to.

At regulatory or compliance checkpoints. In financial services, healthcare, legal, and other regulated industries, there are often statutory requirements for a human to review before certain actions are taken. These gates are not optional and their audit trail requirements are specific. Design them first — they are the most expensive to retrofit.

Steps that do not need a gate: pure data retrieval, classification and scoring that feeds further processing before any action, and intermediate pipeline steps where a human checkpoint comes later anyway. Gating every step produces a workflow that requires constant attention and runs slower than a human doing the job manually.

Should this step have a gate?

Three questions for each step in your pipeline:

1. Is the action reversible? If no — strong gate candidate.
2. Does the output leave the system? If yes (email sent, post published, external record modified) — strong gate candidate.
3. Does a wrong decision here cascade? If the output of this step is the input to multiple downstream steps, a mistake propagates. Gate the step where the error originates.

If none of these apply, the step probably doesn't need a gate.

What happens at a gate

A gate has four design decisions. Each one needs to be specified before you build.

Gate type

The gate type describes what kind of decision the human is making. It determines what to surface in the review interface and what a valid response looks like.

The type matters because it shapes the review interface and the mental model the reviewer brings to the task. A content reviewer needs to read and judge quality. A decision reviewer needs to see the criteria and make a yes/no call. Conflating types produces review interfaces that are confusing and reviews that take longer than they should.

Trigger condition

The trigger condition determines when the gate releases and the next pipeline step runs.

Most content and lead review workflows use any_approved or all_resolved. Regulated workflows often need all_resolved for audit completeness.

Rejection behaviour

What happens when a human rejects a record is a design decision with real consequences for how the rest of the pipeline behaves.

For most workflows, skip is the right default — it's the least disruptive and keeps the pipeline moving. rerun is useful for content workflows where the reviewer can give feedback and have the AI revise. halt is appropriate when the rejected item is load-bearing — if one contract clause fails review, the whole contract stops.

Timeout behaviour

What happens if no one acts within the configured time period.

Timeout is not optional to design. A gate with no timeout configuration can hang a production pipeline indefinitely if a reviewer is on leave, a notification fails to deliver, or the review interface has an issue. Configure a timeout with a sensible default — 24 or 72 hours is common — and a behaviour that matches the risk profile of the workflow.

Worked example: content approval workflow

A marketing team wants an AI workflow that drafts blog posts for approval before publishing. Here is what the gate design looks like before any code is written.

The pipeline:

1. brief-intake — receives a topic brief and produces a structured content outline
2. content-writer — drafts the post from the outline
3. gate: content-review
4. publisher — publishes the approved post

Gate specification:

{
  "name": "content-review",
  "type": "content_generation",
  "afterStep": "content-writer",
  "triggersStep": "publisher",
  "fields": ["title", "body", "targetKeyword", "wordCount"],
  "trigger": "any_approved",
  "onReject": "rerun",
  "recordActions": [
    { "label": "Approve", "verb": "approve", "style": "primary" },
    { "label": "Revise", "verb": "reject", "style": "secondary" },
    { "label": "Discard", "verb": "skip", "style": "danger" }
  ],
  "timeout": {
    "after": "48h",
    "behaviour": "halt"
  }
}

What each choice specifies:

• type: content_generation — the reviewer reads and evaluates quality, not just yes/no
• trigger: any_approved — publishing can start as soon as one post is approved; the reviewer doesn't need to process the whole batch first
• onReject: rerun — when a reviewer clicks Revise, the rejection reason feeds back to content-writer for a revision pass
• Three record actions — Approve to publish, Revise to send back to the AI with feedback, Discard to remove it entirely
• Timeout 48h / halt — if no one reviews within 48 hours, the pipeline stops and the operator is notified, rather than publishing unreviewed content automatically

A compliance variant: In a regulated document workflow — contract review, financial disclosure, medical intake — the same structure applies with type: "action", trigger: "all_resolved", onReject: "halt", and a shorter timeout. Every record must be resolved before any action proceeds, a single rejection stops the pipeline, and the review window is tight.

What agents on either side of a gate need to know

A gate changes the prompts on both sides, not just the pipeline step between them. This is the part most builders miss when they add gates as an afterthought.

The agent before the gate should know it is producing output for human review, not for another agent. Its job is clarity and structure. It should produce output that a reviewer can evaluate in under a minute. If the gate type is content_generation, the agent should produce well-formed text with the key fields surfaced prominently. If the type is decision, the agent should produce a record with the fields the human needs to make a yes/no call — not buried in a block of reasoning.

The agent after the gate should know it is processing human-validated input. An agent that sends emails after a content gate should not second-guess the approved text — it should send it. An agent that processes approved leads should treat them as confirmed targets, not candidates.

This context belongs in both agents' role definitions — not as a comment, but as an explicit part of what each agent knows about its position in the pipeline. For how role definitions and pipeline position fit together, see the anatomy of a multi-agent system.

Where Envelope fits

Envelope lets you design gates into your workflow from the start — before any code is written. When you describe your workflow in Envelope, you specify which steps require human approval, what type of decision the reviewer is making, and what approve and reject each do. Envelope structures that into a complete multi-agent design and exports it as a .envelope.json file with gate configuration defined.

The design step is where these decisions get made. Getting them right on paper is the work. Envelope is the tool that captures and structures it.

If you're thinking about how gates interact with your pipeline's ordering — which steps can run in parallel before a gate, which must wait — parallel vs. sequential agents covers that decision.

Design your AI agents in Envelope

Envelope turns a plain-language description of your workflow into a complete AI agent system — agents with named roles, model assignments, tool access, handoffs, and human review gates. Free to start, no code required.

Start designing →

Frequently asked questions

What is a human-in-the-loop gate in a multi-agent workflow?

A human-in-the-loop gate is a schema-declared checkpoint between pipeline steps where a person must review and act — approve, reject, or skip — before the next step runs. It's not a notification or a log entry. It's a pause in the pipeline that waits for a real decision before continuing.

Why should gates be designed before the workflow is built?

Because a gate changes how the surrounding agents are built. The agent before the gate must produce reviewable, human-legible output. The agent after it must handle the fact that its input was human-validated. Adding a gate after the fact means retrofitting those requirements into agents that were never designed for them — which usually produces fragile integrations and incomplete audit trails.

Which steps in a workflow need a human gate?

Steps where the action is irreversible, where the output leaves the system (emails, posts, external database writes), or where a wrong decision cascades downstream are strong gate candidates. Pure data retrieval and intermediate steps that feed further processing before any external action generally do not need gates.

What is onReject and why does it matter?

onReject specifies what the pipeline does when a human rejects a record at a gate. skip excludes it and moves on. rerun sends the rejection reason back to the previous agent for a revision pass. escalate routes it to the coordinator for a judgment call. halt stops the entire pipeline. The choice matters: a content workflow where rejected drafts can be revised needs rerun; a compliance workflow where one rejection invalidates the whole run needs halt.

What happens if no one reviews in time?

The timeout configuration specifies what to do. halt stops the pipeline and notifies the operator — the right choice for regulated workflows and anything where unreviewed content proceeding automatically is unacceptable. proceed releases the gate and continues — appropriate only when the cost of delay exceeds the risk of an unreviewed item moving forward. escalate routes to the coordinator to find an alternative reviewer. Always configure a timeout — a gate with no timeout can hang a production pipeline indefinitely.

How do approval gates affect the agents on either side?

Significantly. The agent before the gate should produce output designed for human review — structured, legible, with the key fields a reviewer needs to make a decision surfaced prominently. The agent after the gate should treat its input as human-validated and act accordingly. Both role definitions should include this context explicitly, not as a comment but as part of what the agent knows about its position in the pipeline.

Do I need a different gate type for content review vs. lead approval?

Yes. content_generation gates are for reviewing AI-produced text — the reviewer reads, evaluates quality, and optionally edits. decision gates are for yes/no on candidate records — the reviewer sees the key fields and makes a call. Using the wrong type produces a review interface that doesn't match what the reviewer needs, which slows review and reduces decision quality.

How is this different from just splitting the workflow into two separate runs?

Splitting into two runs is a valid pattern for many use cases — and often the right choice. The gate approach is preferable when a human's decision needs to happen mid-workflow with the run's state preserved, or when you need a consolidated review interface across many records rather than separate triggers for each. For a deeper look at the two approaches and when each applies, see human in the loop and the autonomous agent problem.