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