[Feature] Lagent troubleshooting guide based on the WFGY 16-problem RAG / agent map

[onestardao]

Hi, thanks for Lagent. A lightweight agent framework is very helpful for people who want to prototype quickly.

I maintain WFGY, an MIT-licensed diagnostic framework that organises 16 common failure modes for RAG pipelines and agent systems:

• WFGY 16-problem RAG / agent ProblemMap
  https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md

The same map is already referenced in research contexts such as:

• ToolUniverse from the Harvard MIMS Lab (LLM tools benchmark including WFGY in the robustness / debugging section)
• Multimodal RAG Survey by the QCRI LLM Lab (curated survey of multimodal RAG where WFGY appears as a practical diagnostic framework)
• Rankify from the University of Innsbruck Data Science Group (RAG toolkit that points to the WFGY ProblemMap for failure analysis)

Motivation

Lagent users often build:

• small but deep tool-using agents
• RAG-backed workflows that run many steps
• multi-agent experiments glued together via simple interfaces.

Typical breakdowns include mis-interpreted retrieved chunks, long-chain drift, disappearing context between calls, or hard-to-debug multi-agent interactions. Those line up with several WFGY problems (No.1, No.2, No.3, No.7, No.13).

Proposal

I would like to propose a short “Troubleshooting with WFGY” section in the Lagent docs that:

1. Lists the subset of the 16 WFGY problems that are most common in Lagent scenarios.
2. Shows very small code or log snippets illustrating each pattern.
3. Links to the full ProblemMap README for users who want the complete taxonomy and mitigation ideas.

If this direction is acceptable, I can provide a first draft and adapt it to the current documentation structure.