HITL Troubleshooting๏ƒ

Common issues for Human-in-the-Loop (HITL) interventions in Praval 0.7.22.

HITLConfigurationError๏ƒ

Symptom: A tool call fails immediately with HITLConfigurationError.

Cause: Tool metadata has requires_approval=True but the agent is decorated/configured with hitl=False.

Fix: Enable HITL for that agent:

@agent("ops_agent", hitl=True, tools=["critical_tool"])
def ops_agent(spore):
    ...

InterventionRequired during Agent.chat()๏ƒ

Symptom: chat() raises InterventionRequired.

Cause: Expected behavior for approval-gated tools on hitl=True agents.

Fix: Approve/reject/edit intervention, then resume the run:

agent.approve_intervention(intervention_id, reviewer="oncall")
agent.resume_run(run_id)

Pending queue never clears๏ƒ

Checklist:

  1. Inspect queue: praval hitl pending.

  2. Confirm intervention decision exists (APPROVED/REJECTED).

  3. Resume run via API or CLI.

  4. Verify DB path consistency (PRAVAL_HITL_DB_PATH vs explicit --hitl-db-path).

praval hitl resume cannot find agent๏ƒ

Symptom: CLI reports agent not registered in current process.

Cause: CLI process has not imported/initialized the module that defines the agent.

Fix: Use --module to import agent modules before resume:

praval hitl resume <run_id> --module your_project.agents

Resume fails after restart๏ƒ

Checklist:

  1. Use the same HITL SQLite database path across restarts.

  2. Ensure tool names and signatures are unchanged.

  3. Ensure code imports register the same agent name used by the suspended run.