Skip to main content
Approval asks a reviewer to allow or deny a proposed tool action. The SDK returns the denial to the model when approval is refused. A run may then complete by explaining that the action was not performed.

Complete local example

This example prompts an operator in the terminal and records only a simulated refund. It does not contact a payment service. Install @agentium/core, openai, and zod; use the project setup.
support.ts
Type y to approve or press Enter to deny. Inspect the final simulated-refund count as well as the model’s response. The tutorial explains both outcomes.

Configuration

Return { approved: boolean, reason?: string } from the callback. A tool can set requiresApproval to a boolean or an argument-dependent function. These per-tool values override the legacy approval.policy, including a false exemption. Use host execution policy for mandatory decisions that a tool cannot relax.

Hosted review

Without a callback, approval can wait for an event-driven decision. tool.approval.request announces a pending request; the approval manager owns the decision. Bind reads and decisions to the verified user/tenant and the pending action. Do not forward an arbitrary client-provided request ID to an unscoped approve operation. Callback/event approval is local to this execution lifecycle. When the decision must survive a restart, use the separately admitted durable action/approval contract.

Timeouts and effects

The default timeout decision denies execution. Timing out the SDK decision does not automatically cancel an arbitrary application callback that is still waiting. Close resources owned by that callback, such as terminal or UI listeners, when their owner finishes. Approval is permission to attempt an action. It does not establish that a remote action succeeded or make it idempotent. A real payment or notification requires the service’s own outcome and reconciliation rules; see recovery.