Human-in-the-Loop (HITL)

CloudPeek's AI agents are capable, but you decide how much they're allowed to do on their own. Human-in-the-Loop (HITL) is the system of approval gates that keeps a person in control of anything that matters. This page explains the controls and where to find them.

The idea

AI agents work by calling tools, querying Splunk, listing AWS findings, looking up an IP on VirusTotal, and so on. Some tool calls only read data; others could change a system. HITL lets you draw the line: which of those the agent may do automatically, and which require a human to click Approve first.

You set this per investigation, so a routine lookup can run wide open while a sensitive case runs locked down.

Approval modes

In an investigation's chat input there's an approval control. It offers four modes, from most to least autonomous:

The control is labelled with the current mode (e.g. "Approve All External"). The same options appear in the chat settings (gear) menu under the heading Approval & autonomy, where they're described as:

• No Approvals: "All tool calls run automatically."
• Approve External Writes: "Read-only external calls run automatically."
• Approve All External: "Every external tool call needs approval."
• Approve All: "Every tool call requires approval."

Plan mode

Beyond per-action approvals, Plan mode adds a higher-level gate. With it on, the agent first writes a structured plan of what it intends to do and waits. You review the plan and choose:

• Approve & run: execute the plan.
• Edit plan: adjust it first.
• Reject plan: stop.

Plan mode is ideal for sensitive or high-impact work where you want to see the whole approach before any step runs. Toggle it from the chat settings menu (Plan mode), alongside the HITL approvals toggle and a Show reasoning option that reveals the agent's thinking.

Approving and rejecting in the moment

When the agent reaches a gated step, that step appears in the conversation with Approve and Reject buttons. After you decide:

• Approve → the step shows an Approved badge and runs ("Running {tool}…"), then the agent continues.
• Reject → the step shows a Rejected badge and the agent moves on without it.

The number of items waiting for a decision is surfaced on the Dashboard as the HITL backlog KPI, and clearing it is one of the onboarding checklist steps.

Admin settings that govern HITL

Two timeouts control how long the agent waits for a human before giving up. They're set per tenant in Settings → Runtime Configuration (/admin/settings/runtime-config), under Agent runtime:

• Plan approval timeout: how long to wait for a human to approve a plan (default 10 minutes).
• Tool approval timeout: how long to wait for a human to approve a single tool call (default 5 minutes).

If the timeout passes with no decision, the agent stops waiting on that item.

HITL and automatic (background) work

It's important to understand the distinction between interactive investigations and autonomous background work:

• Interactive investigations (you, in the chat) use the full HITL system above: you grant autonomy and approve actions as they come up.
• Autonomous background work: the follow-up actions that workers run automatically after triage, is restricted to read-only tools by design. The automation gathers facts and reports; it does not take actions that change your systems. In other words, the background path has a hard safety limit rather than an approval prompt: write actions simply aren't available to it.

Good practice

• Start new or sensitive investigations in Approve All External (or stricter) and loosen only once you trust the pattern.
• Use Plan mode when the work is high-impact and you want to vet the approach up front.
• Keep an eye on the HITL backlog on the dashboard so approvals don't pile up and stall agents.

Related

• Investigations: where you use these controls.
• Follow-up Actions: the read-only autonomous path.
• Admin & Settings: the runtime timeouts.