Actor + HITL — automated vs human-review actors

Actors are calls that change external state (Lesson 1). Because they're irreversible, the division of when and who fires an actor is the core safety pattern of agent design. This lesson separates actors into automated vs human-review and designs a HITL (Human-in-the-Loop) workflow.

Two kinds of actor

Automated actor

Takes the LLM's reasoning output and fires immediately. No human in the middle.

• log_event(...) — One audit log line. The side effect is confined to internal organizational logs, so it's safe as an automated actor.
• send_internal_slack(...) — Internal Slack notification. If misfired, the impact stays internal.
• update_metric(...) — Increment an operational metric counter.

The shared property of automated actors — malfunction impact stays within the organization and is recoverable.

Human-review actor

The LLM produces a recommendation, a person accepts or overrides it, and only then does the external call fire. The reviewer's decision is the actor's input.

• capture_review_decision(reviewer_id, decision) — The reviewer picks one of APPROVE / PARTIAL / REJECT. The output of this actor is the input to the next.
• Downstream — actors like issue_refund(amount) or send_rejection_email(reason) are the irreversible external calls.

The shared property — malfunction impact extends to organizationally external parties (customers · financial systems · regulators) or carries legal/contractual liability.

One HITL cycle

The refund-approval agent (§6 of the refund_approval workshop) flow:

1. User input — Reviewer enters the order ID under review.
2. Two tool calls — get_enriched_order(order_id) for context, search_refund_policy(reason) for the relevant policy paragraph via RAG (next lesson).
3. LLM reasoning — Combine the two outputs to produce a recommendation (APPROVE / PARTIAL / REJECT) + three justification lines.
4. Human-review actor — capture_review_decision. The reviewer clicks one of three buttons in the UI.
5. Automated actor — If APPROVE, fire issue_refund; if REJECT, fire send_rejection_email. The decision is always written via log_event to the audit trail.

The key point is that Step 5's external call cannot fire without Step 4's human-review actor. With human decision between LLM recommendation and external firing, LLM malfunctions are blocked from leaking outside the organization.

The human-review actor UI pattern

When a reviewer makes a decision, what should appear on the screen is central to HITL design.

Gather three things on one screen.

1. The LLM recommendation + grounding — Recommend APPROVE. Grounds: (1) tier=platinum, (2) past_approval_rate=0.85, (3) the refund reason maps to the 'defective' category in policy §3.2.
2. A bundle of raw context — The raw context the reviewer needs to decide whether to trust the recommendation. Order info, customer tier, past refund history, policy paragraph.
3. Three decision buttons — APPROVE / PARTIAL / REJECT. A different decision from the recommendation must be one click away.

If reviewers only accept the recommendation, HITL loses its value. For overrides to become routine, the UI should not over-emphasize the recommendation and instead expose raw context with equal weight.

Register actors — wire them to the agent

Like tools, register each actor under the agent builder's Actors panel. If actor firing order matters, also configure actor-level dependencies — e.g. issue_refund only fires when capture_review_decision's output is APPROVE.

What you should be able to do after this lesson

• The automated vs human-review split of actors
• The 5-step flow of HITL — input → tool → LLM → review → external firing
• The reviewer UI's three areas — recommendation + raw context + decision buttons

Next lesson

Pull knowledge resources via RAG embedding search and require citation grounding in responses.