Learning Tactus

Human-in-the-Loop

Human-in-the-loop (HITL) is where agent workflows stop being “cool demos” and start being trustworthy systems. This chapter introduces approvals and reviews as language primitives.

Now that you’ve seen how to structure an agent loop, HITL becomes a practical pattern: gate the risky step, collect missing inputs, and resume the workflow exactly where it left off.

The HITL Primitives

Tactus includes three blocking primitives you’ll use constantly:

Each is a durable suspend point. When execution reaches one of these calls, the runtime:

  1. Checkpoints everything up to that point
  2. Emits a pending request to the human UI/handler
  3. Suspends execution
  4. Resumes later (even in a new process) when the human responds

That’s the difference between “agent scripts” and real workflows: you don’t keep a Python process running for 14 hours waiting for someone to click “Approve.”

Timeouts and “Fail Safe”

All blocking HITL calls can be configured with timeouts and defaults:

For risky actions, the safe default is almost always “don’t proceed.”

Example: Review the Draft, Then Approve Sending

The example for this chapter is code/chapter-10/50-meeting-recap-hitl-send.tac.

It follows a workflow shape you can reuse almost anywhere:

  1. Generate a structured draft (subject, body, action_items)
  2. Human.review(...) the draft (human can approve, reject, or revise)
  3. If revised, incorporate edits (or re-run the agent with feedback)
  4. Human.approve(...) before calling the send tool
  5. Call send_email(...) (stubbed here) and return message_id

Run it:

tactus run code/chapter-10/50-meeting-recap-hitl-send.tac \
  --param recipient_name="Sam" \
  --param recipient_email="sam@example.com" \
  --param raw_notes="Discussed Q1 launch timeline. Risks: vendor delays. Action: Sam to confirm dates by Friday."

In mock mode, HITL is automatically answered so tests can run without blocking:

tactus test code/chapter-10/50-meeting-recap-hitl-send.tac --mock

How HITL Shows Up in Different Environments

The same Lua code can run with different HITL handlers:

The procedure doesn’t change. That portability is the point.

This is also how you move beyond the “everyone uses chat” paradigm. Instead of forcing end users to steer the agent turn-by-turn, your application can surface structured, minimal interactions:

In other words: the human is still in the loop, but they’re an approver/reviewer/operator—not a full-time copilot.

Where This Takes Us

At this point in Part II, our workflow is:

Next, Part III steps back and names the levers of control you have in an agent system—beyond prompts—then turns those into enforceable guardrails: capability control, sandboxing, isolation boundaries, and secretless execution. After that, Part IV covers reliability: specs and evaluations so you can trust the workflow over time.