Permissions
Configure tool permissions for agents using scopes, explicit tool lists, and user group overrides.
Agent tool permissions control which frontend tools a standard agent can execute. This system provides fine-grained security to ensure agents only access appropriate functionality.
Tool permissions are configured in the Governance tab of the agent workspace, alongside guardrails.

Permission System Overview
The permission system operates at three levels:
Tool Scope Permissions - Grant access to all tools within specific scopes (for example, "content-read", "navigation")
Explicit Tool Permissions - Grant access to individual tools by their ID
User Group Overrides - Add or remove tools per user group (additive and subtractive)
Tool Scopes
Tool scopes categorize frontend tools by their purpose and security requirements. Each tool can belong to a scope, allowing you to grant access to entire categories of operations at once.
Built-in Tool Scopes
Umbraco.AI provides built-in scopes for common tool categories:
content-read
icon-article
No
Read operations on content items
content-write
icon-article
Yes
Create, update, or delete content
media-read
icon-picture
No
Read operations on media items
media-write
icon-picture
Yes
Upload, update, or delete media
search
icon-search
No
Search content, media, and Umbraco resources
navigation
icon-navigation
No
Access current page info and context resources
web
icon-globe
No
Fetch external web pages and content
Configuring Scope Permissions
Scope permissions are defined on AIStandardAgentConfig (accessed via AIAgent.Config). They can be configured in the Governance tab of the agent workspace in the backoffice, or via code:
Explicit Tool Permissions
For fine-grained control, you can grant access to specific tools by their ID, regardless of their scope.
When to Use Explicit Permissions
Use explicit tool permissions when you need to:
Grant access to a single tool from a scope without enabling the entire scope
Create custom combinations of tools for specialized agents
Supplement scope-based permissions with individual tools
Configuring Explicit Tool Permissions
Explicit tool permissions can be configured in the Governance tab of the agent workspace in the backoffice, or via code:
Combining Scopes and Explicit Permissions
An agent can use both scope-based and explicit permissions together. A tool is allowed if either condition is met:
In this example, the agent can:
Execute all tools in the
content-readscopeExecute the
get_umbraco_media_itemtool specifically
User Group Permission Overrides
User group overrides allow you to customize an agent's tool permissions for specific user groups. This is useful when different teams need different levels of access.
Use Cases
Content Editors - Allow
content-writescope for editors in addition to the base permissionsAdministrators - Grant broader access to admin users while restricting others via deny rules
Department-Specific - Customize tools based on organizational structure
How Overrides Work
User group overrides are additive and subtractive, not replacement:
Base Permissions - The agent's
AllowedToolScopeIdsandAllowedToolIdsdefine the default allowed tools for everyone.User Group Allow -
AllowedToolIdsandAllowedToolScopeIdsfrom the user group override are added to the base permissions.User Group Deny -
DeniedToolIdsandDeniedToolScopeIdsfrom the user group override subtract from the combined set. Deny rules take precedence over allow rules.System Tools - System tools are always included and cannot be denied.
Multiple Groups - When a user belongs to multiple groups, allow lists from all matching groups are combined, and deny lists from all matching groups are combined.
Configuring User Group Overrides
User group overrides can be configured in the Governance tab of the agent workspace in the backoffice, or via code:
User Group Permission Properties
The AIAgentUserGroupPermissions model has four collections:
AllowedToolIds
IReadOnlyList<string>
Tool IDs added to the allowed set for this user group.
AllowedToolScopeIds
IReadOnlyList<string>
Tool scope IDs added to the allowed set for this user group.
DeniedToolIds
IReadOnlyList<string>
Tool IDs removed from the allowed set. Takes precedence over allow rules.
DeniedToolScopeIds
IReadOnlyList<string>
Tool scope IDs removed from the allowed set. Takes precedence over allow rules.
Permission Resolution Flow
When a user runs an agent, permissions are resolved in this order:
Frontend Tool Metadata
Frontend tools define their scope and destructiveness using the ManifestUaiAgentTool interface:
Tool Metadata Properties
scope
string?
Tool scope ID for permission grouping (for example, "content-write")
isDestructive
boolean
Whether tool performs destructive operations (create/update/delete)
This metadata flows from frontend to backend for permission filtering:
Checking Permissions Programmatically
IAIAgentService exposes two methods for inspecting the resolved permissions for an agent.
Check if a Tool is Allowed
Get All Allowed Tools
Permission Filtering at Runtime
When an agent runs, IAIAgentService.StreamAgentAsync and related methods automatically filter frontend tools based on the resolved permissions -- a tool is included only if its ID is in the resolved allowed list. Unpermitted tools are silently excluded.
Security Considerations
Best Practices
Principle of Least Privilege - Only grant the minimum permissions needed.
Review Destructive Scopes - Carefully consider before granting
content-write,media-write, etc.Use Deny Rules for Safety - Use
DeniedToolIds/DeniedToolScopeIdsto subtract risky tools from specific user groups even when broader scopes are granted.Test with Different User Groups - Verify overrides behave as expected for each role.
Document Agent Permissions - Clearly document why permissions are granted.
Audit Permission Changes - Track changes to agent permissions over time.
Avoid granting all scopes by default -- instead, grant only the specific scopes each agent needs. Use user group overrides to provide role-based access rather than giving broad permissions to all users.
Related
Agent Surfaces - Categorizing agents by surface (different from tool scopes)
Frontend Tools - Creating custom frontend tools
Getting Started - Agent setup guide
API Reference - IAIAgentService methods
Last updated
Was this helpful?