Scope agent permissions
Set guardrails on what an agent is allowed to do.
Advanced · ~10 min · Prerequisites: an agent with tools
Building and editing agents is admin-only. Members can run and observe agents, but only admins can create or change them.
What you'll do
Review the tools and actions your agent has access to, remove anything the role doesn't require, and gate sensitive actions behind approvals — so members can trust what the agent will and won't do.
Why scoping matters
An agent's permissions are the set of tools it can call and actions it can take. The broader that set, the harder it is to predict behavior, audit what happened, and contain mistakes. Least privilege applies here just as it does in any access-control system: give the agent exactly what it needs to do its job, and nothing more. See Permissions for the full model.
Limit tools to the role
Open /admin/agents/<slug>/edit and go to the Tools section. Look at every tool in the active list and ask: does this agent's role actually require this action?
- A Research Analyst agent needs read tools — search, fetch document, summarize. It doesn't need create, delete, or send.
- A Support Triage agent needs to read tickets and update statuses. It doesn't need to access your CRM's billing fields or send emails on behalf of users.
Remove any tool that doesn't map directly to the role. You can always add more tools and publish a new version later.
Gate sensitive actions
Some actions carry real consequences — sending an email, creating a calendar event on someone else's behalf, deleting a record, or posting to a public channel. For these:
- Add an approval step in the tool configuration if the tool supports it. The agent proposes the action; a member confirms before it runs.
- Write an explicit rule in the instructions that tells the agent when it must pause and check with the user before taking an action, rather than proceeding autonomously.
Approvals add a small friction step, but they're the right default for anything irreversible or externally visible. Members learn to trust an agent that asks before it acts on their behalf.
If you're unsure whether an action needs gating, treat external writes (email, Slack, GitHub) and anything that touches billing or identity as sensitive by default.
Review before publishing
Before you publish, do a final review pass:
- Open the Tools section and read the active tool list end to end.
- For each tool, confirm the role justifies it and the scope is as narrow as possible.
- Check your instructions for any language that might encourage the agent to act without confirmation on sensitive tasks.
- Run one more test in the test panel focused specifically on the edge cases — what happens if a member asks the agent to do something outside its defined role?
A clean permissions review now prevents the harder conversation after a member is surprised by something the agent did. Once you're satisfied, head to Give your agent knowledge to ground it in your team's content, or go straight to Test before you publish for a full pre-publish validation pass.