Tool Approvals

Tool approvals are the AI SDK agent mechanism for pausing selected tool executions before they happen. In a ToolLoopAgent, tools that define execute normally run automatically when the model calls them. That default is convenient for low-risk actions, but it is not appropriate for operations that can delete data, spend money, run commands, send messages, or reveal private information. The toolApproval option lets an application review each relevant tool call, approve it, deny it, or ask a human user before the tool is executed.

Sources: content/docs/03-agents/06-tool-approvals.mdx

Purpose and Scope

Use this page when you already have an agent with tools and need to decide which tool calls require a safety gate. The repository documentation frames approvals as part of the agent tool loop rather than as a provider feature. That distinction matters: approvals apply to tools executed by the AI SDK, while provider-executed tools run provider-side and do not participate in AI SDK approval handling. In practice, approval rules belong near agent setup because they define how your application handles sensitive local capabilities.

Sources: content/docs/03-agents/06-tool-approvals.mdx

A tool approval policy returns a status for a tool call. Some statuses are terminal, and some allow execution to continue. A rule can say that approval is not applicable, approve automatically, deny automatically, or emit a user approval request. The documentation also allows automatic approval and denial statuses to carry a reason, which is useful for audit trails, UI explanations, and debugging why a tool did or did not run. Approval functions may also return undefined, which is treated like not-applicable.

Sources: content/docs/03-agents/06-tool-approvals.mdx

Relevant Source Files

• content/docs/03-agents/06-tool-approvals.mdx — first-party documentation for ToolLoopAgent toolApproval, approval statuses, per-tool configuration, input-dependent approval functions, and generic approval rules.

Core Concepts

The smallest approval configuration is a per-tool map. Each key is the tool name registered on the ToolLoopAgent, and each value is either a fixed approval status or an approval object. For example, a runCommand tool can be configured with toolApproval: { runCommand: 'user-approval' }. When the model calls that tool, the agent returns a tool-approval-request instead of immediately calling the tool’s execute function. That makes the model’s intended action visible to the application before any side effect occurs.

Sources: content/docs/03-agents/06-tool-approvals.mdx

Per-tool approval functions are the next level of control. They are used when the decision depends on validated tool input rather than only the tool name. The documented processPayment example receives parsed values such as amount and uses metadata such as runtimeContext to decide what happens. Non-admin users can be denied automatically, large payments can request manual approval, and smaller admin payments can proceed without approval metadata. This pattern keeps simple authorization and risk thresholds close to the tool that performs the sensitive action.

Sources: content/docs/03-agents/06-tool-approvals.mdx

A generic approval function is useful when a single policy must reason across the entire tool call rather than one named tool. The documentation calls this a GenericToolApprovalFunction. It receives the full toolCall, including fields such as toolName, toolCallId, input, and whether the call is dynamic. That makes it appropriate for shared policy logic, dynamic tool sets, or cross-tool checks such as requiring approval for every dynamic tool call while also requiring approval for a known destructive tool like deleteFile.

Sources: content/docs/03-agents/06-tool-approvals.mdx

Approval Status Reference

Automatic approval and denial can be returned either as strings or as objects with a type field. Use the object form when the application should preserve an explanation, such as { type: 'denied', reason: 'Deleting files is disabled in this workspace' }. That reason is especially important when tool approval results are surfaced in an operator interface, stored for review, or used to explain why an agent did not complete a requested task. The rule can also return undefined when no approval behavior applies.

Sources: content/docs/03-agents/06-tool-approvals.mdx

Execution Flow

The execution flow starts after the model selects a tool. The agent checks the toolApproval configuration before invoking the tool’s execute function. If the rule returns not-applicable or undefined, the tool runs normally. If it returns approved, the approval is recorded and the tool runs. If it returns denied, the agent does not execute the tool and instead returns a denied tool output. If it returns user-approval, the agent emits a tool-approval-request and waits for an explicit approval response before proceeding.

Sources: content/docs/03-agents/06-tool-approvals.mdx

This flow is designed for human-in-the-loop user interfaces as well as automated guardrails. A chat UI, terminal UI, or workflow host can render the approval request, show the tool name and parsed input, ask the user or operator for a decision, and then send the response back into the agent run. The important implementation boundary is that the sensitive execute function has not run while the request is pending. That lets applications treat approval as a true pre-execution gate rather than as a post-hoc notification.

Sources: content/docs/03-agents/06-tool-approvals.mdx

API Components and Signatures

The documented per-tool approval function receives the typed tool input as its first argument. Its second argument includes contextual data such as toolCallId, messages, toolContext, and runtimeContext. This signature lets a policy combine validated input with request-scoped information. For example, runtimeContext.role can determine whether a caller is allowed to make payments, while the parsed amount determines whether the payment is small enough to execute automatically or large enough to require human review.

Sources: content/docs/03-agents/06-tool-approvals.mdx

toolApproval: {
  processPayment: async ({ amount }, { runtimeContext }) => {
    if (runtimeContext.role !== 'admin') {
      return { type: 'denied', reason: 'Only admins can send payments' };
    }
 
    return amount > 1000 ? 'user-approval' : undefined;
  },
}

The generic form receives an object centered on toolCall, which includes the selected tool name, call identifier, input, and dynamic-tool information. Prefer this form when approval is not owned by one tool definition. For example, a workspace policy might require user approval for any dynamic tool call because the tool may not have been known when the agent was created. The same policy can also single out known high-risk tools, such as file deletion, while leaving read-only tools to execute normally.

Sources: content/docs/03-agents/06-tool-approvals.mdx

Implementation Guidance

Start by classifying tools by risk. Read-only tools often need no approval, while tools that mutate external state usually need either automatic policy checks or manual review. Encode obvious denials as denied so the agent receives a clear tool output without involving a human. Encode allowed low-risk cases as not-applicable, undefined, or approved depending on whether you need approval metadata. Reserve user-approval for operations where a person must inspect the specific call before it runs.

Sources: content/docs/03-agents/06-tool-approvals.mdx

When you build the UI around approvals, display the tool name, parsed input, and any reason supplied by the approval rule. Preserve the toolCallId so the response can be correlated with the pending request. Do not assume that provider-side tools can be intercepted by this mechanism, because the documentation explicitly limits toolApproval to tools executed by the AI SDK. If you need policy centralization beyond inline functions, the related policy-based approval documentation builds on the same request and response flow.

Sources: content/docs/03-agents/06-tool-approvals.mdx

Next Steps

After adding approval rules, test each status deliberately: a normal execution path, an automatic approval path, an automatic denial path, and a pending user approval path. For larger systems, compare inline toolApproval functions with policy-based approvals, especially when authorization rules should be reviewable outside the agent code. Also review the related agent pages on loop control, runtime context, tool calling, and policy-based tool approvals so approvals are combined with appropriate stopping conditions, request-scoped data, and UI handling.