92 lines
2.4 KiB
Markdown
92 lines
2.4 KiB
Markdown
---
|
|
description: Guide for running subagents effectively - model selection and troubleshooting
|
|
limit: 2000
|
|
---
|
|
# 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
|
|
|
|
### Preferred Models
|
|
- **For exploration/research**: `kimi-k2.5` or `kimi-k2.5-nvfp4`
|
|
- **For coding tasks**: `qwen3-coder` or `glm-4.7-flash`
|
|
- **For complex reasoning**: `kimi-k2-thinking` or `deepseek-r1`
|
|
|
|
## 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
|