Skip to main content
Availabilitycli

About subagents

Subagents are custom agents that you can configure for specialized tasks, like code review or project bootstrapping. Each subagent has its own tools and capabilities that you can delegate specific tasks to. You can have local subagents or share them with your team by adding their configuration to your repository.
  • Subagents have their own context window independent from the main agent
  • Subagents have a custom prompt that is used to instruct the agent
  • Subagents run in parallel with other subagents
  • Subagents will show a summary of their current progress in the main thread

Create a subagent

You can create a new subagent through the wizard by running /agents command in interactive mode. Or you can create the configuration file manually.

Create a subagent with the wizard

  1. Run the /agents command in interactive mode
  2. Select “Create new agent”
  3. Select where you want the agent configuration to be stored
  4. Complete the following fields to configure the agent:
    • Name
    • Description
    • Color
    • Model
    • Prompt
  5. Review the configuration and press enter to save the agent

Create a subagent manually

You can create a subagent manually by creating a configuration file. The configuration file should be a markdown file stored in either ~/.augment/agents/ (user only) or ./.augment/agents/ (shared). See the Subagent configuration reference for more details. Example subagent configuration:

Running your subagent

Once you’ve configured the subagent, you can trigger it by sending a message that references the agent name. Augment will also automatically detect when a task is appropriate for a subagent and offer to use it.

Subagent configuration reference

File locations

Subagents are configured in markdown files with YAML frontmatter. Subagents can be configured at the user level or the workspace level. User-level subagents are available in all workspaces, while workspace-level subagents are only available in the current workspace.

Frontmatter configuration

Tool restrictions

You can control which tools a subagent has access to using either an allowlist or a denylist:
  • tools (allowlist): Only the listed tools will be available. Use this when you want to give the subagent a small, specific set of tools.
  • disabled_tools (denylist): All tools except the listed ones will be available. Use this when you want to remove a few tools from the full set.
Important notes:
  • If both tools and disabled_tools are specified, disabled_tools takes precedence and tools is ignored.
  • If neither is specified, the subagent has access to all tools (default behavior).
Tool restrictions are useful for:
  • Security: Preventing a subagent from modifying files or running commands
  • Focus: Giving a subagent only the tools it needs for its specific task
  • Safety: Preventing subagents from performing destructive operations
Common tool names:
  • view - View files and directories
  • codebase-retrieval - Search the codebase
  • str-replace-editor - Edit existing files
  • save-file - Create new files
  • remove-files - Delete files
  • launch-process - Run shell commands
  • github-api - Interact with GitHub
  • web-fetch - Fetch web content
  • web-search - Search the web
Example with YAML list format:
Example with comma-separated format:

Supported models

Subagents can use any model available in Auggie. To see a list of available models, run the following command:
This will display all supported models along with their identifiers that you can use in your subagent configuration.
Model availability may vary depending on your Augment subscription and organization settings.

Agent prompt

The agent prompt is the main body of the markdown file. The prompt is used to instruct the agent on its role and capabilities. The prompt can include any information that you want to be available to the agent, including specific tools or instructions. The prompt is rendered as markdown and supports code blocks, lists, and other formatting.

Best practices for subagents

  • Subagents are most effective when they have a specific and focused task. It is better to create multiple subagents for different tasks rather than trying to create a single agent for multi-step, long-running, or complex tasks.
  • Subagents should have a detailed prompt. The prompt should clearly define the agent’s role, capabilities, and expected behavior. Include specific instructions, task lists, examples, and expected output. Take advantage of markdown formatting to make the prompt as clear as possible.
  • Share your subagents with your team. Subagents are a great way to share custom workflows with your team. Store your subagents in your projects ./.augment/agents/ directory to make them available to everyone.

Example subagents

Code review agent

Read-only code reviewer (with tool restrictions)

This example shows how to create a code review agent that can examine code but cannot make modifications:

Test generation agent

API designer agent