Control risk levels, blocked actions, approval workflows, rate limits, constraints, and organization policies — the full security profile for this agent.
Permissions define the boundaries of what your agent is allowed to do. They answer questions like: Can this agent send emails without approval? How many actions can it perform per hour? Is it allowed to delete data or run code?
There are three ways to set permissions:
Organization-wide policies also apply automatically and are shown at the bottom of this page.
The permission system uses several endpoints:
GET /policies/agent/:id?orgId=… — Fetch applicable org policiesGET /profiles/presets — List available preset profilesGET /souls/by-category — List role templates grouped by category with metadataPOST /profiles/:id/apply-preset — Apply a named preset to the agentPUT /profiles/:id — Save a custom permission profileRole templates also update agent config (identity, personality, description) via hot-update or config patch, and optionally apply a suggested permission preset. The profile object contains: maxRiskLevel, blockedSideEffects, sandboxMode, requireApproval, rateLimits, and constraints.
PUT /profiles/:id and take effect on the next agent action.Role templates are pre-configured agent personas that bundle together:
Templates are organized by category (e.g., "Customer Facing," "Internal Operations," "Creative"). Each category has metadata including an icon and display name. Applying a template:
config.identity (role, personality, description) via hot-update or config patchsuggestedPreset, applies that permission preset as wellThe template gallery supports search (by name, description, and tags) and can be collapsed/expanded.
Presets are quick permission profiles that replace the entire current profile. They configure risk levels, blocked actions, rate limits, and approval requirements in one click. The currently active preset is highlighted with a checkmark and accent border.
Common presets:
Defines the highest risk tier of tools the agent can use. Four levels:
Tools above the maximum risk level are blocked entirely, regardless of other settings.
Side effects are categories of real-world impact. You can block specific types entirely:
sends-email — Sending outbound emailssends-message — Sending chat messagessends-sms — Sending text messagesposts-social — Publishing to social mediaruns-code — Executing shell commands or scriptsmodifies-files — Creating, editing, or moving filesdeletes-data — Permanently removing datacontrols-device — Interacting with hardware or IoT devicesfinancial — Making purchases or financial transactionsBlocked side effects are shown as red badges. Any tool that produces a blocked side effect will be denied.
When enabled, the agent must get human approval before performing certain actions. You configure:
Rate limits prevent runaway behavior and control costs. Four configurable limits:
When a limit is reached, subsequent tool calls are denied until the window resets. Set to 0 for unlimited (not recommended for production).
Operational limits that govern the agent's resources:
The permission profile can include explicit tool-level overrides:
This section only appears when overrides are configured.
Organization-level policies that apply to this agent. Policies are rules defined at the org level — they're not per-agent but apply to agents based on scope. The table shows:
Pick the preset closest to your needs (usually "Standard"), then use "Edit" to adjust specific settings. This avoids starting from a blank slate.
At minimum, require approval for sends-email and financial side effects. This prevents the agent from sending messages or spending money without human confirmation — especially important during initial deployment.
The defaults (30/min, 500/hr, 5000/day) work for most agents. Lower them for agents with external actions to prevent spam. Raise them for batch-processing agents that need high throughput.
When developing or testing a new agent, enable sandbox mode. The agent can read data and plan actions but can't execute anything with real-world impact. Disable it once you're confident in the agent's behavior.
Check the Applicable Policies table to understand what org-level rules affect this agent. Mandatory policies can block actions even if the agent's own profile allows them.
When creating a new agent, apply a role template first. It sets identity, personality, and permissions in one click — a much faster starting point than configuring everything manually.
Check in order: (1) Is the tool's category enabled in the Tools tab? (2) Is the tool's risk level within maxRiskLevel? (3) Is the side effect type blocked? (4) Is there a mandatory org policy blocking it? (5) Has a rate limit been hit?
The agent has no profile yet. Apply a role template, select a preset, or create a custom profile. Without a profile, the agent may use system defaults which vary by deployment.
Presets replace the entire profile. If you see stale values, refresh the page — the profile is re-fetched from the server. Also check the browser console for errors from POST /profiles/:id/apply-preset.
Not all role templates have a suggestedPreset. If the template doesn't include one, only the agent's identity (role, personality, description) is updated. Apply a permission preset separately if needed.
The default timeout is 30 minutes. If approvers consistently miss the window, increase the timeout in the approval settings. Also consider reducing which actions require approval to only the most critical ones.
Policies are managed at the organization level, not per-agent. If a policy appears disabled here, it was disabled org-wide. Contact your organization admin to re-enable it.
When an agent belongs to a client organization, permissions are governed by that organization's policies: