Tutorial: human approval for a tool call

HITL is enforced at the Agent boundary. A protected tool call can be persisted, reviewed, and resumed without exposing a private decorated-agent attribute.

Define an approval-gated tool

from praval import Agent, InterventionRequired, ToolSpec


def critical_write(resource: str) -> str:
    return f"write-complete:{resource}"


spec = ToolSpec(
    name="critical_write",
    description="Perform a critical write",
    parameters={
        "type": "object",
        "properties": {"resource": {"type": "string"}},
        "required": ["resource"],
    },
    requires_approval=True,
    risk_level="critical",
    approval_reason="Writes to a production resource.",
)

Enable HITL and run

agent = Agent(
    "ops-agent",
    provider="openai",
    model="gpt-5.4-mini",
    hitl_enabled=True,
    hitl_db_path="./interventions.sqlite3",
)
agent.add_tool_spec(spec, critical_write)

try:
    try:
        response = agent.generate("Use critical_write for production/orders.")
        print(response.content)
    except InterventionRequired as interruption:
        print(interruption.intervention_id, interruption.run_id)
        agent.approve_intervention(
            interruption.intervention_id,
            reviewer="oncall",
            edited_args={"resource": "staging/orders"},
        )
        print(agent.resume_run(interruption.run_id))
finally:
    agent.close()

The model must actually request the tool for an intervention to be created. edited_args is optional; omit it to approve the original arguments. Use reject_intervention() with a reason to reject.

The SQLite store permits the pending intervention and suspended run to be inspected from another process before resumption.

CLI review

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>

If a tool requires approval while HITL is disabled, Praval raises HITLConfigurationError. It does not execute the tool autonomously.

MCP tools use the same approval flow but are async-only in this release. Resume those runs with the async Agent API.

The optional protected live certification verifies a real provider-generated call, persistent interruption, argument editing or approval, and resume.