Guide

Agent Permission Design

How to design AI agent permissions with read, draft, write, approval, rollback, and audit boundaries before production use or team rollout safely.

Agent permission design is the control layer that keeps a useful workflow from becoming an unsafe automation. A model can make plausible decisions with incomplete context, and a tool can execute those decisions exactly. The risk appears when the agent has more authority than its evidence justifies.

Start with the principle that permissions are granted by impact, not by developer convenience. If an action changes external state, exposes private data, sends communication, spends money, changes access, or cannot be easily rolled back, it belongs behind an approval gate. The definition in what is an AI agent becomes operational only when every tool has a permission class.

The problem with broad tool access

Broad access makes demos easier and incidents harder. An agent with search, database, ticketing, email, repository, and publishing tools can appear powerful, but a single bad assumption can cross several boundaries before a human sees the result. The same prompt that works on a fixture may fail when a source is stale, a customer name is ambiguous, or a tool returns a partial result.

Permissions should reduce the blast radius of those ordinary failures. They should make the safe path easy and the dangerous path explicit. That means the agent can gather evidence and prepare work, but it cannot silently perform actions that require accountability.

Permission classes

Read-only permissions let the agent inspect approved sources. Examples include internal documentation search, repository read access, ticket lookup, and analytics queries. Read-only does not mean risk-free; sensitive sources still need access rules and redaction. But read-only is the correct starting point for most agents.

Draft-write permissions let the agent create artifacts that require review before they affect users or systems. Examples include draft support replies, proposed documentation edits, pull request comments, candidate summaries, and incident notes. Draft-write is valuable because it measures usefulness without surrendering control.

Production-write permissions let the agent modify live systems. Examples include sending email, closing tickets, changing records, merging code, publishing pages, or updating permissions. These should be rare, scoped, logged, and tied to explicit acceptance criteria.

Administrative permissions should almost never be available to a general agent. User management, billing, secrets, security policy, and destructive operations require separate workflows and strong human review.

Approval gates

Approval is not a sign that the agent failed. It is a designed checkpoint. Require approval when the action is irreversible, external, customer-visible, financially meaningful, security-sensitive, or based on weak evidence. The approval screen should show the proposed action, sources, tool calls, known uncertainty, and rollback plan.

For example, a documentation assistant may draft a page update automatically, but publishing it requires a reviewer. A support bot may prepare a response, but refund promises require approval. A research agent may summarize sources, but it should not email executives without a human decision.

Tool-call validation

Every tool call should pass validation before execution. Validate required fields, enum values, tenant or workspace scope, date ranges, record limits, and permission class. Reject calls that are too broad, missing identifiers, or inconsistent with the user’s request.

The model should receive a clear, bounded error when validation fails. Allow limited retries, then escalate. Infinite correction loops are a failure mode described in the AI agent failure modes guide.

Rollback and audit

Permissions are incomplete without rollback and audit. For each write action, define whether it can be reverted, who can revert it, and what evidence is required. If the action cannot be reverted, approval should be stricter. Store the trace described in the agent observability guide so reviewers can see why the action was allowed.

Audit logs should separate who requested the run, what the agent proposed, who approved it, which tool executed it, and what changed. Avoid logs that only say “agent completed task”; that is not enough for incident review.

Verification checklist

Before launch, list every tool and assign a permission class. Mark each action as read, draft-write, production-write, or administrative. Define approval conditions. Add schema validation for every parameter. Add rate limits and retry limits. Add a no-answer path when the agent lacks authority.

Then test fixtures that try to cross the boundary: broad search, ambiguous customer, malicious instruction in retrieved text, stale source, missing approval, and request for a destructive action. The agent should stop or escalate, not improvise authority.

Frequently asked questions

What permission should a new AI agent start with?

A new AI agent should start with read-only permissions, then earn draft-write and production-write access only after fixture tests and trace reviews pass.

When should an AI agent require human approval?

Human approval should be required for irreversible, external, financial, customer-visible, permission-changing, or privacy-sensitive actions.

Next step

Create a permission matrix before connecting tools. If a tool cannot be classified, validated, logged, and reviewed, it should not be available to the agent yet.