Anvia Docs

Use requireApproval(...) from an onToolCall(...) hook. This is the approval gate: if the hook returns approval, Anvia does not run the tool until the approval handler resolves the request.

Require Approval for One Tool

import { createHook, requireApproval } from "@anvia/core";

const approvalHook = createHook({
  onToolCall({ toolName, args }) {
    if (toolName === "refund_order") {
      return requireApproval({
        reason: `Review refund request: ${args}`,
        rejectMessage: "Refund was not approved.",
        timeoutMessage: "Refund approval timed out.",
      });
    }
  },
});

The args value is the JSON string Anvia will send to the tool. Use it to show reviewers exactly what the model is trying to do.

Attach the Hook

Attach the hook to one request when approval rules are request-specific.

const response = await agent
  .prompt("Refund order A-100.")
  .withHook(approvalHook)
  .withToolApprovalHandler(handleApproval)
  .send();

Attach the hook to the agent when the rule should apply to every request.

const agent = new AgentBuilder("support", model)
  .tool(refundOrder)
  .hook(approvalHook)
  .defaultMaxTurns(3)
  .build();

Require Approval by Tool Name

Keep the approval rule explicit.

const sensitiveTools = new Set(["refund_order", "cancel_subscription"]);

const approvalHook = createHook({
  onToolCall({ toolName }) {
    if (sensitiveTools.has(toolName)) {
      return requireApproval({
        reason: `${toolName} requires human review.`,
      });
    }
  },
});

Use normal tool execution for safe read-only tools such as lookup or search.

Rejected and Timed-Out Approvals

When approval is rejected or timed out, Anvia skips the tool. The model receives a tool result containing the rejection or timeout text, then it can produce a final answer.

return requireApproval({
  rejectMessage: "The reviewer rejected this action.",
  timeoutMessage: "No reviewer approved this action in time.",
});

Use clear messages because the model sees them as the tool result.

Tool Approval

Require Approval for One Tool

Attach the Hook

Require Approval by Tool Name

Rejected and Timed-Out Approvals