Debugging a Crew That Won't Converge on an Answer

Q: Why does verbose show clever thoughts but bad outputs?

Thought text is not graded. expected_output and tool results are. Tighten the contract and tool reliability.

Q: What output should CI assert?

Structured fields or checklist items from expected_output, plus max token/time budgets, not full prose equality.

Q: Do callbacks help?

Yes. step_callback / task_callback can emit metrics the terminal scrollback loses.

A crew that "won't converge" usually loops on tools, re-delegates forever, or hands off mush between agents until max_iter or your wallet stops it.

Use this cheatsheet to find whether the bug is task design, role overlap, tools, process, or missing stop rails.

How to Use This Cheatsheet

Reproduce once with verbose=True and saved logs (output_log_file).
Walk A → F in order; most failures die in A-C.
Change one variable per run (expected_output, tools, process, model).
Capture tasks_output and token usage after every experiment.

A - Capture Evidence First

Check	What to record
[ ] Verbose trace	Which agent, which tool, which thought loops
[ ] Per-task outputs	`result.tasks_output` raw text
[ ] Token usage	`result.token_usage` / `crew.usage_metrics`
[ ] Inputs	Exact `kickoff(inputs=...)` payload
[ ] Process mode	sequential vs hierarchical
[ ] Caps	`max_iter`, `max_execution_time`, `max_rpm`, retries

Without artifacts you will tune folklore.

B - Task Contract Failures (Most Common)

Symptom	Likely cause	Fix
Agent rambles / never "finishes"	Weak or missing `expected_output`	Write measurable acceptance text
Writer invents research	Missing `context=[research_task]`	Wire context; forbid tools on writer
Every task restates the whole mission	Descriptions too broad	Split tickets; one outcome each
Placeholder leftovers like `{topic}`	Inputs not passed	Pass `kickoff(inputs={"topic": ...})`
Output format wars	Contradictory description vs expected_output	Make them agree

Litmus test: could a human contractor finish the task without chatting back? If not, the task is not ready for a crew.

C - Role and Tool Thrash

Symptom	Likely cause	Fix
Two agents do the same search	Overlapping goals + shared tools	Least-privilege tool lists
Agent calls the same tool with tiny arg changes	Bad tool errors or vague description	Return clear errors; tighten tool docs
Delegation ping-pong	`allow_delegation=True` without need	Default false on workers
"I need more info" loops	Goal asks for perfection	Goal: best-effort under caps
Tool auth failures every turn	Missing env secrets	Fix credentials; fail fast

D - Process-Specific Issues

Sequential

Symptom	Fix
Stage N ignores stage N-1	Add `context`; shrink stage N-1 into structured notes
Early stage dumps a novel	Cap length in `expected_output` ("max 15 bullets")
Late stage cannot recover bad notes	Add a thin normalize task; do not hope

Hierarchical

Symptom	Fix
Manager reassigns endlessly	Clarify worker roles; strengthen manager goal to stop criteria
Manager does the work itself poorly	Provide capable workers; constrain manager to assign/review
Missing manager config errors	Set `manager_llm` or `manager_agent`
Cost explosion	Cap iterations; switch stable pipelines back to sequential

E - Stop Rails Checklist

Agent max_iter set intentionally (default may be higher than you want for demos).
max_execution_time on long tool users.
max_retry_limit not hiding persistent tool bugs.
Crew max_rpm if provider 429s cause silent stalls/retries.
Product budget (wall clock + dollars) outside the framework.
respect_context_window understood (summarization vs hard fail).

Prompts do not stop runaway loops. Host caps do.

F - Memory / Knowledge Confusion

Symptom	Fix
Answers cite stale facts	Reset memory/knowledge in dev; check storage dir
Irrelevant recalls derail tasks	Narrow scopes; tune thresholds; disable memory to A/B
Embed dimension errors	Pin embedder; reset stores after model changes
Believes chat history is memory	Wire the correct layer (context vs Memory vs Knowledge)

G - Minimal Bisect Procedure

Single agent, single task with the same goal. If this fails, do not debug multi-agent yet.
Add second agent without tools and explicit context. Confirm handoff text quality.
Add one tool to the discoverer only.
Enable memory only after the pipeline converges cold.
Try hierarchical last, never first, when debugging convergence.

H - Logging Snippets

crew = Crew(
    agents=[...],
    tasks=[...],
    verbose=True,
    output_log_file="debug_crew.json",
)
 
result = crew.kickoff(inputs={"topic": "convergence debugging"})
for t in result.tasks_output:
    print("====", getattr(t, "agent", None))
    print((t.raw or "")[:1000])
print("tokens", result.token_usage)

Replay mindset (CLI - verify at build): inspect latest task outputs, then crewai replay -t <task_id> after fixing a downstream task instead of re-running expensive upstream research.

I - When It Is Not a Crew Bug

Provider outages / rate limits (check raw API errors).
Model too weak for tool schemas (upgrade or simplify tools).
Eval expects creativity but task demands strict format (align metrics).
Human requirements still ambiguous (no framework fixes that).

FAQs

What does "converge" mean here?

The crew produces an acceptable final artifact within iteration/time/cost caps without repetitive no-progress cycles.

Should I raise max_iter to fix loops?

No as a first move. Raising caps hides the bug and increases spend. Fix tasks and tools first.

Why does verbose show clever thoughts but bad outputs?

Thought text is not graded. expected_output and tool results are. Tighten the contract and tool reliability.

Can hierarchical process reduce thrash?

Sometimes, when you need review. Often it adds thrash if workers already form a clean pipeline.

How do I detect no-progress loops programmatically?

Log tool name+args hashes and task output hashes; stop or alert when duplicates exceed a threshold.

Is planning a fix for non-convergence?

Rarely by itself. Planning helps organization; it cannot repair contradictory goals or broken tools.

Should I switch models while debugging?

Only after contracts are clear. Otherwise you cannot tell prompt bugs from model gaps.

What output should CI assert?

Structured fields or checklist items from expected_output, plus max token/time budgets, not full prose equality.

Do callbacks help?

Yes. step_callback / task_callback can emit metrics the terminal scrollback loses.

When should I abandon multi-agent?

When a single agent with one or two tools meets quality targets cheaper. Multi-agent is a cost, not a badge.

CrewAI Basics - minimal working crew
Defining Agent Roles, Goals, and Backstories - fix role overlap
Sequential vs Hierarchical Crew Processes - process misfile
Building a Custom Tool for a CrewAI Agent - tool errors and schemas
CrewAI 1.14's Pluggable Memory, Knowledge, and RAG Backends - stale recall issues
CrewAI Best Practices - prevention checklist

Stack versions: Pins from the category manifest (verify at build): OpenRouter (~315+ models, July 2026 pricing/fees); LangGraph 1.0+; CrewAI 1.14+; Microsoft Agent Framework 1.0; Vercel AI SDK 6; Pydantic AI (latest); LlamaIndex (latest); OpenAI Agents SDK (latest + MCP); MCP (Linux Foundation governance); A2A (HTTP+SSE+JSON-RPC 2.0); Solana @solana/web3.js + @solana/spl-token.

Use this cheatsheet to find whether the bug is task design, role overlap, tools, process, or missing stop rails.

How to Use This Cheatsheet

Reproduce once with verbose=True and saved logs (output_log_file).
Walk A → F in order; most failures die in A-C.
Change one variable per run (expected_output, tools, process, model).
Capture tasks_output and token usage after every experiment.

A - Capture Evidence First

Check	What to record
[ ] Verbose trace	Which agent, which tool, which thought loops
[ ] Per-task outputs	`result.tasks_output` raw text
[ ] Token usage	`result.token_usage` / `crew.usage_metrics`
[ ] Inputs	Exact `kickoff(inputs=...)` payload
[ ] Process mode	sequential vs hierarchical
[ ] Caps	`max_iter`, `max_execution_time`, `max_rpm`, retries

Without artifacts you will tune folklore.

B - Task Contract Failures (Most Common)

Symptom	Likely cause	Fix
Agent rambles / never "finishes"	Weak or missing `expected_output`	Write measurable acceptance text
Writer invents research	Missing `context=[research_task]`	Wire context; forbid tools on writer
Every task restates the whole mission	Descriptions too broad	Split tickets; one outcome each
Placeholder leftovers like `{topic}`	Inputs not passed	Pass `kickoff(inputs={"topic": ...})`
Output format wars	Contradictory description vs expected_output	Make them agree

Litmus test: could a human contractor finish the task without chatting back? If not, the task is not ready for a crew.

C - Role and Tool Thrash

Symptom	Likely cause	Fix
Two agents do the same search	Overlapping goals + shared tools	Least-privilege tool lists
Agent calls the same tool with tiny arg changes	Bad tool errors or vague description	Return clear errors; tighten tool docs
Delegation ping-pong	`allow_delegation=True` without need	Default false on workers
"I need more info" loops	Goal asks for perfection	Goal: best-effort under caps
Tool auth failures every turn	Missing env secrets	Fix credentials; fail fast

D - Process-Specific Issues

Sequential

Symptom	Fix
Stage N ignores stage N-1	Add `context`; shrink stage N-1 into structured notes
Early stage dumps a novel	Cap length in `expected_output` ("max 15 bullets")
Late stage cannot recover bad notes	Add a thin normalize task; do not hope

Hierarchical

Symptom	Fix
Manager reassigns endlessly	Clarify worker roles; strengthen manager goal to stop criteria
Manager does the work itself poorly	Provide capable workers; constrain manager to assign/review
Missing manager config errors	Set `manager_llm` or `manager_agent`
Cost explosion	Cap iterations; switch stable pipelines back to sequential

E - Stop Rails Checklist

Agent max_iter set intentionally (default may be higher than you want for demos).
max_execution_time on long tool users.
max_retry_limit not hiding persistent tool bugs.
Crew max_rpm if provider 429s cause silent stalls/retries.
Product budget (wall clock + dollars) outside the framework.
respect_context_window understood (summarization vs hard fail).

Prompts do not stop runaway loops. Host caps do.

F - Memory / Knowledge Confusion

Symptom	Fix
Answers cite stale facts	Reset memory/knowledge in dev; check storage dir
Irrelevant recalls derail tasks	Narrow scopes; tune thresholds; disable memory to A/B
Embed dimension errors	Pin embedder; reset stores after model changes
Believes chat history is memory	Wire the correct layer (context vs Memory vs Knowledge)

G - Minimal Bisect Procedure

Single agent, single task with the same goal. If this fails, do not debug multi-agent yet.
Add second agent without tools and explicit context. Confirm handoff text quality.
Add one tool to the discoverer only.
Enable memory only after the pipeline converges cold.
Try hierarchical last, never first, when debugging convergence.

H - Logging Snippets

crew = Crew(
    agents=[...],
    tasks=[...],
    verbose=True,
    output_log_file="debug_crew.json",
)
 
result = crew.kickoff(inputs={"topic": "convergence debugging"})
for t in result.tasks_output:
    print("====", getattr(t, "agent", None))
    print((t.raw or "")[:1000])
print("tokens", result.token_usage)

Replay mindset (CLI - verify at build): inspect latest task outputs, then crewai replay -t <task_id> after fixing a downstream task instead of re-running expensive upstream research.

I - When It Is Not a Crew Bug

Provider outages / rate limits (check raw API errors).
Model too weak for tool schemas (upgrade or simplify tools).
Eval expects creativity but task demands strict format (align metrics).
Human requirements still ambiguous (no framework fixes that).

FAQs

What does "converge" mean here?

The crew produces an acceptable final artifact within iteration/time/cost caps without repetitive no-progress cycles.

Should I raise max_iter to fix loops?

No as a first move. Raising caps hides the bug and increases spend. Fix tasks and tools first.

Why does verbose show clever thoughts but bad outputs?

Thought text is not graded. expected_output and tool results are. Tighten the contract and tool reliability.

Can hierarchical process reduce thrash?

Sometimes, when you need review. Often it adds thrash if workers already form a clean pipeline.

How do I detect no-progress loops programmatically?

Log tool name+args hashes and task output hashes; stop or alert when duplicates exceed a threshold.

Is planning a fix for non-convergence?

Rarely by itself. Planning helps organization; it cannot repair contradictory goals or broken tools.

Should I switch models while debugging?

Only after contracts are clear. Otherwise you cannot tell prompt bugs from model gaps.

What output should CI assert?

Structured fields or checklist items from expected_output, plus max token/time budgets, not full prose equality.

Do callbacks help?

Yes. step_callback / task_callback can emit metrics the terminal scrollback loses.

When should I abandon multi-agent?

When a single agent with one or two tools meets quality targets cheaper. Multi-agent is a cost, not a badge.

CrewAI Basics - minimal working crew
Defining Agent Roles, Goals, and Backstories - fix role overlap
Sequential vs Hierarchical Crew Processes - process misfile
Building a Custom Tool for a CrewAI Agent - tool errors and schemas
CrewAI 1.14's Pluggable Memory, Knowledge, and RAG Backends - stale recall issues
CrewAI Best Practices - prevention checklist

Stack versions: Pins from the category manifest (verify at build): OpenRouter (~315+ models, July 2026 pricing/fees); LangGraph 1.0+; CrewAI 1.14+; Microsoft Agent Framework 1.0; Vercel AI SDK 6; Pydantic AI (latest); LlamaIndex (latest); OpenAI Agents SDK (latest + MCP); MCP (Linux Foundation governance); A2A (HTTP+SSE+JSON-RPC 2.0); Solana @solana/web3.js + @solana/spl-token.

Debugging a Crew That Won't Converge on an Answer

Search Documentation

Debugging a Crew That Won't Converge on an Answer