Redflag/system/subagent_usage_guide.md

description, limit

description	limit
Guide for running subagents effectively - model selection and troubleshooting	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

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