Skip to content

Commit 26f6c9e

Browse files
continue[bot]Continuenate
committed
docs: add documentation for Subagent tool
Add comprehensive documentation for the new Subagent feature including: - Architecture overview and execution flow - Built-in agents (general agent) - When to use subagents - Tool interface and parameters - Output streaming behavior - Implementation details and migration notes - Error handling - Future enhancements Also update AGENTS.md to reference the new subagents documentation. This documentation is for PR #9128. Generated with [Continue](https://continue.dev) Co-Authored-By: Continue <[email protected]> Co-authored-by: nate <[email protected]>
1 parent 316df75 commit 26f6c9e

File tree

2 files changed

+168
-0
lines changed

2 files changed

+168
-0
lines changed

‎extensions/cli/AGENTS.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,7 @@ This is a CLI tool for Continue Dev that provides an interactive AI-assisted dev
4646
- Code search functionality
4747
- Terminal command execution
4848
- Diff viewing
49+
- Subagents for delegating complex multi-step tasks (see [`docs/subagents.md`](./docs/subagents.md))
4950
- Exit tool (headless mode only)
5051

5152
6. **MCP Integration** (`src/mcp.ts`): Model Context Protocol service for extended tool capabilities

‎extensions/cli/docs/subagents.md‎

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
# Subagents
2+
3+
## Overview
4+
5+
The Subagent tool enables Continue CLI agents to spawn specialized sub-agents to handle complex, multi-step tasks autonomously. This allows for better task parallelization and separation of concerns by delegating specific work to isolated agent sessions.
6+
7+
## Architecture
8+
9+
### Subagent Execution
10+
11+
Subagents run in isolated child sessions with the following characteristics:
12+
13+
- **Isolated System Message**: Each subagent gets its own system prompt combined with the agent-specific instructions
14+
- **Separate Chat History**: Subagents maintain their own conversation context, independent of the parent agent
15+
- **Tool Access**: Subagents have access to all standard tools (Read, Write, Edit, etc.) except the Subagent tool itself to prevent recursion
16+
- **Permission Inheritance**: Subagents inherit tool permissions from the main agent, with all tools currently allowed by default
17+
18+
### Tool Interface
19+
20+
The Subagent tool is a built-in tool available to all agents running in the CLI.
21+
22+
**Tool Name:** `Subagent`
23+
24+
**Parameters:**
25+
26+
- `description` (string, required): A short 3-5 word description of the task
27+
- `prompt` (string, required): The detailed task for the subagent to perform
28+
- `subagent_name` (string, required): The type of specialized agent to use (currently only `"general"` is available)
29+
30+
**Example Tool Call:**
31+
32+
```json
33+
{
34+
"name": "Subagent",
35+
"parameters": {
36+
"description": "Research API patterns",
37+
"prompt": "Analyze the codebase and document all REST API endpoints, including their parameters, response formats, and authentication requirements.",
38+
"subagent_name": "general"
39+
}
40+
}
41+
```
42+
43+
## Built-in Agents
44+
45+
### General Agent
46+
47+
The `general` agent is a versatile subagent designed for autonomous execution of multi-step tasks.
48+
49+
**Capabilities:**
50+
51+
- Researching complex questions across multiple files
52+
- Executing multi-step implementation tasks
53+
- Performing comprehensive code analysis
54+
- Working autonomously with minimal guidance
55+
56+
**System Prompt:**
57+
58+
```
59+
You are a specialized task execution agent.
60+
61+
Your role:
62+
- Work autonomously to complete the given task
63+
- Use available tools effectively
64+
- Provide clear, concise results
65+
- If you cannot complete the task, explain why clearly
66+
67+
Important:
68+
- Focus on the specific task at hand
69+
- Avoid unnecessary explanations or preamble in your final response
70+
- Return actionable results
71+
```
72+
73+
## When to Use Subagents
74+
75+
**Good Use Cases:**
76+
77+
- Complex research tasks requiring multiple file reads and searches
78+
- Multi-step implementation tasks that can be completed independently
79+
- Tasks that benefit from autonomous execution without back-and-forth
80+
- Parallelizing independent work items
81+
82+
**Not Recommended For:**
83+
84+
- Simple single-file reads (use the `Read` tool directly)
85+
- Single search operations (use the `searchCode` tool directly)
86+
- Tasks that require frequent user input or clarification
87+
- Trivial operations that don't require multiple steps
88+
89+
## Output Streaming
90+
91+
Subagent execution supports real-time output streaming:
92+
93+
- The subagent's output is streamed back to the parent agent as it executes
94+
- Long outputs are truncated in the UI (showing the last 20 lines)
95+
- Tool calls and their results are visible during execution
96+
- A metadata footer indicates the task status (completed/failed)
97+
98+
**UI Output Format:**
99+
100+
```
101+
⎿ Subagent output:
102+
... +50 lines
103+
<last 20 lines of output>
104+
105+
<task_metadata>
106+
status: completed
107+
</task_metadata>
108+
```
109+
110+
## Implementation Details
111+
112+
### Tool Changes
113+
114+
The introduction of subagents required a modification to the `Tool` interface:
115+
116+
**Before:**
117+
118+
```typescript
119+
run: (args: any) => Promise<string>;
120+
```
121+
122+
**After:**
123+
124+
```typescript
125+
run: (args: any, context?: { toolCallId: string }) => Promise<string>;
126+
```
127+
128+
The optional `context` parameter provides the `toolCallId` which enables live streaming of subagent output back to the parent agent's chat history.
129+
130+
**Migration Note:** If you have custom tools with strict TypeScript settings, update their signatures to match the new interface. The `context` parameter is optional and can be ignored if streaming is not needed.
131+
132+
## Execution Flow
133+
134+
1. **Tool Call**: Parent agent calls the Subagent tool with description, prompt, and agent type
135+
2. **Validation**: The system validates the agent type and checks for available models
136+
3. **Session Creation**: A child session is created with:
137+
- The subagent's custom system message
138+
- Disabled parent chat history interference
139+
- All tools except the Subagent tool itself
140+
4. **Execution**: The subagent executes autonomously using the provided prompt
141+
5. **Streaming**: Output streams back to the parent via the `toolCallId`
142+
6. **Completion**: The final response is returned to the parent agent with status metadata
143+
7. **Cleanup**: The child session resources are cleaned up, and the parent's system message and chat history state are restored
144+
145+
## Error Handling
146+
147+
Subagent execution includes comprehensive error handling:
148+
149+
- **Validation Errors**: Invalid agent types or missing parameters are caught early
150+
- **Execution Errors**: Runtime errors are logged and returned with detailed messages
151+
- **Graceful Degradation**: Failed subagent execution returns an error result without crashing the parent agent
152+
- **State Restoration**: Original system message and chat history state are always restored, even if the subagent fails
153+
154+
## Future Enhancements
155+
156+
Potential improvements to the subagent system:
157+
158+
- **Custom Agent Types**: Support for specialized agents (e.g., "researcher", "implementer", "reviewer")
159+
- **Tool Restrictions**: Fine-grained control over which tools each agent type can access
160+
- **Model Selection**: Allow specifying different models for different agent types
161+
- **Subagent Chaining**: Enable subagents to spawn their own subagents for hierarchical task decomposition
162+
- **Result Caching**: Cache subagent results for frequently executed tasks
163+
- **Parallel Execution**: Run multiple subagents concurrently for independent tasks
164+
165+
---
166+
167+
This document describes the initial subagent implementation. Update it as the feature evolves.

0 commit comments

Comments
 (0)