Manage permissions for Retool Agents
Learn how to manage permissions and access for Retool Agents.
| Retool Agents Availability | |||
|---|---|---|---|
| Cloud-hosted | Public beta | ||
| Self-hosted (3.259 Edge) | Public beta | ||
| Self-hosted (Stable) | Not currently available | ||
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.
Agent permissions
An agent is permissioned like an app or workflow. Refer to the Configure permission controls guide for more information about permissions within apps or workflows.
- 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 create new agents, 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.
To use an app that calls an agent, you also need to have Use permissions on the app. But to call the agent from the app, only Use permissions on the agent are necessary.
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.