Agent folders
How agents are grouped — folders derived from the agent's id, how automation-installed agents file themselves, and where the permission boundary actually lives.
2 min read
Agents are grouped by folders, and a folder comes from the agent's id: name an agent marketing/seo-writer and it files under a marketing folder wherever agents are listed. Folders are an organisational sorting tool, not a permission boundary — who can use an agent is the Access section on its General page, unchanged by where it is filed.
File an agent into a folder
The folder is set where the agent's id is set: the Name field in the create dialog. The id must be lowercase letters, numbers, hyphens, and underscores, with a / separating the folder from the agent — and it can't change later, so pick the folder when you create the agent. The display name is independent; rename the agent freely without moving it.
In the Agents list, folders render as collapsed rows with an agent count — click one to expand it, and the breadcrumb tracks where you are. The builtin agents ship pre-filed: the general assistants under chat, the GitHub agents under github.
Agents that arrive with an automation
Installing an automation files its agents like any others — the PR Creator and PR Reviewer from the Resolve GitHub issues bundle land in the same list, in the folder their id names. There is no separate agent store to browse: the Automations catalog is where bundled agents come from, and the list is where they live afterwards.
When to reach for it
| Use folders when… | Use team access when… |
|---|---|
| The agents list is getting long and needs order | An agent must only be usable by one team |
| Departments each own a set of agents | You are drawing a permission boundary, not a directory |
Where this fits
Folders are the lightest available grouping for agents — they sort the list and the catalog, nothing more. Larger separations live elsewhere: Project agents scope an agent to a Project, and Policies and limits govern what any agent may spend or do.