Subagents

Note: The former Spring Boot example module agentscope-examples/multiagent-patterns/ was removed during the 2.0 package refactor. Use the code snippets on this page as the reference implementation. For other runnable samples, see agentscope-examples/documentation/.

​

Why use subagents?

​

How it works

1. Orchestrator has a tool named Task (and optionally TaskOutput for background tasks). It also has direct tools (e.g. glob_search, grep_search, web_fetch) for simple, single-step work.
2. When the user request is complex or domain-specific, the orchestrator calls the Task tool with:
   • subagent_type: which sub-agent to run (e.g. codebase-explorer, web-researcher)
   • prompt: the task description to send to that sub-agent
3. The system looks up the sub-agent by type, runs it with that prompt in an isolated context (its own system prompt and tools), and returns the sub-agent’s reply as the tool result.
4. The orchestrator uses that result (and optionally other tool results) to synthesize a final answer for the user.

​

Defining sub-agents

​

1. Markdown (file-based)

---
name: codebase-explorer
description: Fast agent for exploring codebases. Use for finding files, searching code, analyzing structure. Tools: glob_search, grep_search.
tools: glob_search, grep_search
---

You are a codebase exploration specialist. Your job is to explore and analyze codebases efficiently.

**Your capabilities:**
- Find files using glob patterns
- Search file contents using regex
- Analyze project structure and dependencies

**Guidelines:**
- Use glob_search first to understand layout, then grep_search for content
- Provide concise, structured findings

• name: Unique identifier; the orchestrator uses this as subagent_type when calling the Task tool.
• description: Tells the orchestrator (and the model) when to delegate to this sub-agent. Be specific so the main agent knows when to use it.
• tools: Comma-separated list of tool names this sub-agent can use. Only these tools are attached; others are not available, which keeps the sub-agent focused and safe.

​

2. API (programmatic)

ReActAgent dependencyAnalyzerReAct = ReActAgent.builder()
        .name("dependency-analyzer")
        .description("Analyzes project dependencies. Use for version conflicts, outdated libs, security.")
        .model(model)
        .sysPrompt(DEPENDENCY_ANALYZER_SYSTEM_PROMPT)
        .toolkit(depToolkit)  // e.g. glob_search, grep_search only
        .memory(new InMemoryMemory())
        .build();

TaskToolsBuilder.builder()
        .model(model)
        .defaultToolsByName(defaultToolsByName)
        .subAgent("dependency-analyzer", dependencyAnalyzerReAct)
        // ... addAgentResource(...) for Markdown specs
        .build();

​

Task tools builder (AgentScope example)

1. TaskToolsBuilder.builder()
   • model: Used when building ReActAgents from Markdown specs.
   • defaultToolsByName: Map of tool name → instance (e.g. glob_search, grep_search, web_fetch). Markdown specs reference these by name in the tools field.
   • taskRepository: For background execution; required even if you only use synchronous Task calls.
   • subAgent(type, ReActAgent): Register one programmatic sub-agent.
   • addAgentResource(Resource): Load one Markdown spec from a classpath or file resource (e.g. classpath:agents/codebase-explorer.md).
2. build()
   Resolves all Markdown specs into ReActAgents (via AgentSpecLoader and a factory), merges them with programmatic sub-agents, and returns a TaskToolsResult with:
   • taskTool(): The Task tool to register on the orchestrator’s toolkit.
   • taskOutputTool(): The TaskOutput tool for checking or retrieving results of background tasks.
3. Orchestrator toolkit
   Register the Task and TaskOutput tools on the orchestrator’s Toolkit, along with any direct tools (glob, grep, web_fetch) the orchestrator can use itself. The orchestrator’s system prompt should describe when to delegate (which subagent_type for which kind of request) and when to use direct tools.

​

Example: Tech Due Diligence Assistant

• Orchestrator system prompt describes when to use each sub-agent and when to use direct tools. It has Task, TaskOutput, glob_search, grep_search, web_fetch.
• Markdown specs live in src/main/resources/agents/*.md and are loaded with TaskToolsBuilder.addAgentResource(res).
• dependency-analyzer is built as a ReActAgent and registered with TaskToolsBuilder.subAgent("dependency-analyzer", dependencyAnalyzerReAct).

@Autowired
OrchestratorService orchestratorService;

String answer = orchestratorService.run(
    "Analyze this codebase for technical debt and research Spring AI documentation");

​

Subagents vs other patterns

• Supervisor: The supervisor pattern also has a central agent that calls specialists as tools, but there is one tool per specialist (e.g. schedule_event, manage_email) and often fewer, more stable roles. Subagents use a single Task tool parameterized by type and prompt, and support many sub-agents (including Markdown-defined) and optional background execution.
• Agent as Tool: Agent as Tool registers one sub-agent as one tool with a fixed name and signature. Subagents use a dispatcher (Task tool) that selects the sub-agent by name and passes a free-form task string; sub-agents are often defined in bulk via Markdown.
• Routing: A router classifies the input and sends it to one or more specialists, then synthesizes results; it usually does not maintain a long conversation. The subagent orchestrator maintains the conversation and can call Task multiple times (possibly different sub-agent types) in one turn or across turns.

​

Best practices

• Write clear sub-agent descriptions: The orchestrator relies on description (and its own system prompt) to decide when to call which sub-agent. Include trigger phrases and example scenarios (e.g. “Use for finding files, searching code, analyzing structure”).
• Limit tools per sub-agent: In Markdown, list only the tools that sub-agent needs. This keeps behavior predictable and reduces the risk of misuse.
• Keep system prompts focused: The body of each Markdown file is the sub-agent’s system prompt. Define responsibilities, steps, and output format so the sub-agent returns useful, consistent results.
• Version control Markdown specs: Store agents/*.md in the repo so the team can add and refine sub-agents without code changes.

​

Related Documentation

• Supervisor - One supervisor, one tool per specialist
• Agent as Tool - Register a single agent as a tool
• Pipeline - Sequential and parallel composition