RUNLOCALAIv38
->Will it run?Best GPUCompareTroubleshootStartLearnPulseModelsHardwareToolsBench
Run check
RUNLOCALAI

Independently operated catalog for local-AI hardware and software. Hand-written verdicts. Source-cited claims. Reproducible commands when we have them.

OP·Eruo Fredoline
DIR
  • Models
  • Hardware
  • Tools
  • Benchmarks
TOOLS
  • Will it run?
  • Compare hardware
  • Cost vs cloud
  • Choose my GPU
  • Prompting kits
  • Quick answers
REF
  • All buyer guides
  • Learn local AI
  • Methodology
  • Glossary
  • Errors KB
  • Trust
  • Suggest a feature
EDITOR
  • About
  • Author
  • How we make money
  • Editorial policy
  • Contact
LEGAL
  • Privacy
  • Terms
  • Sitemap
MAIL · MONTHLY DIGEST
Get monthly local AI changes
Monthly recap. No spam.
DISCLOSURE

Some links on this site are affiliate links (Amazon Associates and other first-class retailers). When you buy through them, we earn a small commission at no extra cost to you. Affiliate links do not influence our verdicts — there are cards we rate highly that we don't have affiliate relationships with, and cards that sell well that we refuse to recommend. Read more →

© 2026 runlocalai.coIndependently operated
RUNLOCALAI · v38
  1. >
  2. Home
  3. /Learn
  4. /How-to
  5. /How to implement human-in-the-loop for AI agents
HOW-TO · SUP

How to implement human-in-the-loop for AI agents

advanced·25 min·By Eruo Fredoline
Target environment
Ubuntu 24.04 · Ollama 0.4.x
PREREQUISITES

Agent workflow defined, human review interface

What this does

Implementing human-in-the-loop for AI agents adds approval checkpoints where the agent pauses execution and requests human judgment before performing high-stakes actions. These checkpoints can trigger for actions like deleting files, sending emails, executing financial transactions, or deploying code. The human reviewer sees the proposed action with context and can approve, reject, or modify it before the agent proceeds. This pattern reduces risk while preserving automation for low-risk steps.

Steps

Identify the agent actions that require human approval. Common candidates: file deletion, API calls that modify data, code execution, email sending, and configuration changes. Tag these actions in the agent's tool definitions with requires_approval: true. Implement the approval gate in the agent's execution loop. After the agent selects an action, check the tag: if action.requires_approval: approval = await request_approval(action). The request_approval function serializes the proposed action with all context—the user's original request, the reasoning chain, the action details—and sends it to the review channel. For synchronous review (CLI), present a formatted summary and use input("Approve? [y/n/e(dit)]: "). For asynchronous review, publish to a Redis channel and await a response on a unique correlation ID. Store the pending approval in a database table with fields: id, session_id, action_json, status (pending/approved/rejected/modified), created_at, reviewed_at, reviewer, modified_action_json. Set a timeout (default 30 minutes) after which pending approvals auto-reject with a logged reason. When the response arrives, resume the agent with the approved action, the modified action, or a rejection message instructing the agent to find an alternative path.

  • Record the local run evidence. Save the exact command, runtime or package version, model name if applicable, and observed output so the result can be reproduced later.

  • Confirm the local starting state. Print the active binary, package version, model name, or configuration path before changing the workflow.

  • Run the smallest complete path. Execute the minimum command or script that proves the guide works end to end on the local machine.

  • Compare against expected output. Check the final line, status code, generated artifact, or model response against the verification section before expanding the setup.

  • Record the local run evidence. Save the exact command, runtime or package version, model name if applicable, and observed output so the result can be reproduced later.

Verification

Run the agent with a task that triggers an approval checkpoint, e.g., "Delete all log files older than 7 days." Verify the agent pauses and displays the proposed deletion with a list of affected files. Approve the action and confirm files are deleted. Run the same task, reject the action, and verify no files are deleted and the agent reports the rejection. Test the timeout: leave a pending approval for 31 minutes and confirm it auto-rejects. Verify asynchronous approval by sending a task, checking the pending-approvals database, and approving via API—the agent should resume within 5 seconds.

Common failures

Agent hangs indefinitely waiting for approval: Ensure the timeout mechanism is working and that the agent has a fallback path when approval times out. Review channel not receiving approvals: Check the message queue connection and verify the correlation ID is correctly passed in the response. Approval decision lost after agent restart: Persist pending approvals to a database, not in-memory, so restarts can recover them. Reviewer overwhelmed by too many approval requests: Adjust the requires_approval tag to only flag truly risky actions; add a confidence threshold where the agent self-approves actions below the threshold. Race condition with concurrent approval and timeout: Use database-level locks or atomic state transitions (pending → approved/rejected) to prevent double-processing.

  • Version mismatch - The installed package or runtime differs from the command shown; check the version first and rerun the smallest verification command.
  • Local environment drift - Another service, virtual environment, model, or path is being used; print the active binary path and configuration before changing the guide steps.

Related guides

  • build-multi-agent-supervisor-workflow
  • implement-guardrails-ai-agents
  • setup-agent-observability-opentelemetry
← All how-to guidesCourses →