Agent Restrictions

This page covers the admin configuration side of agent access control. For how the permission model works conceptually, see Agent Access Control.

The 4-tier hierarchy

Platform
Superadmin · Applies to all organizations
↓ inherits down
Organization
Org Admin · Applies to all org members
↓ inherits down
Group
Org Admin · Applies to group members
↓ overrides above
User Override
Org Admin · Applies to one specific user

Each tier stores two things per agent: - agent_status — allow, deny, or inherit - tool_settings — Per-tool overrides (same allow/deny/inherit values)

Platform settings

Who: Superadmin only

Platform settings are the system-wide baseline. Use these to disable agents globally (e.g., during maintenance or before an agent is fully tested).

PLATFORM AGENT SETTINGS
web_research
allow
data_router
allow
experimental_agent
deny

Platform settings list all registered agents. Setting an agent to "deny" at platform level blocks it for every user in every organization unless a lower tier explicitly overrides it.

Organization settings

Who: Org admin (own org) or superadmin (any org)

Organization settings show the platform context alongside editable org-level controls. This lets admins see what they're inheriting before deciding to override.

The admin panel shows both the inherited platform value and the org-level setting so admins understand the full picture.

Group settings

Who: Org admin (own org) or superadmin (any org)

Group settings show the platform and org context alongside the editable group controls. Admins select a group, then configure which agents its members can access.

User overrides

Who: Org admin (own org) or superadmin (any org)

User overrides are the most specific tier. Admins can search for a user, view all four tiers of their effective permissions, and set per-user overrides.

Example: Can Alice use data_router?
User Override: allow
✓ Most specific — this wins
Group (Marketing): deny
Overridden by user level
Organization: inherit
Overridden by user level
Platform: allow
Overridden by user level

The admin can also list all users who have overrides, making it easy to audit exceptions.

Settings schema

Each agent setting at any tier contains:

Field Type Description
agent_status allow / deny / inherit Whether the agent is enabled at this tier
tool_settings JSON object Per-tool overrides: {"tool_name": {"status": "allow"}}
allow deny inherit

When agent_status is "inherit", the system defers to the next higher tier. When no tier has an explicit value, the default is allowed.

Practical admin scenarios

Goal Where to configure
Disable an agent system-wide Platform: set agent to deny
Restrict data agents to one org Org: deny in all orgs, allow in the one that needs it
Give analytics team data access Group: allow data agents for the analytics group
One user needs an exception User Override: allow the agent for that specific user
Block a specific tool, not the whole agent Any tier: set agent to allow, then deny the individual tool in tool_settings

Audit trail

All agent settings changes are logged:

Action When
PLATFORM_AGENT_SETTINGS_UPDATED Superadmin changes platform-level agent settings
ORG_AGENT_SETTINGS_UPDATED Admin changes org-level agent settings
GROUP_AGENT_SETTINGS_UPDATED Admin changes group-level agent settings
USER_AGENT_SETTINGS_UPDATED Admin changes user override settings
USER_AGENT_OVERRIDE_UPDATED User changes their own tool preferences

See Audit Logs for querying and exporting these events.