---
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

### 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>