Subagents
A subagent is a named, reusable helper the Polygent Code agent can delegate a self-contained task to — research a question, implement a focused change, or sweep across many files — without cluttering its own context. The agent invokes one through its Agent tool by passing a subagent_type; Polygent applies that subagent's stored prompt, tools, MCP servers, and model to a fresh nested session and returns its conclusion.
Subagents only apply to the Polygent Code provider (its in-process harness is the one with an Agent tool). They live under Dev Tools → Subagents.
Built-in subagents
Two subagents ship out of the box and are available in every Polygent Code session — whether you start a regular session or chat with a bot:
| Subagent | Tools | Use for |
|---|---|---|
general | Full toolset (read, write, run) | Any delegated task — research, implement, or verify |
explorer | Read, Glob, Grep | Read-only fan-out search across many files; returns the conclusion |
Built-ins are always-on and cannot be deleted. Their name, description, system prompt, and allowed tools are fixed — but you can still edit their model, MCP servers, and Polygent MCP tools to tune them to your codebase.
Creating a custom subagent
Dev Tools → Subagents → Create Subagent.
| Setting | Description |
|---|---|
| Name | The value the agent passes as subagent_type (uniqueness checked) |
| Description | Advertised to the agent so it knows when to pick this subagent |
| System Prompt | Instructions applied to the spawned subagent session |
| Model | A Polygent Code model, or Inherit from parent to reuse the calling session's model |
| Allowed Tools | Which built-in tools the subagent may use; empty = the harness default |
| MCP Servers | Registered MCP servers forwarded into the subagent's session |
| Polygent MCP Tools | Restrict which built-in Polygent MCP tools (e.g. write_plan, create_ticket) the subagent may call; empty = all |
| Enabled | Toggle a custom subagent on/off without deleting (built-ins are always-on — no toggle) |
The Agent tool itself is always excluded from a subagent, so subagents can never spawn further subagents.
Polygent MCP tools
Subagents that inherit the harness default tool set (leave Allowed Tools empty) get Polygent's built-in MCP tools (write_plan, create_ticket, the memory tools, etc.) automatically. Use the Polygent MCP Tools picker to restrict such a subagent to a named subset — for example, give a "planner" subagent only write_plan, or leave the picker empty to allow all. This works exactly like the same picker on bots.
If you instead set an explicit Allowed Tools list, the subagent gets exactly those tools and no Polygent MCP tools — the built-in explorer (Read, Glob, Grep) is intentionally configured this way for pure read-only searching.
Exposing subagents to a bot
A Polygent Code bot can offer custom subagents to its conversations. In the bot form (Polygent Code only), a Subagents picker lists your custom subagents — select the ones that bot's sessions should be able to delegate to. The two built-ins (general, explorer) are always available and don't need to be selected.
How the agent uses them
When a Polygent Code session starts, Polygent injects an <available-subagents> list (each name + description) so the model knows which subagents it can call. The model then delegates with the Agent tool, e.g. Agent(subagent_type: "explorer", description: "find auth flow", prompt: "Locate where login is handled and report the files."). The subagent runs in the same workspace worktree, does its work, and returns a single summary that becomes the Agent tool's result — the parent agent keeps the conclusion, not the intermediate file dumps.
You can override a subagent's model or tools for a single call by also passing model / tool_allowlist to the Agent tool; explicit per-call values win over the subagent's stored configuration.
Permissions
| Permission | Capability |
|---|---|
subagents.view | See the Subagents page |
subagents.manage | Create / edit / delete subagents |
Subagents vs. bots
A bot is a persistent persona a user chats with. A subagent is a helper the agent delegates to mid-task. They're complementary: a bot defines who you talk to; subagents define who that agent can hand focused work off to.