Skip to main content

Permissions

In the world of Agents, efficiency is key, but so is control and safety. This is where Tool-Level Approval comes in – a powerful feature that ensures you, the human, always have the final say over your Agent's most critical actions.

This document dives deep into how Agents request your approval, why it's defined at the Tool level, and how this gives you remarkably fine-grained control.

The Agent's Journey: Action by Action​

Your Agent, powered by advanced AI, works by planning and executing a series of steps to achieve its goal. Often, these steps involve using various Tools to interact with the outside world – sending emails, updating databases, searching information, or posting content.

Most of the time, Agents can handle these steps autonomously. However, for certain actions, you'll want a safety net, a moment to review and confirm. This is precisely what Tool-Level Approval provides.

The Core Mechanism: Approval Defined at the Tool Level​

Unlike a blanket approval for an entire Agent's run, our system allows you to specify that individual Tools (or specific actions within a Tool) require your human approval before they are executed. This is a critical distinction that offers incredibly precise control.

Imagine your Agent has a "Send Email" Tool and an "Update Record" Tool. You might want the Agent to automatically update a record, but always ask for your review before sending any email. This is the power of Tool-Level Approval:

  • Not the Whole Agent: You're not approving the Agent itself, or every single step it takes.
  • Specific to the Tool/Action: You're saying, "Whenever this particular 'Send Email' Tool is about to be used, or whenever this 'Update Customer Details' Tool is about to modify a record, I need to see it first."
  • Fine-Grained Control: This level of detail means you can be incredibly precise. You can allow an Agent to perform 99% of its tasks automatically, while retaining control over that crucial 1% that carries significant implications.

This capability is typically configured when the Tool is set up or when it's assigned to an Agent, using a simple flag like "Requires Approval." (Behind the scenes, this corresponds to the require_approval flag you might have seen in the technical descriptions of Agent Tools).

Why Request Approval? Use Cases and Examples​

Tool-Level Approval is indispensable for preventing unintended consequences and maintaining high standards of accuracy. Here are common scenarios where it's vital:

  1. Preventing Irreversible Actions:

    • Deleting Data: An Agent might identify old records for deletion. You'd want to review the list of records to be deleted before it's permanently wiped from your database.
    • Financial Transactions: If an Agent is capable of initiating payments or transfers, you'd absolutely require approval for every transaction amount and recipient.
    • Public Posts: Before an Agent publishes a blog post, social media update, or a news article, you'll want to ensure the content is perfect.

  2. Ensuring Accuracy and Brand Voice:

    • Reviewing an Email Before Sending It: An Agent drafts a personalized response to a customer. Even if it's generally good, you can set the "Send Email" Tool to pause and let you review the exact wording, tone, and recipient before it leaves your outbox.
    • Generating Reports: An Agent compiles data into a report. You might want to approve the final summary or key conclusions before it's circulated.

  3. Validating Data Updates:

    • Reviewing Fields Before an Agent Makes an Update: An Agent might be tasked with updating customer information in your CRM. You can configure the "Update CRM Record" Tool to pause and show you exactly which fields it intends to change and what the new values will be before it commits the update. This prevents accidental data corruption or incorrect information being saved.

  4. Handling Sensitive Information:

    • If an Agent is about to access highly confidential data or is tasked with sharing it, an approval step ensures that proper protocols are followed and no sensitive information is mishandled.

  5. Managing Costs:

    • Some Tool actions might incur costs (e.g., initiating a large batch of cloud compute jobs, or running an extensive data query). An approval step can act as a gatekeeper for these budget-impacting actions.

How the Approval Request Works (The "Hard Stop")​

When an Agent's plan involves a Tool that requires approval, here's the precise flow:

  1. Agent's Decision: The Agent's AI determines that using a specific Tool (like "Send Customer Email") is the next logical step to achieve its goal.
  2. Payload Generation: The Agent proceeds to prepare exactly what it intends to do with that Tool. For an email, this means generating the recipient, subject, and full body text. For an update, it means identifying the record and the precise field changes. This complete instruction set is called the "payload."
  3. System Interception: At this critical moment, our system recognizes that this specific Tool has the require_approval flag set to True. Instead of sending the generated "payload" to the Tool for immediate execution, the system intercepts it.
  4. Human Presentation: The system then presents this "payload" to you in a clear, understandable format (e.g., in your dashboard's approval queue). You'll see precisely what the Agent proposes to do.
  5. The "Hard Stop": This is the crucial part. The Tool's execution code will not run until you provide your explicit approval. There is no way for the Agent to bypass this. It's a mandatory pause, ensuring you have the ultimate veto power over that specific action.

Your Interaction and Decision​

When an Agent is awaiting your approval, you'll typically receive a notification and find the pending task in your Agent dashboard or a dedicated "Approval Inbox." You'll see:

  • The Agent's Name: Which Agent is requesting approval.
  • The Tool Being Used: Which specific capability it's trying to invoke.
  • The Proposed Action Details: The exact "payload" – the email content, the data fields to be updated, the file to be deleted, etc. – presented clearly for your review.
  • The Agent's Reasoning: Often, the Agent will also provide context on why it wants to perform this action.

You then have two clear options:

  • Approve: If you agree with the Agent's proposed action, you approve it. The system then releases the "payload" to the Tool, and the Tool's code executes exactly as the Agent proposed. The Agent then continues its task.
  • Reject: If you disagree, find an error, or simply don't want the action to proceed, you reject it. The Tool's execution is cancelled for that specific instance, and the Agent will typically mark that step as failed or might return to a previous decision point, depending on its programming.

The Benefits of Tool-Level Approval​

  • Unrivaled Control: You maintain precise, granular control over sensitive or critical operations.
  • Eliminate Guesswork: No more wondering if your Agent is doing something it shouldn't. You get to review the exact details.
  • Enhanced Accuracy: Catch errors or refine outputs before they go live, ensuring quality and precision.
  • Risk Mitigation: Significantly reduces the risk of costly mistakes, data corruption, or brand damage.
  • Builds Trust: You can confidently deploy Agents for more complex tasks, knowing that you have the final safety check in place.

By leveraging Tool-Level Approval, you empower your Agents to be highly capable, while ensuring you always remain the ultimate decision-maker for the actions that matter most.