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

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

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