Skip to content

05.Sub-Agent Configuration.md

Latest commit

 

History

History
360 lines (239 loc) · 15 KB

05.Sub-Agent Configuration.md

File metadata and controls

360 lines (239 loc) · 15 KB

Snow CLI User Guide - Sub-Agent Configuration

Welcome to Snow CLI! Agentic coding in your terminal.

What are Sub-Agents

Sub-agents are branches of the main workflow in Snow CLI, designed to handle specific individual tasks to save context usage in the main workflow.

Three Built-in System Sub-Agents

  • Explore Agent - An exploration agent for searching code functionality for the main workflow, focusing on locating code positions.

  • Plan Agent - A planning agent for developing comprehensive coding plans and guidance for the main workflow.

  • General Purpose Agent - A general-purpose agent that provides common coding functionality for the main workflow, suitable for completing tasks that are singular but involve many files (e.g., internationalization).

Sub-Agent Workflow

graph TB
Start([User Initiates Task]) --> MainProcess[Main Workflow Main Agent]

MainProcess --> Check{Does it need<br/>a sub-agent?}

Check -->|No| DirectHandle[Main workflow handles directly]
DirectHandle --> End([Return Result])

Check -->|Yes| SelectAgent{Select sub-agent type}

SelectAgent -->|Code exploration| ExploreAgent[Explore Agent<br/>Exploration Agent]
SelectAgent -->|Make plan| PlanAgent[Plan Agent<br/>Planning Agent]
SelectAgent -->|General coding| GeneralAgent[General Purpose Agent<br/>General-Purpose Agent]

ExploreAgent --> SendTask[Main workflow sends task prompt]
PlanAgent --> SendTask
GeneralAgent --> SendTask

SendTask --> SubProcess[Sub-agent receives task]

SubProcess --> Isolate[Independent context environment<br/>Isolated from main workflow]

Isolate --> SpecializedWork{Specialized direction processing}

SpecializedWork -->|Explore agent| SearchCode[Search code positions<br/>Analyze code structure]
SpecializedWork -->|Plan agent| MakePlan[Develop coding plan<br/>Provide guidance]
SpecializedWork -->|General agent| GeneralWork[Execute general coding<br/>Process batch files]

SearchCode --> Complete[Processing complete]
MakePlan --> Complete
GeneralWork --> Complete

Complete --> Return[Send results back to main workflow]

Return --> MainReceive[Main workflow receives results]

MainReceive --> End

style MainProcess fill:#e1f5ff
style ExploreAgent fill:#fff4e1
style PlanAgent fill:#ffe1f5
style GeneralAgent fill:#e1ffe1
style Isolate fill:#ffe1e1
style SubProcess fill:#f0f0f0
style Return fill:#e1ffe1
Loading

Workflow Description

  1. Main Workflow Assessment: After receiving a user task, the main workflow first evaluates whether a sub-agent is needed.

  2. Sub-Agent Selection: Select an appropriate sub-agent based on the task type:

    • Explore Agent: Deep code exploration (5+ files), complex dependency tracing
    • Plan Agent: Breaking down complex features, major refactoring planning
    • General Purpose Agent: Batch modifications (5+ files), systematic refactoring

  3. Task Dispatch: The main workflow sends a task prompt containing complete context to the sub-agent.

  4. Independent Processing: The sub-agent processes the task in an independent context environment, completely isolated from the main workflow.

  5. Specialized Processing: Each sub-agent performs targeted processing according to its specialized direction.

  6. Return Results: After processing is complete, the sub-agent sends the results back to the main workflow.

  7. Main Workflow Continues: The main workflow receives the results and continues with subsequent work.

Key Features

  • Context Isolation: Sub-agents have independent context that does not affect the main workflow's conversation history.
  • One-Way Communication: Main workflow → Send task → Sub-agent → Return results → Main workflow
  • Specialized Division of Labor: Each sub-agent focuses on a specific domain, improving processing efficiency.
  • Resource Conservation: Prevents the main workflow context from being occupied by extensive exploration or planning information.

Sub-Agent Configuration Management

Adding a Sub-Agent

You can create custom sub-agents through the configuration interface to meet specific business needs.

Operation Steps

  1. Enter Configuration Interface

    • Select "Sub-Agent Configuration" in the main menu
    • Select "Add Sub-Agent"

  2. Basic Information Configuration

    Fill in the following fields as prompted by the interface:

    • Agent Name (Required)

      • Enter the name of the sub-agent
      • Suggest using descriptive names like "Code Review Agent", "Testing Agent", etc.
      • Press Enter to confirm and move to the next field

    • Description (Required)

      • Enter the function description of the sub-agent
      • Describe in detail the purpose and application scenarios of this sub-agent
      • Role Definition (Required)
      • Define the role and behavioral norms of the sub-agent
      • This is the sub-agent's own role instructions. At runtime it is appended to the prompt sent to the sub-agent.
      • Example: 
        You are a professional code review assistant.
Your responsibilities are:
1. Check code quality and compliance
2. Discover potential bugs and security issues
3. Provide improvement suggestions and best practices
      • Press Enter to confirm and move to the next field

  3. Advanced Configuration Options

    Important Reminder: Sub-agents no longer select System Prompt or Custom Request Headers separately. Both are taken from the selected Configuration Profile (Profile), because the profile already contains these settings.

    • Configuration Profile (Optional)

      • Specify a dedicated API configuration profile for the sub-agent

      • Purpose: Allow the sub-agent to use different API endpoints, different models, and the system prompt + request headers defined in that profile

      • Operation:

        • Use ↑/↓ arrow keys to browse available profiles
        • Press Space to select/deselect
        • Use ←/→ arrow keys to quickly switch between configuration options
        • Marker description: ❯ indicates cursor position, [✓] indicates selected

      • Application scenarios:

        • Let the sub-agent use more powerful models

        • Let the sub-agent use different API providers

        • Allocate different billing accounts for different sub-agents

        • Bind different system prompts/request headers via different profiles

        • Set different request priorities

  4. Tool Permission Configuration

    Select the tools that the sub-agent can use:

    • Use ↑/↓ arrow keys to navigate between tool categories
    • Use ←/→ arrow keys to switch between tool categories
    • Press Space to select/deselect tools
    • Tool categories include:
      • Filesystem tools (filesystem-read, filesystem-create, filesystem-edit, etc.)
      • ACE code search tools (ace-find_definition, ace-semantic_search, etc.)
      • Codebase tools (codebase-search)
      • Terminal tools (terminal-execute)
      • TODO management tools
      • Web search tools
      • MCP tools (if configured)

    Suggestion: Only grant the minimum set of permissions needed for the sub-agent to complete its tasks.

  5. Save Configuration

    • Press Ctrl+S to save the configuration
    • The system will automatically validate the configuration's completeness
    • Return to the main menu after successful save

Configuration Inheritance Explanation

When creating a new sub-agent, if no Configuration Profile (Profile) is specified, the sub-agent will follow the currently active profile of the main workflow. This means:

  • The sub-agent will use the same API configuration and model as the main workflow
  • The sub-agent will use the system prompt and request headers defined in that profile (and then apply its own role definition on top)

Editing a Sub-Agent

You can edit existing sub-agent configurations, including the three built-in system agents.

Operation Steps

  1. Enter Edit Interface

    • Select "Sub-Agent Configuration" in the main menu
    • Select the sub-agent to edit

  2. Edit Restrictions Explanation

    System Built-in Agents (Explore Agent, Plan Agent, General Purpose Agent):

    • Name, description, and role definition are read-only and cannot be modified
    • The interface will display "(System Built-in - Not Modifiable)" prompt
    • Can modify: Tool permissions, configuration profile

    Custom Agents:

    • All fields can be modified

  3. Modify Configuration

    Navigation and operation methods are the same as adding an agent:

    • Use ↑/↓ arrow keys to navigate between fields
    • Use ←/→ arrow keys to switch between configuration options
    • Press Space to select/deselect
    • Directly input modification content in text fields

  4. Save Changes

    • Press Ctrl+S to save changes
    • The system will validate the modified configuration
    • Return to the main menu after successful save

Edit Configuration Inheritance Explanation

When editing an existing sub-agent:

  • If the sub-agent already has custom configurations, the interface will display and load these configurations
  • If the sub-agent does not have custom configurations:
    • When editing a copy of a system built-in agent, it will automatically inherit the current main workflow's configuration as default values
    • When editing an existing custom agent, configurations will not be automatically filled (remain unselected)

Configuration Best Practices

  1. Clear Role Definition

    • Clearly describe the scope of responsibilities of the sub-agent
    • Provide specific work steps or checklists
    • Specify output format and quality standards

  2. Reasonable Tool Permission Allocation

    • Follow the principle of least privilege
    • Read-only tasks do not grant write tools
    • Exploration tasks do not grant execution tools

  3. Good Use of Configuration Isolation

    • Configure different sub-agents for different types of tasks
    • Use different configuration profiles (Profile) to control cost and model selection
    • Use different configuration profiles (Profile) to bind different system prompts and request headers

  4. Test Configuration Effects

    • Perform small-scale testing after creation
    • Observe whether the sub-agent's behavior meets expectations
    • Adjust role definition and tool permissions based on actual effects

Keyboard Shortcuts

  • ↑/↓: Navigate between options or scroll lists
  • ←/→: Switch between fields (configuration options, tool categories)
  • Space: Select/deselect (tools, configuration options)
  • Enter: Confirm input and move to next field
  • Ctrl+S: Save configuration
  • Ctrl+C or ESC: Cancel and return

Quick Sub-Agent Selection

In addition to using the /agent- command to open the sub-agent selection panel, you can also use the # symbol in the input box to quickly trigger the sub-agent picker:

How to Use

  1. Trigger the picker: Type # in the input box to automatically pop up the sub-agent selection panel
  2. Search and filter: Type #keyword to filter sub-agents by ID, name, or description
  3. Select sub-agent: Use arrow keys to select a sub-agent, press Enter to confirm. The system will automatically insert #subAgentID into the input box

Examples

#explore     → Select explore sub-agent
#plan        → Select plan sub-agent
#general     → Select general sub-agent

Notes

  • The # symbol must not be preceded by @ (e.g., @# or @@# will not trigger the sub-agent picker, but the file picker)
  • If you type a space or newline after #, the picker will automatically close
  • Press ESC to close the sub-agent selection panel

Sending Messages to Running Sub-Agents

When a sub-agent is running, you can use the >> command to send messages to specific running sub-agents, enabling real-time interaction with the main workflow.

How to Use

  1. Trigger the picker: Type >> at the beginning of the input box (leading whitespace is allowed) to pop up the list of currently running sub-agents
  2. Select sub-agents:
    • Use ↑/↓ arrow keys to navigate
    • Use Space to select/deselect sub-agents (supports multi-select)
    • If no sub-agent is explicitly selected, the currently highlighted item will be auto-selected when you press Enter
  3. Send message: Press Enter to confirm selection, then type your message and send

Visual Tag Explanation

After selecting sub-agents, a visual tag will appear in the input box:

[»Explore Agent#abcd: Investigating project architecture...] Please continue analyzing
  • » symbol (U+00BB): Used to avoid re-triggering the picker
  • Explore Agent: Sub-agent name
  • #abcd: Last 4 characters of instance ID (ensures uniqueness)
  • Investigating project architecture...: Short summary of the task prompt

Message Routing Mechanism

The actual sent message contains a special marker:

# SubAgentTarget:instanceId:agentName
Your message content

The system routes the message to the corresponding sub-agent based on these markers.

Use Cases

  • Follow-up details: Ask about a specific function implementation while the sub-agent is exploring code
  • Correct direction: Send correction information when you notice the sub-agent misunderstood
  • Add context: Inform the working sub-agent of important information you just remembered
  • Batch instructions: Send the same instruction to multiple running sub-agents simultaneously

Notes

  • >> must appear at the beginning of the input box (leading whitespace is ignored) to trigger
  • If a sub-agent has completed or exited, it will not appear in the selection list
  • Press ESC to close the selection panel
  • The selection panel will auto-close when you delete >>

Common Questions

Q: Can sub-agents use the context of the main workflow?

A: No. Sub-agents are completely isolated from the main workflow's context. The main workflow needs to provide all necessary context information in the prompt when calling a sub-agent.

Q: How can I make a sub-agent use a more powerful model? A: In the configuration profile (Profile) option, select a profile that uses a more powerful model for the sub-agent.

Q: What is the difference between the system prompt in a profile and a sub-agent's role definition?

A: The role definition is the sub-agent's own behavioral specification (entered/edited in the sub-agent config). The system prompt in a configuration profile (Profile) is a profile-level constraint that affects both the main workflow and any sub-agent that uses that profile. At runtime, the sub-agent uses the profile's system prompt as the base, then applies the sub-agent's role definition on top.

Q: Will editing a system built-in agent affect the original configuration? A: No. The core definitions (name, description, role) of system built-in agents are read-only. You can only modify their tool permissions and configuration profile (Profile), and these modifications only affect your usage without changing the system presets.

Q: How do I delete a custom sub-agent?

A: Select the sub-agent to delete in the sub-agent list, press the Delete key or select the delete option. System built-in agents cannot be deleted.