Manage permissions for Retool Agents
Learn how to manage permissions and access for Retool Agents.
| Agents Availability | |||
|---|---|---|---|
| Cloud | Public beta | ||
| Self-hosted Edge 3.234 or later | Public beta | ||
| Self-hosted Stable 3.253 or later | Public beta | ||
There are three objects that are relevant from a permissions standpoint: the agent, the tool, and the resource.
- Agents have Use, Edit, or Own permissions.
- Resources have Use, Edit, or Own permissions.
- Tools are not independently permissioned, they are implicitly permissioned based on the agent that contains the tools.
To use an app that calls an agent, you also need to have Use permissions on the app.
Folder permissions
For a user group to see all of the agents in an organization from their All agents page, an admin must grant them Edit all or Own all access for agents.
- Navigate to Settings > Permissions.
- Select a permission group.
- Select the Agents tab.
- Choose Edit all.
Before a user can create and edit agents, an admin must configure their permission group so that they have either Edit or Own permissions on an agent folder.
- Edit permissions on an agent folder allow users to create new agents within the folder, view and edit the configuration of agents in the folder that they have edit access to, and use agents they have edit access to in creator mode.
- Own permissions on an agent folder allow users to do everything they can do with Edit permissions, as well as move, delete, or rename agents within the folder.
Permissions are not necessarily inherited to the agents within folders. Admins can choose to provide user groups with Edit permissions on a folder, and restrict access to an individual agent within a folder.
Individual agent permissions
An agent is permissioned like an app or workflow. Refer to Permissions for Apps for more information about permissions within apps.
- Use permission for an agent will allow a user to view it from
/agents, and access only the Chat tab. - Edit permissions allow a user to view and edit the configuration of an agent, and use the agent in creator mode.
You can only edit the configuration of an agent if you have the necessary permissions to all tools used by the agent (e.g., Use for workflows, Edit for resources and MCP).
- Own permissions allow a user to edit an agent’s configuration, including moving or deleting the agent.
Permission groups
Agents are available in the /settings/permissions/group/{group_id}/group-name page as a top-level, permissionable object.
You can define access for agents at a group-level in Settings > Permissions.
A permission group may have Use, Edit, or Own permissions on an agent.
Use
A member of a permission group with Use access to an agent may:
- View the agent (including Name, Description, and version history).
- Access the chat tab of the agent on
/agents/{uuid}. - Create new chat threads and messages with the agent.
- Have tool calls executed on their behalf if they have Use permissions on the underlying resource(s) for the agent.
- If users don’t have the required permissions to a resource, Retool throws an error, which is passed back to the agent.
Edit
A member of a permission group with Edit access to an agent may:
- Build an agent.
- Edit an agent (all editable properties).
Own
A member of a permission group with Own access to an agent may:
- Build an agent.
- Move an agent.
- Edit an agent.
- Delete an agent.
- Rename an agent.
When interacting with an agent, a user is a member of a permission group for both the agent and the resource, and the following rules are observed.
| AGENT PERMISSION LEVEL | |||||
|---|---|---|---|---|---|
| RESOURCE PERMISSION LEVEL | NONE | USE | EDIT | OWN | |
| NONE | The user may not interact with this agent, and cannot call a tool on any resource. | The user can interact with the agent. If the agent calls a tool that the user lacks permission to use, an error is passed back as the output of the tool, and the model explains the error to the user. | The user can modify this agent’s configuration, but cannot create a tool that references a resource that they have no permission to use. | The user can modify this agent’s configuration, delete, and rename the agent, but cannot create a tool that references a resource that they have no permission to use. | |
| USE | The user may not interact with this agent, and cannot call a tool on any resource. | Can call tools. | The user can modify this agent and add and call a tool based on this resource. | The user can modify this agent and add and call a tool based on this resource. | |
| EDIT | The user may not interact with this agent, and cannot call a tool on any resource. | Can call tools. | The user can modify this agent and add and call a tool based on this resource. | The user can modify this agent and add and call a tool based on this resource. | |
| OWN | The user may not interact with this agent, and cannot call a tool on any resource. | Can call tools. | The user can modify this agent and add and call a tool based on this resource. | The user can modify this agent and add and call a tool based on this resource. | |
The visibility of certain tabs within Retool Agents is also limited based on permissions:
| Tabs | Use | Edit | Own |
|---|---|---|---|
| Chats | Access | Access | Access |
| Configuration | No access | Access | Access |
| Logs | No access | Access | Access |
| Evals | No access | Access | Access |
Admin capabilities
You must have Retool AI enabled for your organization to be able to use Retool Agents.
Retool Agents can be globally enabled or disabled for a given organization in Settings > Retool AI > AI Agents.
An admin of your Retool organization can enable Retool Agents in Settings > Retool AI > AI Agents.
Exercise extreme caution when disabling AI Agents Sharing, as it will immediately unpublish all currently shared threads from your organization. This is a security feature in place to prevent unauthorized public sharing of sensitive information. Toggling AI Agents Sharing back on will not restore sharing for any previously-created public threads.
To enable the Function Generator for automatic custom tool creation, toggle AI Agents Function Generation.
User consent handling
Consent is different from access control. Consent assumes that the agent has the permission level to execute the tool, but it is a validation step that the parameters passed into the tool are acceptable.
To require confirmation before an agent uses a tool, on the Edit Tool page, select the checkbox for Require user confirmation before use.
Check the box to Require user confirmation before use on the Edit Tool page.
When an agent is triggered via chat or from an app, tools requiring consent will prompt you for approval within the chat interface.
Tool requiring approval within the agent chat interface.
When an agent is called from a workflow, only tools that do not require consent will be accessible. Similarly, agents invoked by another agent will not be able to access tools that require consent, even if the parent agent was called via chat.