For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to page URLs.
Skip to content

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 apply to standard agents only. Orchestrated agents manage tools within their workflow implementations.

Tool permissions are configured in the Governance tab of the agent workspace, alongside guardrails.

The agent Governance tab showing tool permission configuration

Permission System Overview

The permission system operates at three levels:

  1. Tool Scope Permissions - Grant access to all tools within specific scopes (for example, "content-read", "navigation")

  2. Explicit Tool Permissions - Grant access to individual tools by their ID

  3. User Group Overrides - Add or remove tools per user group (additive and subtractive)

A tool is allowed if it appears in the agent's explicit tool list OR if its scope is in the agent's allowed scopes list, and it is not denied by a user group override. System tools are always allowed and cannot be denied.

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:

Scope ID
Icon
Destructive
Description

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-read scope

  • Execute the get_umbraco_media_item tool 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-write scope for editors in addition to the base permissions

  • Administrators - 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:

  1. Base Permissions - The agent's AllowedToolScopeIds and AllowedToolIds define the default allowed tools for everyone.

  2. User Group Allow - AllowedToolIds and AllowedToolScopeIds from the user group override are added to the base permissions.

  3. User Group Deny - DeniedToolIds and DeniedToolScopeIds from the user group override subtract from the combined set. Deny rules take precedence over allow rules.

  4. System Tools - System tools are always included and cannot be denied.

  5. 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.

UserGroupPermissions is an IReadOnlyDictionary<Guid, AIAgentUserGroupPermissions> keyed by user group ID. The user group ID is the dictionary key, not a property on AIAgentUserGroupPermissions.

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:

Property
Type
Description

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

Property
Type
Description

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

  1. Principle of Least Privilege - Only grant the minimum permissions needed.

  2. Review Destructive Scopes - Carefully consider before granting content-write, media-write, etc.

  3. Use Deny Rules for Safety - Use DeniedToolIds/DeniedToolScopeIds to subtract risky tools from specific user groups even when broader scopes are granted.

  4. Test with Different User Groups - Verify overrides behave as expected for each role.

  5. Document Agent Permissions - Clearly document why permissions are granted.

  6. 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.

Last updated

Was this helpful?