Skip to content
⚠️ Before You Start
Risk: High
Duration: 1-2 days including client review
Last Validated: Not yet validated (draft)
Kind: Decision guide
Risk Note: High (a loose envelope is the root cause of excessive-agency incidents)

Define an agent's permission envelope: scope, spend, actions and data

Draft outline: not validated

Drafted with AI from official sources on 16 Oct 2026. Checked and verified against official sources on 10 November 2026. Do not use on a live system until it is written, dry-run by someone other than the author and signed off (planned 2026-11-27). Author: Prasanna · dry-run: Devadharshini Raja · sign-off: James. Work items: AGT-08-T01, AGT-08-T02, AGT-08-T03, AGT-08-T04.

1. Summary

This guide helps an agent lead decide what a tool-using agent is allowed to do, before the agent is built. It writes the answer as one permission envelope with four parts: scope, spend, actions and data. Two choices settle most of it: how independent the agent is (autonomy tier) and which identity it runs as.

The default is simple. Use act with approval for any tool that writes, sends or spends, and give each agent its own user-assigned managed identity with no role broader than resource group scope (team default). Facts checked against official documentation on 10 November 2026.

Risk: High (a loose envelope is the root cause of excessive-agency incidents). Typical duration: 1-2 days including client review.

2. When to use and when not to

Use this guide when:

  • You are about to build an agent that can call tools, and nobody has yet written down what it may do.
  • A client board or risk committee asks what the agent is allowed to do and you need an answer you can defend.
  • You add a tool that writes, sends or spends to an existing agent.
  • The review date in an existing envelope has passed.

Do not use it when:

  • The envelope is agreed and you need to enforce it in code. Use PB-AGT-08-02.
  • You want to change an envelope or a role assignment that is already in production. Use PB-AGT-08-03.
  • An agent has already acted outside its envelope. Use PB-AGT-08-04.
  • You are doing the go-live review. Use PB-AGT-08-05.
  • You only need to set spend limits and decide what happens at the limit. Use PB-AGT-11-01 and PB-AGT-11-04.
  • The agent only reads data and has no side effects. It still needs its own identity and a data boundary, but it needs no approval gates.

3. What you must know first

  1. Excessive agency is the core risk. OWASP lists LLM06:2025 Excessive Agency in its Top 10 for LLM Applications 2025. LLM10:2025 Unbounded Consumption and LLM02:2025 Sensitive Information Disclosure relate to the spend and data parts of the envelope (team mapping). OWASP also publishes a Top 10 for Agentic Applications 2026, dated 9 December 2025. Its entry names are in a downloadable document.
  2. The envelope has four parts. Scope (what the agent can reach), spend (how much it may use), actions (which tools it may call, and which need approval) and data (which sources, classifications and tenants it may touch). This split is team guidance.
  3. Give each agent its own identity. A managed identity removes the need to manage credentials. A system-assigned identity is tied to one Azure resource. A user-assigned identity is a separate resource that several resources can share. Use one identity per agent, never a shared service principal or a human account, so that every action can be traced to one agent (team guidance). Source: What are managed identities for Azure resources?
  4. Entra Agent ID adds agent-specific controls. An agent identity is a special service principal with no credentials of its own. It is created from a reusable blueprint, which holds the credentials. An administrator can then apply conditional access to, disable, or revoke permission grants for all agents of one kind. Each agent identity can have a sponsor, the person or group accountable for it, who is contacted in a security incident. Agent identities work in one tenant only. Source: Overview of agent identities in Microsoft Entra Agent ID.
  5. Grant the least privilege at the narrowest scope. Azure RBAC guidance says to avoid broader roles at broader scopes, to use a narrow scope such as resource group or resource for privileged roles, to assign roles to groups and not to users, to use role IDs and not role names in scripts, and to avoid the wildcard in custom roles. Our team rule is that no agent identity holds a role broader than resource group scope. Source: Best practices for Azure RBAC.
  6. Every tool falls into one of three classes. Allow, allow with approval, or deny. Irreversible actions default to approval (team guidance). The class is enforced in code, outside the prompt, which is what PB-AGT-08-02 builds. AWS's AgentCore Policy follows the same idea: it checks every tool call at the gateway, outside the agent's code. Source: Policy in Amazon Bedrock AgentCore.

4. Options

Two decisions shape the envelope: how independent the agent is, and which identity it runs as. The tool classes, the data boundary and the spend limits follow from them.

The envelope in four parts

Part Question it answers What you write Related OWASP risk (team mapping)
Scope What can the agent reach? The identity and its role assignments, each at resource group scope or narrower LLM06 Excessive Agency
Actions Which tools may it call? Each tool classed as allow, allow with approval or deny LLM06 Excessive Agency
Data Which data may it touch? Sources, the highest data classification, and whether it may cross tenants LLM02 Sensitive Information Disclosure
Spend How much may it use? Limits per run, per user and per tenant (set in AGT-11) LLM10 Unbounded Consumption

Decision 1: the autonomy tier

Option A: Suggest only

The agent recommends and a person acts. No write, send or spend tool is available to the agent. Fits a new or unproven agent, or a pilot. Lowest risk and the slowest to use. Carried out by PB-AGT-08-02 (the suggest-only switch).

Option B: Act with approval (default)

The agent may read freely. Any tool that writes, sends or spends pauses for a person's approval, who sees the exact tool and arguments. Fits most production agents. Moderate risk, plus human review time. Carried out by PB-AGT-08-02.

Option C: Act and report

The agent acts without approval and reports what it did. Fits only tools that are read-only, or that can be undone and carry a low value, and only after sign-off. Highest risk, and the fastest. Carried out by PB-AGT-08-02.

Option A: Suggest only Option B: Act with approval Option C: Act and report
Who performs a write A person The agent, after approval The agent
Review effort High (a person does it) Medium (approvals) Low (after-the-fact reports)
Worst case if wrong A bad suggestion An approver approves a bad action A bad action happens
Typical use Pilot, new agent Production default Read-only or reversible low-value tools

Decision 2: the identity model

Option A: One user-assigned managed identity per agent (default)

A standalone Azure resource with its own role assignments. No credentials to manage. Fits one agent or a small number of agents on Azure resources. No extra cost. Control is per agent, by hand. Carried out by PB-AGT-08-02 and PB-AGT-08-03.

Option B: Entra Agent ID blueprint with agent identities

One blueprint per kind of agent, and one agent identity per deployed agent, each with a sponsor. Fits a fleet of agents of the same kind, or where an administrator must disable or revoke access for a whole kind at once. Check availability and any licence needs before you commit. Carried out by PB-AGT-08-03.

Not an option: a shared service principal or a human account

Actions cannot be traced to one agent, and one leak exposes every agent that shares it.

Option A: Managed identity Option B: Entra Agent ID
Credentials None to manage Held by the blueprint
Control at scale Per agent Per kind of agent, through the blueprint
Accountable person Recorded in the envelope (owner) Sponsor on the agent identity
Maturity Established Check current status

How to write the envelope

  1. List every tool and tag it as read-only, reversible write or irreversible write.
  2. Choose the autonomy tier (Decision 1).
  3. Class each tool as allow, allow with approval or deny for that tier.
  4. Define the data boundary: which sources, which classifications and which tenants.
  5. Set spend limits per run, per user and per tenant with the cost pack (PB-AGT-11-01 and PB-AGT-11-04).
  6. Choose the identity (Decision 2) and assign roles at resource group scope or narrower.
  7. Write the envelope as a JSON policy file that the code enforces and that fails closed when it is missing or invalid.
  8. Review the envelope against the OWASP risks and record the risks you accept.
  9. Get sign-off from the business owner and the Responsible AI officer.

Draft snippet: Permission envelope for one agent

{
  "agent": "${AGENT_NAME}",
  "owner": "${OWNING_TEAM}",
  "autonomyTier": "act-with-approval",
  "identity": {"type": "userAssignedManagedIdentity", "clientId": "${AGENT_CLIENT_ID}"},
  "actions": {"allow": ["lookup_invoice", "draft_email"], "requireApproval": ["issue_refund", "send_email"], "deny": ["delete_invoice", "change_bank_details"]},
  "data": {"sources": ["erp-invoices"], "maxClassification": "${MAX_CLASSIFICATION}", "crossTenant": false},
  "spend": {"maxTokensPerRun": "${MAX_TOKENS_PER_RUN}", "maxStepsPerRun": "${MAX_STEPS_PER_RUN}"},
  "approvedBy": ["${BUSINESS_OWNER_ROLE}", "responsible-ai-officer"],
  "reviewDate": "${REVIEW_DATE}"
}

The tool names and autonomyTier values match PB-AGT-08-02. Set every ${...} value from your own decisions. This guide does not recommend a number for the spend limits.

Snippets to add:

  • snippets/governance/agent-policy.json: Agent permission envelope policy file (json)
  • snippets/governance/envelope-review.md: Envelope review record with OWASP mapping (markdown)

5. Decision table

Situation Choose Why
New agent with any tool that writes, sends or spends Act with approval, one managed identity Irreversible actions default to approval. A person sees the exact tool and arguments.
The agent only reads data and has no side effects Act and report, plus its own identity and a data boundary There is nothing to approve, but a leak of read access is still a risk.
A tool cannot be undone (delete, payment, external message) Allow with approval, or deny The cost of one mistake is higher than the cost of a review.
A tool can be undone and carries a low value Act and report, after sign-off Approval adds delay without much risk reduction.
A new or unmeasured agent, or a pilot Suggest only Move to act with approval once evaluation shows the agent is reliable (PB-AGT-07 metrics).
One agent, or a few, on Azure resources One user-assigned managed identity per agent No credentials to manage, and no extra cost.
A fleet of agents of one kind, or an administrator must disable or revoke access for a whole kind Entra Agent ID blueprint The blueprint lets an administrator act on all agents of a kind. Check availability first.
The agent needs a person's data rights On-behalf-of user tokens, and minimal rights for the agent itself The agent then does not hold tenant-wide data rights.
Someone proposes a shared service principal or a human account Do not. Give the agent its own identity One identity per agent keeps actions traceable.
A role is needed above resource group scope Stop and redesign, or record an exception with sign-off The team rule is no broader than resource group scope.
A tool can run arbitrary code or SQL Deny, or replace it with single-purpose tools A permitted meta-tool can run commands outside the allow-list.

Default: act with approval for every tool that writes, sends or spends. Read tools are allowed. One user-assigned managed identity per agent, with roles at resource group scope or narrower. The envelope is a JSON file that the code enforces and that fails closed. The business owner and the Responsible AI officer sign it off, and it has a review date.

Deviate when:

  • The agent is new or unmeasured. Start at suggest only.
  • A tool is read-only, or reversible and low value. Act and report may be justified, with sign-off.
  • You run a fleet of one kind of agent. Consider Entra Agent ID.
  • A role is needed above resource group scope. Record an exception with sign-off. Do not widen the role quietly.

Rule of thumb: if you could not explain a tool's worst case to the client board in one sentence, that tool needs approval or a denial.

7. Known issues and fixes

Symptom Likely cause Fix
Envelope approved but code ignores it The policy is kept only as a document Load the JSON policy at runtime and fail closed when it is missing (PB-AGT-08-02)
Agent needs a human's data rights The agent runs as an app with tenant-wide rights Use on-behalf-of user tokens for user-scoped data and keep the agent's own rights minimal
Every tool ends up on approval Risk tagging is too cautious Split tools into read and write operations and approve only the writes
An agent identity holds Contributor at subscription scope A broad role was assigned for convenience Replace it with a narrower role at resource group scope or below
Role assignment automation breaks after a role is renamed Scripts use the role name Assign roles by the unique role ID
A custom role grants more than intended The role uses a wildcard in its permissions List the actions and data actions explicitly
Actions cannot be traced to one agent Several agents share one identity Give each agent its own identity
The envelope no longer matches production The policy file was edited without sign-off Restore the signed-off file and raise a governance incident

8. Monitoring and alerts

The thresholds below are team defaults, not platform recommendations. Tune them against your own baseline.

Signal Alert when Action
Policy file version in production (custom check) Differs from the last signed-off version Raise a governance incident and restore the signed-off file.
Role assignment changes for the agent identity (Azure Activity Log; check the exact operation name in the docs) Any change not made through the change process Review the change. If it was not approved, use PB-AGT-08-04.
Sign-in activity of the agent identity (Microsoft Entra sign-in logs) Sign-ins from a source or at a time you do not expect Investigate. Check whether the identity is used outside the agent.
Envelope review date (custom check) The review date has passed Run the review again and sign it off.

9. Cost and capacity notes

  • Identity. Managed identities can be used at no extra cost. For Entra Agent ID, check the current licensing before approval.
  • Review time. Act with approval adds human time for every approved action. Class tools carefully so that only real writes need approval.
  • Spend limits. The limits in the envelope come from the cost pack. Check the current price before approval.

10. AWS and open-source equivalents

Platform Equivalent Key differences
AWS: Amazon Bedrock AgentCore Policy in AgentCore Policy engines are associated with an AgentCore Gateway. Every agent request to a tool is checked against the policies before the tool is called. Policies are written in Cedar. The enforcement sits outside the agent's code.
AWS: IAM One IAM role per agent, with the minimum actions Check the AWS IAM least-privilege guidance.
AWS: Guardrails for Amazon Bedrock Content and prompt-attack filters on inputs and model responses These filter content. They do not replace the allow-list. ApplyGuardrail can evaluate text without calling a model.
Open source: Open Policy Agent or Cedar A policy engine in front of tool calls Tool calls are sent to the engine and checked against the policy. The policy is separate from the agent framework.

11. Validation record

Pending. Filled in by the dry-runner (see docs/validation-protocol.md).

Sandbox scenario: a second engineer writes an envelope for the sandbox agent using only this guide.

Pass criteria: every tool is classified; the identity holds no role broader than resource group scope; the review maps at least the relevant OWASP agentic risks.

Record

Item Detail
Playbook PB-AGT-08-01 at commit [hash]
Dry-run by [Name] (must not be author or reviewer)
Date YYYY-MM-DD
Sandbox [Resource group or tag, tier and region]
Scenario [Scenario followed]
Time taken [Hands-on time] hands-on, [waiting time] waiting
Result [PASS / PASS WITH NOTES / FAIL]
Notes 1. [Step number: defect or explanation; blocking/non-blocking; fixed/logged]
Signed off by [Reviewer name and date]

12. Sources

Checked on 10 November 2026.

  • PB-AGT-08-02: Enforce action allow-lists and approval gates in agent code (enforces this envelope).
  • PB-AGT-08-03: Change an agent's permissions safely.
  • PB-AGT-08-04: Respond to an agent acting outside its permission envelope.
  • PB-AGT-08-05: Agent governance go-live review checklist.
  • PB-AGT-11-01: Enforce per-run, per-user and per-tenant budgets (the spend limits).
  • PB-AGT-11-04: Set budget ceilings and choose what happens at the limit.