Tool Approval Strategy for Spring AI Tool Calling

[rmukubvu]

1. Motivation

Spring AI supports tool calling, allowing models to invoke arbitrary functions, services, and APIs via ToolCallbacks. While powerful, this introduces risk:

• Some tools can modify or delete data.
• Some tools might be expensive or rate-limited.
• Not all tools should be accessible to all conversations or tenants.

Today, once the model decides to call a tool, Spring AI executes it without any pluggable approval step.

This proposal introduces a small, focused Tool Approval Strategy that lets application developers decide, at runtime, whether a given tool call should be executed, rejected, or handled in a custom way, without breaking existing behavior.

---

2. Goals and Non-Goals

2.1 Goals

• Provide a simple, Spring-style hook to approve or reject tool calls before execution.
• Allow per-tool overrides (e.g., some tools always require approval, some never do).
• Preserve backwards compatibility: existing applications behave exactly as they do today by default.
• Keep the v1 surface area as small as possible while being clearly useful.

2.2 Non-Goals (for v1)

The following ideas are explicitly out of scope for this initial version and can be addressed in follow-up work:

• Composite strategies (AND/OR composition, builder APIs).
• Async or human-in-the-loop approval flows.
• Dedicated auditor components.
• Rich observability/metrics integrations.
• Complex policy languages or rule engines.

---

3. High-Level Design

At a high level, the design adds:

1. A ToolApprovalStrategy functional interface that is consulted before any tool is executed.
2. A ToolApprovalDecision value type describing the outcome (approved/rejected).
3. A ToolApprovalException for signaling hard failures in the approval layer.
4. A requiresApproval flag on tool metadata to allow per-tool configuration.
5. A small change to DefaultToolCallingManager to invoke the strategy and handle rejections.

Default behavior is preserved via an AlwaysApproveStrategy that simply approves every tool call. Applications can provide their own strategy as a Spring bean to override this behavior.

---

4. Public API (v1)

4.1 ToolApprovalStrategy

A functional interface that receives information about the tool call and returns a decision.

@FunctionalInterface
public interface ToolApprovalStrategy {

    /**
     * Decide whether the given tool call should be approved or rejected.
     *
     * @param toolCallback the tool definition and metadata
     * @param arguments the raw JSON arguments for the tool call
     * @param toolContext optional context (conversation, user, etc.), may be null
     * @return a ToolApprovalDecision indicating approve or reject
     * @throws ToolApprovalException to signal an error evaluating approval
     */
    ToolApprovalDecision approve(ToolCallback toolCallback,
                                 String arguments,
                                 @Nullable ToolContext toolContext)
            throws ToolApprovalException;

    // Convenience implementations for common cases

    static ToolApprovalStrategy alwaysApprove() {
        return (tool, args, ctx) -> ToolApprovalDecision.approve();
    }

    static ToolApprovalStrategy alwaysReject(String reason) {
        return (tool, args, ctx) -> ToolApprovalDecision.reject(reason);
    }
}

A simple default implementation:

public final class AlwaysApproveStrategy implements ToolApprovalStrategy {

    @Override
    public ToolApprovalDecision approve(ToolCallback toolCallback,
                                        String arguments,
                                        @Nullable ToolContext toolContext) {
        return ToolApprovalDecision.approve();
    }
}

Framework default: AlwaysApproveStrategy.

---

4.2 ToolApprovalDecision

A small value type that represents the outcome of a strategy decision.

public record ToolApprovalDecision(
        boolean approved,
        @Nullable String reason,
        @Nullable Map<String, Object> metadata
) {

    public static ToolApprovalDecision approve() {
        return new ToolApprovalDecision(true, null, null);
    }

    public static ToolApprovalDecision approve(String reason) {
        return new ToolApprovalDecision(true, reason, null);
    }

    public static ToolApprovalDecision reject(String reason) {
        return new ToolApprovalDecision(false, reason, null);
    }

    public static ToolApprovalDecision reject(String reason,
                                              @Nullable Map<String, Object> metadata) {
        return new ToolApprovalDecision(false, reason, metadata);
    }
}

• reason is intended primarily for logging and optional model/user-facing messages.
• metadata is included for future extensibility (e.g., attaching policy IDs, severity, tenant IDs). v1 does not prescribe a specific schema.

---

4.3 ToolApprovalException

A dedicated exception type for approval-layer failures.

public class ToolApprovalException extends RuntimeException {

    private final String toolName;

    public ToolApprovalException(String toolName, String message) {
        super(message);
        this.toolName = toolName;
    }

    public ToolApprovalException(String toolName, String message, Throwable cause) {
        super(message, cause);
        this.toolName = toolName;
    }

    public String getToolName() {
        return toolName;
    }
}

This exception is not thrown for “normal” rejections (those are represented by ToolApprovalDecision); it is used when something goes wrong evaluating the approval (e.g., policy engine unavailable).

---

4.4 ToolMetadata.requiresApproval

Tools can opt in or out of approval on a per-tool basis.

public interface ToolMetadata {

    // existing methods...

    /**
     * Whether this tool requires approval before execution.
     *
     * <ul>
     *   <li>null – use the global ToolApprovalStrategy (default behavior)</li>
     *   <li>true – always apply the approval strategy for this tool</li>
     *   <li>false – never apply the approval strategy for this tool</li>
     * </ul>
     */
    @Nullable
    Boolean requiresApproval();
}

For example:

• A harmless, read-only tool can set requiresApproval = false to bypass approval even if a global strategy is configured.
• A sensitive tool can set requiresApproval = true to ensure it is always subject to the strategy.

---

5. Default Behavior and Backwards Compatibility

To avoid breaking existing applications:

• If no ToolApprovalStrategy bean is registered, Spring AI configures an AlwaysApproveStrategy internally.
• If requiresApproval() returns null and the default strategy is used, the behavior is identical to today: all tools are executed as requested by the model.
• Rejections are only possible when:
  • The application supplies a custom ToolApprovalStrategy, and
  • Either the tool’s requiresApproval is true, or the strategy is applied globally (see below).

---

6. DefaultToolCallingManager Integration

DefaultToolCallingManager is extended to consult the approval strategy before invoking a tool.

High-level flow for a single tool call:

1. Parse tool call from model output.
2. Resolve the corresponding ToolCallback.
3. Check if approval is required for this tool.
4. If required:
   • Call toolApprovalStrategy.approve(...).
   • If decision is approved, proceed with tool execution.
   • If decision is rejected, return a structured rejection back into the model conversation instead of executing the tool.
5. If approval is not required:
   • Execute the tool as today.

Pseudo-code:

public class DefaultToolCallingManager implements ToolCallingManager {

    private final ToolApprovalStrategy toolApprovalStrategy;

    public DefaultToolCallingManager(ToolApprovalStrategy toolApprovalStrategy) {
        this.toolApprovalStrategy = toolApprovalStrategy;
    }

    @Override
    public ToolExecutionResult executeToolCall(ToolCallback toolCallback,
                                               String arguments,
                                               @Nullable ToolContext toolContext) {

        if (isApprovalRequired(toolCallback)) {
            ToolApprovalDecision decision = toolApprovalStrategy.approve(
                    toolCallback, arguments, toolContext
            );

            if (!decision.approved()) {
                // Do not execute the tool; propagate rejection as a tool response
                return ToolExecutionResult.rejected(
                        toolCallback,
                        decision.reason(),
                        decision.metadata()
                );
            }
        }

        // Existing behavior: execute tool
        return executeTool(toolCallback, arguments, toolContext);
    }

    private boolean isApprovalRequired(ToolCallback toolCallback) {
        Boolean perTool = toolCallback.getToolMetadata().requiresApproval();
        if (perTool != null) {
            return perTool;
        }
        // Fallback: by default, consult the strategy.
        // The default strategy simply approves everything.
        return true;
    }
}

Notes:

• ToolExecutionResult.rejected(...) is a placeholder for the existing response type used to represent tool outputs. In v1, rejections would be encoded as a tool response that the model can see (e.g., “Tool execution was denied: ”).
• The strategy is always invoked when isApprovalRequired() returns true. With the default AlwaysApproveStrategy, this is O(1) and effectively a no-op.

---

7. Example Usage

7.1 Application configuration: simple blacklist

An application might define a simple blacklist strategy:

@Configuration
public class ToolApprovalConfig {

    @Bean
    public ToolApprovalStrategy toolApprovalStrategy() {
        Set<String> blockedTools = Set.of("deleteAccount", "dropDatabase");

        return (tool, args, ctx) -> {
            if (blockedTools.contains(tool.getName())) {
                return ToolApprovalDecision.reject(
                        "Tool '" + tool.getName() + "' is not allowed in this environment.");
            }
            return ToolApprovalDecision.approve();
        };
    }
}

With no changes to the rest of the application, any attempt by the model to call deleteAccount or dropDatabase will be rejected before execution.

7.2 Per-tool override: safe tools

@Tool(
    name = "getWeather",
    description = "Get current weather for a given city"
)
public class WeatherTool {

    @ToolMetadataImpl(
        requiresApproval = false // read-only, no approval needed
    )
    public String getWeather(@P("city") String city) {
        // ...
    }
}

Even if the global ToolApprovalStrategy implements complex policies, this tool bypasses approval.

---

8. Future Extensions (Out of Scope for v1)

The v1 design intentionally limits scope to a small, composable core. Potential future enhancements include:

• Composite strategies (e.g., combine multiple strategies with AND/OR logic).
• Async / human-in-the-loop approval, where a strategy can pause execution until external approval is received.
• Auditor interfaces for central logging of all tool decisions.
• Rich metrics and tracing using Spring Observability, powered by ToolApprovalDecision.metadata.
• Built-in policies, e.g., argument-based constraints, tenant-aware rules, or environment (dev/stage/prod) gating.

These can be added incrementally on top of the v1 foundation without breaking changes.

---

End of v1 doc