104 lines
4.0 KiB
Markdown
104 lines
4.0 KiB
Markdown
# 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
|