feat(core): add token isolation architecture for multi-agent efficiency
- Add spawn-agent.xml task for isolated subprocess spawning - Add token-isolation.md documentation with architecture patterns - Support parallel and sequential agent collaboration patterns - Preserve main session context by isolating agent workloads
This commit is contained in:
Ibrahim Elsahafy
parent
d8b13bdb2e
commit
b59fcc7d55
|
|
@ -0,0 +1,66 @@
|
|||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<task id="spawn-agent" name="Spawn Isolated Agent" standalone="false">
|
||||
<description>Spawn an agent in an isolated subprocess with token isolation</description>
|
||||
|
||||
<config>
|
||||
<source>{project-root}/_bmad/core/config.yaml</source>
|
||||
<token_config>{project-root}/_bmad/bmm/config.yaml:token_management</token_config>
|
||||
</config>
|
||||
|
||||
<parameters>
|
||||
<param name="agent_type" required="true" description="Type of agent to spawn (analyst, architect, dev, pm, etc.)"/>
|
||||
<param name="task_description" required="true" description="Brief description of the task (3-5 words)"/>
|
||||
<param name="prompt" required="true" description="Full prompt/instructions for the agent"/>
|
||||
<param name="model" required="false" default="sonnet" description="Model to use: sonnet, opus, haiku"/>
|
||||
<param name="run_in_background" required="false" default="false" description="Run agent in background"/>
|
||||
<param name="output_file" required="false" description="Path for agent output file"/>
|
||||
</parameters>
|
||||
|
||||
<execution>
|
||||
<step n="1" goal="Validate parameters">
|
||||
<action>Verify agent_type is valid (exists in agent-manifest.csv)</action>
|
||||
<action>Verify prompt is not empty</action>
|
||||
<action>Set default model to sonnet if not specified</action>
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Prepare agent context">
|
||||
<action>Load agent persona from {project-root}/_bmad/_config/agent-manifest.csv</action>
|
||||
<action>Load any agent customizations from {project-root}/_bmad/_config/agents/</action>
|
||||
<action>Construct full agent prompt with persona + task prompt</action>
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Configure output handling">
|
||||
<action if="output_file specified">Use specified output path</action>
|
||||
<action if="output_file not specified">
|
||||
Generate path: {output_folder}/temp/{agent_type}-{timestamp}.md
|
||||
</action>
|
||||
<action>Append output instructions to prompt:
|
||||
"Write your complete output to: {output_file}
|
||||
Return only a brief summary (under 500 words) to this conversation."
|
||||
</action>
|
||||
</step>
|
||||
|
||||
<step n="4" goal="Spawn agent subprocess">
|
||||
<action>Use Task tool with:
|
||||
- description: "{agent_type}: {task_description}"
|
||||
- prompt: {constructed_prompt}
|
||||
- subagent_type: "general-purpose"
|
||||
- model: {model}
|
||||
- run_in_background: {run_in_background}
|
||||
</action>
|
||||
</step>
|
||||
|
||||
<step n="5" goal="Handle response">
|
||||
<action if="run_in_background == false">Wait for agent completion</action>
|
||||
<action if="run_in_background == true">Return agent_id for later retrieval</action>
|
||||
<action>Return summary and output file path to caller</action>
|
||||
</step>
|
||||
</execution>
|
||||
|
||||
<output>
|
||||
<field name="status" description="success | failed | running"/>
|
||||
<field name="agent_id" description="ID for background agents"/>
|
||||
<field name="output_file" description="Path to full output"/>
|
||||
<field name="summary" description="Brief summary of agent work"/>
|
||||
</output>
|
||||
</task>
|
||||
|
|
@ -0,0 +1,103 @@
|
|||
# Token Isolation Architecture
|
||||
|
||||
## Overview
|
||||
|
||||
Token isolation prevents context bloat in multi-agent scenarios by running agents in isolated subprocesses. Each agent gets its own 150K token context window without consuming the main session's tokens.
|
||||
|
||||
## Architecture Diagram
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ TOKEN ISOLATION ARCHITECTURE │
|
||||
├─────────────────────────────────────────────────────────────────────────┤
|
||||
│ Main Session (150K tokens preserved) │
|
||||
│ │ │
|
||||
│ ▼ Task Tool spawns subprocess │
|
||||
│ ┌────────────────────┐ │
|
||||
│ │ Agent Instance │ ◄── Own 150K token context │
|
||||
│ │ (subprocess) │ ◄── Doesn't consume main session │
|
||||
│ └─────────┬──────────┘ │
|
||||
│ │ │
|
||||
│ ▼ Only summary returns │
|
||||
│ "Task complete. Output: temp/raw/file.md" │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Core Rules
|
||||
|
||||
1. **ALWAYS** use Task tool to invoke agents (preserves main session tokens)
|
||||
2. Agents write to files, not return full content to main session
|
||||
3. Use `run_in_background: true` for parallel independent agents
|
||||
4. Sequential agents receive previous output via content injection
|
||||
5. Summaries returned to main session must be < 2000 tokens
|
||||
|
||||
## Agent Execution Template
|
||||
|
||||
```javascript
|
||||
Task({
|
||||
description: "agent-name: brief task description",
|
||||
prompt: agentPrompt,
|
||||
subagent_type: "general-purpose",
|
||||
model: "sonnet", // or "haiku" for quick tasks
|
||||
run_in_background: false // true for parallel
|
||||
});
|
||||
```
|
||||
|
||||
## Collaboration Patterns
|
||||
|
||||
### Sequential Pattern
|
||||
```
|
||||
Agent A → Agent B → Agent C
|
||||
```
|
||||
Use when each step depends on previous output.
|
||||
|
||||
### Parallel Pattern
|
||||
```
|
||||
Agent A ─┐
|
||||
Agent B ─┼→ Synthesis
|
||||
Agent C ─┘
|
||||
```
|
||||
Use when analyses are independent.
|
||||
|
||||
### Debate Pattern
|
||||
```
|
||||
Proposer ↔ Challenger → Refined Output
|
||||
```
|
||||
Use for critical decisions requiring adversarial review.
|
||||
|
||||
### War Room Pattern
|
||||
```
|
||||
All Agents → Intensive Collaboration → Solution
|
||||
```
|
||||
Use for complex urgent problems.
|
||||
|
||||
## Output Management
|
||||
|
||||
### File-Based Output
|
||||
Agents should write outputs to:
|
||||
- `{output_folder}/temp/` - Temporary working files
|
||||
- `{output_folder}/raw/` - Raw agent outputs
|
||||
- `{output_folder}/final/` - Validated final outputs
|
||||
|
||||
### Summary Protocol
|
||||
When an agent completes:
|
||||
1. Write full output to designated file
|
||||
2. Return only: status, file path, key findings (< 2000 tokens)
|
||||
3. Main session can read file if details needed
|
||||
|
||||
## Token Budget Tracking
|
||||
|
||||
| Threshold | Action |
|
||||
|-----------|--------|
|
||||
| 0-80% | Normal operation |
|
||||
| 80-90% | Warning: Consider wrapping up |
|
||||
| 90-100% | Critical: Summarize and hand off |
|
||||
| 100%+ | HALT: Must spawn new subprocess |
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Pre-plan agent work** - Know what each agent needs to do
|
||||
2. **Minimize cross-agent data** - Pass file references, not content
|
||||
3. **Use haiku for simple tasks** - Reduces cost and latency
|
||||
4. **Batch related work** - One agent, multiple related tasks
|
||||
5. **Checkpoint frequently** - Save progress to files regularly
|
||||
Loading…
Reference in New Issue