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: an agent whose id is github/review-pull-requests/pr-reviewer files under a github/review-pull-requests 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
Foldered ids come from the platform, not the create dialog. The dialog's Name field takes a flat id — lowercase letters, numbers, hyphens, and underscores, no / — so an agent you create there lands unfiled at the top level. The folder prefix (chat/, github/review-pull-requests/) is reserved for agents the platform ships or installs: builtins arrive pre-filed, and installing an automation files its agents under the folder their id names. An id can't change later, so the folder is fixed when the agent is created. 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; automation-installed agents file under their automation's folder.
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.