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