CrewAI Tutorial (Python): debugging agent loops for advanced developers

This tutorial shows you how to diagnose and stop agent loops in CrewAI before they burn tokens, time, or downstream SLAs. You’ll wire in verbose tracing, add hard stop conditions, and inspect intermediate state so you can see exactly why an agent keeps repeating itself.

What You'll Need

• •Python 3.10+
• •crewai
• •langchain-openai
• •An OpenAI API key set as OPENAI_API_KEY
• •A terminal with access to run Python scripts
• •Basic familiarity with Agent, Task, and Crew in CrewAI

Step-by-Step

1. •Start with a minimal crew that is likely to loop when the prompt is underspecified. The point here is not to build a good agent yet, but to create a reproducible failure you can inspect.

import os
from crewai import Agent, Task, Crew, Process
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="gpt-4o-mini",
    temperature=0,
    api_key=os.environ["OPENAI_API_KEY"],
)

researcher = Agent(
    role="Research Analyst",
    goal="Summarize the current state of a topic",
    backstory="You are precise and concise.",
    llm=llm,
    verbose=True,
)

task = Task(
    description="Explain why agent loops happen in multi-agent systems.",
    expected_output="A concise explanation.",
    agent=researcher,
)

crew = Crew(
    agents=[researcher],
    tasks=[task],
    process=Process.sequential,
    verbose=True,
)

result = crew.kickoff()
print(result)

2. •Turn on structured debugging signals so you can distinguish normal reasoning from repeated tool/task churn. In practice, most loops come from ambiguous goals, missing completion criteria, or agents being allowed to keep exploring after they already have enough information.

import logging
import os
from crewai import Agent, Task, Crew, Process
from langchain_openai import ChatOpenAI

logging.basicConfig(level=logging.INFO)

llm = ChatOpenAI(
    model="gpt-4o-mini",
    temperature=0,
    api_key=os.environ["OPENAI_API_KEY"],
)

debug_agent = Agent(
    role="Debugger",
    goal="Identify loop causes and stop when enough evidence exists",
    backstory="You inspect prompts for ambiguity and repeated behavior.",
    llm=llm,
    verbose=True,
)

debug_task = Task(
    description=(
        "Analyze this failure mode: the agent keeps repeating the same answer "
        "without converging. Return the top 3 likely causes."
    ),
    expected_output="Three causes with concrete mitigation steps.",
    agent=debug_agent,
)

crew = Crew(
    agents=[debug_agent],
    tasks=[debug_task],
    process=Process.sequential,
    verbose=True,
)
print(crew.kickoff())

3. •Add a second agent whose only job is to verify output completeness. This is the simplest production pattern for stopping loops: one agent generates, another checks whether the response satisfies a strict contract.

import os
from crewai import Agent, Task, Crew, Process
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="gpt-4o-mini",
    temperature=0,
    api_key=os.environ["OPENAI_API_KEY"],
)

writer = Agent(
    role="Writer",
    goal="Produce a direct answer with no repetition",
    backstory="You write short answers and stop once requirements are met.",
    llm=llm,
)

checker = Agent(
    role="Checker",
    goal="Detect repetition and incomplete answers",
    backstory="You reject outputs that repeat ideas or miss constraints.",
    llm=llm,
)

write_task = Task(
    description="Draft a 5-bullet explanation of why an agent might loop.",
    expected_output="Exactly 5 bullets, no repeated points.",
    agent=writer,
)

check_task = Task(
    description="Review the draft for repetition and missing constraints.",
    expected_output="Pass/fail verdict plus fixes if needed.",
    agent=checker,
)

crew = Crew(
        agents=[writer, checker],
        tasks=[write_task, check_task],
        process=Process.sequential,
        verbose=True,
)
print(crew.kickoff())

4. •Put hard boundaries on what the agent is allowed to do. If your version of CrewAI supports tools or iteration limits in your setup, use them; otherwise enforce stopping behavior through task wording and explicit output shape.

import os
from crewai import Agent, Task, Crew, Process
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="gpt-4o-mini",
   temperature=0,
   api_key=os.environ["OPENAI_API_KEY"],
)

bounded_agent = Agent(
   role="Bounded Analyst",
   goal="Answer once and stop",
   backstory="You never repeat yourself and always honor output constraints.",
   llm=llm,
   verbose=True,
)

bounded_task = Task(
   description=(
       "Explain how to debug CrewAI loops in exactly 4 numbered steps. "
       "Do not add extra commentary."
   ),
   expected_output="Exactly 4 numbered steps.",
   agent=bounded_agent,
)

crew = Crew(
   agents=[bounded_agent],
   tasks=[bounded_task],
   process=Process.sequential,
   verbose=True,
)
print(crew.kickoff())

5. •Inspect the raw result and compare it against your expected contract. In real debugging sessions, I also log prompt text, task descriptions, and final output side by side so I can see whether the loop came from the model or from my own orchestration.

import os
from crewai import Agent, Task, Crew, Process
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
   model="gpt-4o-mini",
   temperature=0,
   api_key=os.environ["OPENAI_API_KEY"],
)

agent = Agent(
   role="Inspector",
   goal="Return one clean answer",
   backstory="You produce bounded outputs only.",
   llm=llm,
   verbose=True,
)

task_text = "Summarize three reasons an agent may enter a loop."
task = Task(description=task_text, expected_output="Three reasons.", agent=agent)

crew = Crew(agents=[agent], tasks=[task], process=Process.sequential, verbose=True)
result = crew.kickoff()

print("TASK:", task_text)
print("RESULT:", result)

Testing It

Run the script against a simple prompt first and confirm you get one pass through each task without repeated sections. Then intentionally weaken the expected_output text and see whether verbosity reveals where the model starts drifting into repetition.

If you still see looping behavior, tighten the task contract further:

• •specify exact bullet counts
• •forbid rephrasing previously stated points
• •require a final “done” style ending only once

For production systems, test three cases:

• •a well-specified task that should finish immediately
• •an underspecified task that tends to wander
• •a multi-agent handoff where one agent validates completion before the next starts

Next Steps

• •Add custom tools with strict input/output schemas so agents have less room to ramble.
• •Wrap Crew runs with timeout and retry logic at the application layer.
• •Learn how to use tracing or callbacks to capture intermediate reasoning signals without exposing them to users.

Keep learning

• •The complete AI Agents Roadmap — my full 8-step breakdown
• •Free: The AI Agent Starter Kit — PDF checklist + starter code
• •Work with me — I build AI for banks and insurance companies

By Cyprian Aarons, AI Consultant at Topiax.