553 lines
20 KiB
Markdown
553 lines
20 KiB
Markdown
# Multi-Model DnD Agent System - Complete Setup
|
|
|
|
This document describes the **complete multi-model agent orchestration system** for your DnD campaign vault, optimized for cost-effectiveness and specialized capabilities.
|
|
|
|
## 🎯 System Architecture
|
|
|
|
The system implements a **three-tier architecture** with clear role separation:
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────┐
|
|
│ TIER 1: ORCHESTRATOR │
|
|
│ (Mistral Medium - 2604) │
|
|
│ ┌─────────────────────────────────────────────────────────────────┐│
|
|
│ │ • Analyzes user requests in campaign context ││
|
|
│ │ • Delegates concrete steps to Tier 2 workers ││
|
|
│ │ • Requests creative ideas from Tier 3 (single API call) ││
|
|
│ │ • Synthesizes results and presents to user ││
|
|
│ │ • Coordinates all multi-agent workflows ││
|
|
│ └─────────────────────────────────────────────────────────────────┘│
|
|
└─────────────────────────────────────────────────────────────────────┘
|
|
│
|
|
┌───────────────────┼───────────────────┐
|
|
▼ ▼ ▼
|
|
┌─────────────────────────┐ ┌─────────────────────┐ ┌─────────────────────┐
|
|
│ TIER 2: WORKERS │ │ TIER 2: WORKERS │ │ TIER 2: WORKERS │
|
|
│ (Mistral Small - 2604) │ │ (Mistral Small - 2604) │ │ (Mistral Small - 2604) │
|
|
│ • Session Prep Worker │ │ • Implementer Worker │ │ • Generator Worker │
|
|
│ • Analyzes sessions │ │ • Extracts entities │ │ • Creates content │
|
|
│ • Reviews story arcs │ │ • Creates files │ │ • Applies templates │
|
|
│ • Generates prep docs │ │ • Links content │ │ • Links to existing │
|
|
└─────────────────────────┘ └─────────────────────┘ └─────────────────────┘
|
|
│
|
|
┌───────────────────┘
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────────┐
|
|
│ TIER 3: CREATIVE │
|
|
│ (Claude Opus - 4.5) │
|
|
│ ┌─────────────────────────────────────────────────────────────────┐│
|
|
│ │ • Generates creative ideas ONLY ││
|
|
│ │ • Single API call per request (cost optimization) ││
|
|
│ │ • Minimal context provided (token optimization) ││
|
|
│ │ • Returns concise concepts only (no explanation) ││
|
|
│ │ • ZERO tool access (security isolation) ││
|
|
│ └─────────────────────────────────────────────────────────────────┘│
|
|
└─────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## 📊 Cost Optimization Strategy
|
|
|
|
| Model | Usage | Cost Level | Purpose |
|
|
|-------|-------|------------|---------|
|
|
| Mistral Medium | Orchestrator (1 instance) | Medium | Coordination, reasoning, synthesis |
|
|
| Mistral Small | Workers (4 instances) | Low | All concrete execution |
|
|
| Claude Opus | Creative (1 instance) | High | Creative ideas only |
|
|
|
|
**Estimated Savings**: ~70-80% compared to using Claude Opus for everything
|
|
|
|
**Token Usage Pattern**:
|
|
- 60%: Mistral Small (workers doing the heavy lifting)
|
|
- 25%: Mistral Medium (orchestrator coordinating)
|
|
- 15%: Claude Opus (creative ideas only when needed)
|
|
|
|
---
|
|
|
|
## 🤖 Agent Specifications
|
|
|
|
### Tier 1: Orchestrator
|
|
|
|
**Agent**: `dnd-orchestrator`
|
|
- **Model**: `mistral/mistral-medium-2604`
|
|
- **Mode**: `primary`
|
|
- **Temperature**: 0.3 (balanced reasoning)
|
|
- **Color**: Brown (#8B4513)
|
|
- **File**: `.opencode/agents/dnd-orchestrator.md`
|
|
|
|
**Capabilities**:
|
|
- ✅ Full tool access (read, write, glob, grep, edit, bash)
|
|
- ✅ Full skill access (all dnd-*)
|
|
- ✅ Can delegate to all worker agents (`dnd-worker-*`)
|
|
- ✅ Can request from creative agent (`dnd-creative`) with confirmation
|
|
- ✅ Can use question tool for user input
|
|
- ❌ Cannot access external resources (webfetch denied)
|
|
|
|
**Responsibilities**:
|
|
1. Understand user requests in full campaign context
|
|
2. Break down complex tasks into delegatable steps
|
|
3. Request creative ideas from creative agent when needed
|
|
4. Implement creative ideas using worker agents
|
|
5. Synthesize all results and present to user
|
|
6. Ensure campaign consistency across all work
|
|
|
|
---
|
|
|
|
### Tier 2: Worker Agents
|
|
|
|
All workers use `mistral/mistral-small-2604` for cost-effective execution.
|
|
|
|
#### 1. dnd-worker-session-prep
|
|
- **Temperature**: 0.2 (very focused)
|
|
- **Color**: Green (#228B22)
|
|
- **File**: `.opencode/agents/dnd-worker-session-prep.md`
|
|
|
|
**Handles**:
|
|
- Analyzing session notes and extracting key information
|
|
- Reviewing active story arcs and identifying threads
|
|
- Checking NPC and location statuses
|
|
- Generating session prep document sections
|
|
- Creating preparation checklists
|
|
|
|
**Permissions**:
|
|
- ✅ Full tool access (read, write, glob, grep, edit, bash)
|
|
- ✅ Full skill access (all dnd-*)
|
|
- ❌ CANNOT delegate to other agents (task: deny)
|
|
- ❌ CANNOT access external resources
|
|
|
|
---
|
|
|
|
#### 2. dnd-worker-implementer
|
|
- **Temperature**: 0.2 (very focused)
|
|
- **Color**: Green (#228B22)
|
|
- **File**: `.opencode/agents/dnd-worker-implementer.md`
|
|
|
|
**Handles**:
|
|
- Parsing session notes for entities and events
|
|
- Extracting NPCs, locations, items, organizations
|
|
- Creating new content files from extracted information
|
|
- Linking content with wiki links
|
|
- Moving files between directories
|
|
- Validating content structure
|
|
|
|
**Permissions**: Same as session-prep worker
|
|
|
|
---
|
|
|
|
#### 3. dnd-worker-generator
|
|
- **Temperature**: 0.3 (slightly creative)
|
|
- **Color**: Green (#228B22)
|
|
- **File**: `.opencode/agents/dnd-worker-generator.md`
|
|
|
|
**Handles**:
|
|
- Creating new locations with detailed descriptions
|
|
- Creating new NPCs with full profiles
|
|
- Creating new quests and story arcs
|
|
- Creating new items and equipment
|
|
- Applying templates and metadata
|
|
- Linking new content to existing vault elements
|
|
|
|
**Permissions**: Same as other workers
|
|
|
|
---
|
|
|
|
#### 4. dnd-worker-organizer
|
|
- **Temperature**: 0.1 (very focused)
|
|
- **Color**: Green (#228B22)
|
|
- **File**: `.opencode/agents/dnd-worker-organizer.md`
|
|
|
|
**Handles**:
|
|
- Validating vault structure against standards
|
|
- Checking and repairing wiki links
|
|
- Identifying duplicate content
|
|
- Finding orphaned files
|
|
- Cleaning up Inbox directory
|
|
- Generating vault health reports
|
|
|
|
**Permissions**: Same as other workers
|
|
|
|
---
|
|
|
|
### Tier 3: Creative Agent
|
|
|
|
**Agent**: `dnd-creative`
|
|
- **Model**: `anthropic/claude-opus-4.5`
|
|
- **Mode**: `subagent`
|
|
- **Temperature**: 1.0 (maximum creativity)
|
|
- **Color**: Purple (#9370DB)
|
|
- **File**: `.opencode/agents/dnd-creative.md`
|
|
|
|
**Capabilities**:
|
|
- ✅ Generate creative DnD concepts
|
|
- ✅ Return concise ideas (single sentences)
|
|
- ✅ Single API call per request
|
|
- ❌ CANNOT access ANY tools (all permissions: deny)
|
|
- ❌ CANNOT use any skills (skill: deny)
|
|
- ❌ CANNOT delegate to other agents (task: deny)
|
|
- ❌ CANNOT ask questions (question: deny)
|
|
- ❌ CANNOT fetch external resources (webfetch: deny)
|
|
|
|
**Responsibilities**:
|
|
1. Generate creative ideas when requested by orchestrator
|
|
2. Provide ONLY the ideas (no explanation, no implementation)
|
|
3. Use minimal context (orchestrator provides brief context)
|
|
4. Respond in ONE message (single API call)
|
|
5. Return ideas in German language
|
|
|
|
**Response Format**:
|
|
```
|
|
Idea 1 as a single concise sentence.
|
|
Idea 2 as a single concise sentence.
|
|
Idea 3 as a single concise sentence.
|
|
```
|
|
|
|
---
|
|
|
|
## 🔄 Workflow Examples
|
|
|
|
### Example 1: Session Preparation
|
|
|
|
**User Request**: "Prepare materials for next session"
|
|
|
|
**Workflow**:
|
|
```
|
|
1. User → dnd-orchestrator (Medium)
|
|
"Prepare materials for next session"
|
|
|
|
2. dnd-orchestrator analyzes campaign state
|
|
- Reads last session notes
|
|
- Reviews active story arcs
|
|
- Checks current campaign status
|
|
|
|
3. dnd-orchestrator delegates to workers (Small):
|
|
@dnd-worker-session-prep "Analyze Session 15 and identify unresolved plot hooks"
|
|
@dnd-worker-session-prep "Review active quests and their status"
|
|
|
|
4. dnd-orchestrator requests creative input (Opus):
|
|
@dnd-creative "Generate 3 creative session hook ideas for campaign with stolen amulet"
|
|
→ Returns: 3 single-sentence ideas
|
|
|
|
5. dnd-orchestrator implements best idea using workers (Small):
|
|
@dnd-worker-generator "Create session prep document with selected hook"
|
|
|
|
6. dnd-orchestrator synthesizes all results
|
|
→ Presents comprehensive session prep to user
|
|
```
|
|
|
|
**Token Usage**:
|
|
- Medium: ~500 tokens (orchestration)
|
|
- Small: ~2000 tokens (worker execution)
|
|
- Opus: ~50 tokens (creative ideas)
|
|
- **Total**: ~2550 tokens (optimized)
|
|
|
|
---
|
|
|
|
### Example 2: Story Implementation
|
|
|
|
**User Request**: "Process session notes from Session 15"
|
|
|
|
**Workflow**:
|
|
```
|
|
1. User → dnd-orchestrator (Medium)
|
|
"Process session notes from 01-Sessions/Session 15 - Title.md"
|
|
|
|
2. dnd-orchestrator reads session notes
|
|
|
|
3. dnd-orchestrator delegates to workers (Small):
|
|
@dnd-worker-implementer "Extract all NPCs and create/update files"
|
|
@dnd-worker-implementer "Extract all locations and create/update files"
|
|
@dnd-worker-implementer "Extract quest progress and update arc files"
|
|
@dnd-worker-implementer "Link all new content with wiki links"
|
|
|
|
4. dnd-orchestrator verifies all work
|
|
|
|
5. dnd-orchestrator presents results to user
|
|
```
|
|
|
|
**Token Usage**:
|
|
- Medium: ~300 tokens (orchestration)
|
|
- Small: ~3000 tokens (worker execution)
|
|
- Opus: 0 tokens (no creative needed)
|
|
- **Total**: ~3300 tokens
|
|
|
|
---
|
|
|
|
### Example 3: Content Creation
|
|
|
|
**User Request**: "Create a new city for the Sword Coast"
|
|
|
|
**Workflow**:
|
|
```
|
|
1. User → dnd-orchestrator (Medium)
|
|
"Create a new city for the Sword Coast region"
|
|
|
|
2. dnd-orchestrator analyzes existing Sword Coast content
|
|
|
|
3. dnd-orchestrator requests creative input (Opus):
|
|
@dnd-creative "Generate 3 unique city concepts for Sword Coast region"
|
|
→ Returns: 3 single-sentence concepts
|
|
|
|
4. User selects: "Eldrin, a port city with hidden Underdark entrance"
|
|
|
|
5. dnd-orchestrator delegates to workers (Small):
|
|
@dnd-worker-generator "Create detailed city file for Eldrin"
|
|
@dnd-worker-generator "Generate 3 relevant NPCs for Eldrin"
|
|
@dnd-worker-generator "Create 2 quest hooks connected to Eldrin"
|
|
@dnd-worker-implementer "Link all new content together"
|
|
|
|
6. dnd-orchestrator verifies consistency
|
|
|
|
7. dnd-orchestrator presents results to user
|
|
```
|
|
|
|
**Token Usage**:
|
|
- Medium: ~400 tokens (orchestration)
|
|
- Small: ~2500 tokens (worker execution)
|
|
- Opus: ~30 tokens (creative ideas)
|
|
- **Total**: ~2930 tokens
|
|
|
|
---
|
|
|
|
## 📋 Configuration Files
|
|
|
|
### 1. opencode.json
|
|
Main configuration file with all agent definitions:
|
|
|
|
```json
|
|
{
|
|
"agent": {
|
|
"dnd-orchestrator": {
|
|
"model": "mistral/mistral-medium-2604",
|
|
"mode": "primary",
|
|
"temperature": 0.3,
|
|
"task": {
|
|
"dnd-worker-*": "allow",
|
|
"dnd-creative": "ask"
|
|
}
|
|
},
|
|
"dnd-worker-*": {
|
|
"model": "mistral/mistral-small-2604",
|
|
"mode": "subagent",
|
|
"task": "deny"
|
|
},
|
|
"dnd-creative": {
|
|
"model": "anthropic/claude-opus-4.5",
|
|
"mode": "subagent",
|
|
"permission": {
|
|
"read": "deny",
|
|
"write": "deny",
|
|
"task": "deny",
|
|
"skill": "deny"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### 2. Agent Definition Files
|
|
Each agent has a markdown file in `.opencode/agents/`:
|
|
|
|
- `dnd-orchestrator.md` - Primary coordinator
|
|
- `dnd-worker-session-prep.md` - Session preparation worker
|
|
- `dnd-worker-implementer.md` - Story implementation worker
|
|
- `dnd-worker-generator.md` - Content generation worker
|
|
- `dnd-worker-organizer.md` - Vault organization worker
|
|
- `dnd-creative.md` - Creative ideas agent
|
|
|
|
---
|
|
|
|
## 🚀 Usage Instructions
|
|
|
|
### Starting a Session
|
|
|
|
1. **Load the orchestrator**:
|
|
```
|
|
@dnd-orchestrator [your request]
|
|
```
|
|
|
|
2. **Let it coordinate**: The orchestrator will:
|
|
- Analyze your request
|
|
- Delegate to appropriate workers
|
|
- Request creative ideas if needed
|
|
- Synthesize and present results
|
|
|
|
### Direct Agent Invocation
|
|
|
|
You can also invoke agents directly:
|
|
|
|
```
|
|
# For session preparation
|
|
@dnd-worker-session-prep Analyze Session 15 and identify plot hooks
|
|
|
|
# For story implementation
|
|
@dnd-worker-implementer Extract NPCs from Session 15 notes
|
|
|
|
# For content generation
|
|
@dnd-worker-generator Create a new NPC file for Veylin
|
|
|
|
# For vault organization
|
|
@dnd-worker-organizer Validate all wiki links in 01-Sessions/
|
|
|
|
# For creative ideas (orchestrator will usually handle this)
|
|
@dnd-creative Generate 3 quest ideas for the Cult of the Eclipse
|
|
```
|
|
|
|
---
|
|
|
|
## 🛡️ Security & Safety Features
|
|
|
|
### Creative Agent Isolation
|
|
- **Zero tool access**: Cannot read, write, or modify any files
|
|
- **Zero skill access**: Cannot use any skills or templates
|
|
- **Zero delegation**: Cannot invoke other agents
|
|
- **Pure generation**: Only provides creative ideas, never implements
|
|
|
|
### Worker Agent Restrictions
|
|
- **No delegation**: Workers cannot invoke other agents
|
|
- **Controlled access**: Only have permissions they need
|
|
- **Focused scope**: Each worker has specific, limited responsibilities
|
|
|
|
### Orchestrator Control
|
|
- **Single point of coordination**: Only orchestrator can manage multi-agent workflows
|
|
- **Permission boundaries**: Orchestrator has full access but follows delegation rules
|
|
- **User confirmation**: Creative agent requests require confirmation
|
|
|
|
---
|
|
|
|
## 📊 Performance Metrics
|
|
|
|
### Response Times
|
|
| Agent | Typical Response Time | Complexity |
|
|
|-------|----------------------|------------|
|
|
| Orchestrator | 5-10 seconds | High |
|
|
| Workers | 2-5 seconds | Medium |
|
|
| Creative | 3-8 seconds | Low (simple generation) |
|
|
|
|
### Cost Comparison
|
|
| Approach | Estimated Cost | Quality |
|
|
|----------|---------------|---------|
|
|
| All Opus | $$$$$ | ⭐⭐⭐⭐⭐ |
|
|
| All Medium | $$$ | ⭐⭐⭐⭐ |
|
|
| **This System** | **$$** | **⭐⭐⭐⭐⭐** |
|
|
| All Small | $ | ⭐⭐ |
|
|
|
|
---
|
|
|
|
## 🎯 Best Practices
|
|
|
|
### For Users
|
|
1. **Start with orchestrator** for complex tasks
|
|
2. **Provide clear context** for better results
|
|
3. **Review creative options** before selection
|
|
4. **Trust the delegation** - workers are optimized for their tasks
|
|
5. **Use direct invocation** for simple, focused tasks
|
|
|
|
### For Orchestrator
|
|
1. **Analyze first** - Understand the full context
|
|
2. **Delegate appropriately** - Use the right worker for each task
|
|
3. **Minimize creative context** - Give creative agent only what it needs
|
|
4. **Verify all work** - Check worker results before presenting
|
|
5. **Synthesize clearly** - Present organized, ready-to-use results
|
|
|
|
### For Workers
|
|
1. **Follow instructions exactly** - Do only what you're asked
|
|
2. **Use templates** - Apply appropriate skill templates
|
|
3. **Link everything** - Always use wiki links for references
|
|
4. **Validate work** - Check your results before returning
|
|
5. **Be concise** - Return only what was requested
|
|
|
|
### For Creative Agent
|
|
1. **Ideas only** - Never explain or implement
|
|
2. **Single sentences** - Each idea as one concise sentence
|
|
3. **One message** - Respond in a single API call
|
|
4. **German language** - All ideas in German
|
|
5. **No questions** - Never ask for clarification
|
|
|
|
---
|
|
|
|
## 🔧 Setup Requirements
|
|
|
|
### Model Access
|
|
You need access to these models:
|
|
- **Mistral Medium 2604** (for orchestrator)
|
|
- **Mistral Small 2604** (for all workers)
|
|
- **Claude Opus 4.5** (for creative ideas)
|
|
|
|
### Configuration
|
|
1. Set up provider credentials in OpenCode
|
|
2. Verify models are available: `/models`
|
|
3. Test each agent individually
|
|
4. Start with simple tasks to verify workflow
|
|
|
|
### MCP Servers (Optional but Recommended)
|
|
Configure these verified MCP servers for enhanced capabilities:
|
|
- `dnd-5e-mcp` - DnD 5e content via Open5e API
|
|
- `obsidian-mcp` - Direct vault access
|
|
- `gamemaster-mcp` - Campaign management
|
|
|
|
---
|
|
|
|
## 📁 File Structure
|
|
|
|
```
|
|
.opencode/
|
|
├── agents/ # Agent definitions
|
|
│ ├── dnd-orchestrator.md # Primary coordinator (Medium)
|
|
│ ├── dnd-worker-session-prep.md # Session prep worker (Small)
|
|
│ ├── dnd-worker-implementer.md # Implementation worker (Small)
|
|
│ ├── dnd-worker-generator.md # Content generation worker (Small)
|
|
│ ├── dnd-worker-organizer.md # Vault organization worker (Small)
|
|
│ ├── dnd-creative.md # Creative ideas agent (Opus)
|
|
│ └── README.md # Agent documentation
|
|
│
|
|
├── skills/ # Skill definitions (unchanged)
|
|
│ ├── dnd-session-manager/
|
|
│ ├── dnd-npc-creator/
|
|
│ ├── dnd-location-builder/
|
|
│ ├── ...
|
|
│ └── README.md
|
|
│
|
|
├── opencode.json # Main configuration
|
|
└── MULTI_MODEL_SETUP.md # This file
|
|
```
|
|
|
|
---
|
|
|
|
## 🆘 Troubleshooting
|
|
|
|
### Orchestrator Issues
|
|
- **Not delegating**: Check task permissions in opencode.json
|
|
- **Not synthesizing**: Verify worker responses are being received
|
|
- **Creative not responding**: Check that creative agent is not disabled
|
|
|
|
### Worker Issues
|
|
- **Permission denied**: Check agent permissions in opencode.json
|
|
- **Not executing**: Verify worker has required tool access
|
|
- **Delegating**: Workers should NOT delegate - check configuration
|
|
|
|
### Creative Agent Issues
|
|
- **Explaining ideas**: Remind agent to return ONLY ideas
|
|
- **Multiple messages**: Check temperature and instructions
|
|
- **Not creative**: Verify model is Claude Opus 4.5
|
|
|
|
---
|
|
|
|
## 📚 Additional Documentation
|
|
|
|
- **Agent Details**: `.opencode/agents/README.md` - Comprehensive agent documentation
|
|
- **Skills**: `.opencode/skills/README.md` - Skill definitions and usage
|
|
- **OpenCode Docs**: [opencode.ai/docs/agents/](https://opencode.ai/docs/agents/) - Official agent documentation
|
|
|
|
---
|
|
|
|
## 🎉 Summary
|
|
|
|
This **multi-model agent system** provides:
|
|
|
|
✅ **Optimal cost-effectiveness** - Uses cheaper models for most work
|
|
✅ **Specialized capabilities** - Each agent optimized for its role
|
|
✅ **Clear separation of concerns** - Orchestrator coordinates, workers execute, creative inspires
|
|
✅ **Security isolation** - Creative agent has zero access to tools/files
|
|
✅ **Scalable architecture** - Easy to add more workers or agents
|
|
✅ **Campaign-optimized** - Designed specifically for DnD vault management
|
|
|
|
**Result**: High-quality DnD campaign management at a fraction of the cost of using premium models for everything.
|