Tutorial: HITL Interventions๏ƒ

Learn how to enforce human approvals for risky tool calls using agent-gated HITL.

Prerequisites๏ƒ

  • pip install -e .[dev]

  • At least one provider API key set (OpenAI, Anthropic, or Cohere)

1) Mark a Tool as Approval-Gated๏ƒ

from praval import tool

@tool(
    tool_name="critical_write",
    description="Perform a critical write",
    requires_approval=True,
    risk_level="critical",
    approval_reason="Writes to production resources."
)
def critical_write(resource: str) -> str:
    return f"write-complete:{resource}"

2) Enable HITL on the Agent๏ƒ

from praval import agent

@agent("ops_agent", tools=["critical_write"], hitl=True)
def ops_agent(spore):
    return {"status": "ready"}

hitl=False is the default, so enable it only for agents that should pause for human decisions.

3) Run, Approve, Resume๏ƒ

from praval import InterventionRequired

try:
    response = ops_agent._praval_agent.chat("Run critical_write on prod")
    print(response)
except InterventionRequired as interruption:
    # Option A: approve original arguments
    ops_agent.approve_intervention(interruption.intervention_id, reviewer="oncall")

    # Option B: edit arguments before approval
    # ops_agent.approve_intervention(
    #     interruption.intervention_id,
    #     reviewer="oncall",
    #     edited_args={"resource": "staging"},
    # )

    resumed = ops_agent.resume_run(interruption.run_id)
    print(resumed)

4) CLI Workflow๏ƒ

praval hitl pending
praval hitl show <intervention_id>
praval hitl approve <intervention_id> --reviewer oncall
praval hitl reject <intervention_id> --reason "Unsafe"
praval hitl resume <run_id>

5) Conflict Semantics๏ƒ

If an agent is declared with hitl=False and the invoked tool requires approval, Praval raises HITLConfigurationError. This prevents accidental policy bypass.

See Also๏ƒ