107 lines
3.1 KiB
Markdown
107 lines
3.1 KiB
Markdown
---
|
|
description: Guide for running subagents effectively - model selection and troubleshooting
|
|
limit: 5000
|
|
---
|
|
# Subagent Usage Guide
|
|
|
|
## Model Selection
|
|
|
|
When running subagents via the Task tool, always specify a valid model from the available list.
|
|
|
|
### Available Models (as of current system)
|
|
- `kimi-k2.5-nvfp4` - Fast, reliable
|
|
- `kimi-k2.5` - Standard option, works well
|
|
- `glm-4.7-flash` - Lightweight
|
|
- `glm-4.7` - Standard GLM
|
|
- `kimi-k2-thinking` - For reasoning tasks
|
|
- `minimax-m2.5` - Alternative option
|
|
- `qwen3.5` - Qwen series
|
|
- `deepseek-v3.2` - DeepSeek
|
|
- `deepseek-r1` - Reasoning-focused
|
|
- `qwen3-coder` - Code-specific
|
|
- `llama-3.3-70b` - Llama series
|
|
- `sonnet` - Anthropic proxy (uses kimi-k2.5-nvfp4)
|
|
- `haiku` - Lightweight proxy
|
|
- `opus` - Heavy proxy (uses kimi-k2.5-nvfp4)
|
|
- `nemotron-3-super` - NVIDIA model
|
|
- `gpt-oss-120b` - OpenAI OSS
|
|
|
|
### Tiered Model Selection
|
|
|
|
| Task Level | Model | Purpose |
|
|
|------------|-------|---------|
|
|
| **Opus-level** | `kimi-k2.5` | Deep research, complex analysis, high-stakes decisions |
|
|
| **Sonnet-level** | `nemotron-3-super` | Mid-complexity, balanced reasoning, implementation |
|
|
| **Deep reasoning** | `kimi-k2-thinking` | Verification, synthesis, final review at end of chain |
|
|
|
|
### What NOT to Use
|
|
- **NO `qwen`** - User preference: "Qwen sucks"
|
|
- **NO `claude` models** - Hardcoded to proxies, avoid confusion
|
|
- **NO `glm-4.7-flash`** - Use `nemotron-3-super` instead for lightweight tasks
|
|
|
|
### Preferred Models (Updated)
|
|
- **Opus-level tasks**: `kimi-k2.5` (heavy research, architecture decisions)
|
|
- **Sonnet-level tasks**: `nemotron-3-super` (implementation, exploration)
|
|
- **Deep reasoning**: `kimi-k2-thinking` (verification, synthesis)
|
|
- **Fast exploration**: `kimi-k2.5-nvfp4` (quick searches)
|
|
|
|
## Common Errors
|
|
|
|
### 500 Internal Server Error
|
|
```
|
|
InternalServerError2: 500 {"detail":"An unknown error occurred"}
|
|
```
|
|
|
|
**Causes:**
|
|
- Letta server resource issue
|
|
- Subagent creation endpoint failure
|
|
- Transient server error
|
|
|
|
**Resolution:**
|
|
- Retry the same request
|
|
- Try a different model
|
|
- Use direct shell search as fallback
|
|
|
|
### Unknown Model Error
|
|
```
|
|
Error: Unknown model "claude-sonnet-4"
|
|
Available models: ...
|
|
```
|
|
|
|
**Resolution:**
|
|
- Check available models list
|
|
- Use a valid model name from the list
|
|
- Do NOT use "claude" models (user preference)
|
|
|
|
## Best Practices
|
|
|
|
1. **Always specify model explicitly** to avoid ambiguity
|
|
2. **Use kimi-k2.5 or kimi-k2.5-nvfp4** as safe defaults
|
|
3. **Prefer lighter models** for simple exploration tasks
|
|
4. **Retry on 500 errors** - often transient
|
|
5. **Fall back to direct shell/Bash** if subagents fail repeatedly
|
|
|
|
## Example Usage
|
|
|
|
```typescript
|
|
Task({
|
|
description: "Explore codebase",
|
|
prompt: "Find all files that...",
|
|
subagent_type: "explore",
|
|
model: "kimi-k2.5" // Always specify
|
|
})
|
|
```
|
|
|
|
## Troubleshooting Workflow
|
|
|
|
1. Subagent fails with 500? → Retry with same model
|
|
2. Still failing? → Try different model (glm-4.7-flash, qwen3.5)
|
|
3. Still failing? → Use Bash/Grep/Glob directly
|
|
4. Document what worked for future reference
|
|
|
|
---
|
|
|
|
Last updated: 2026-03-21
|
|
Discovered during: Matrix bridge formatting investigation
|
|
Signed: Annie Tunturi <ani@wiuf.net>
|