LlamaIndex Tutorial (Python): debugging agent loops for intermediate developers

This tutorial shows you how to instrument a LlamaIndex agent loop in Python so you can see every tool call, intermediate thought boundary, and failure mode. You need this when an agent keeps repeating the same action, ignores a tool result, or burns tokens without making progress.

What You'll Need

• •Python 3.10+
• •llama-index
• •An OpenAI API key set as OPENAI_API_KEY
• •A terminal with pip
• •Basic familiarity with LlamaIndex agents and tools
• •A small local script or notebook where you can run and inspect logs

Install the package first:

pip install llama-index

Step-by-Step

1. •Start with a minimal agent setup and a tool that is easy to observe.
   The goal here is not to build a clever agent; it’s to create a loop you can inspect when something goes wrong.

import os
from llama_index.core.agent import ReActAgent
from llama_index.core.tools import FunctionTool
from llama_index.llms.openai import OpenAI

def get_account_status(account_id: str) -> str:
    if account_id == "12345":
        return "Account 12345 is active, balance is $1,240.50."
    return f"Account {account_id} not found."

status_tool = FunctionTool.from_defaults(fn=get_account_status)

llm = OpenAI(model="gpt-4o-mini", temperature=0)
agent = ReActAgent.from_tools(
    [status_tool],
    llm=llm,
    verbose=True,
)

2. •Add callback tracing so you can see the loop at runtime.
   verbose=True helps, but callbacks give you structured visibility into when the agent starts, calls tools, and finishes.

from llama_index.core.callbacks import CallbackManager, LlamaDebugHandler

debug_handler = LlamaDebugHandler(print_trace_on_end=True)
callback_manager = CallbackManager([debug_handler])

llm = OpenAI(
    model="gpt-4o-mini",
    temperature=0,
    callback_manager=callback_manager,
)

agent = ReActAgent.from_tools(
    [status_tool],
    llm=llm,
    verbose=True,
    callback_manager=callback_manager,
)

3. •Run a query that should require exactly one tool call.
   If the agent loops, this is where you’ll catch it immediately because the trace will show repeated reasoning/tool cycles instead of a clean finish.

response = agent.chat("Check account 12345 and tell me its status.")
print("\nFINAL RESPONSE:")
print(response)

print("\nRAW DEBUG TRACE:")
print(debug_handler.get_llm_inputs())

4. •Add a guardrail for loop detection in your own application code.
   In production, you do not want an agent spinning forever because a tool output was ambiguous or the model kept asking for the same action.

from collections import Counter

def detect_repeated_actions(trace_text: str) -> bool:
    lines = trace_text.splitlines()
    tool_lines = [line for line in lines if "tool" in line.lower() or "function" in line.lower()]
    counts = Counter(tool_lines)
    return any(count > 2 for count in counts.values())

trace_dump = "\n".join(map(str, debug_handler.get_llm_inputs()))
if detect_repeated_actions(trace_dump):
    raise RuntimeError("Possible agent loop detected: repeated tool activity.")

5. •Force a failure case so you can confirm your debugging path works before shipping it.
   A missing account ID is useful because it makes the model deal with uncertainty instead of coasting through a happy path.

bad_response = agent.chat("Check account 99999 and summarize the status.")
print("\nFAILURE CASE RESPONSE:")
print(bad_response)

trace_dump = "\n".join(map(str, debug_handler.get_llm_inputs()))
print("\nTRACE SIZE:", len(trace_dump))
print("LOOP DETECTED:", detect_repeated_actions(trace_dump))

Testing It

Run the script once with account 12345 and once with 99999. The first should produce one tool call and then a final answer; the second should either return “not found” cleanly or show where the reasoning gets stuck.

If you see repeated tool invocations for the same input, your issue is usually one of three things: weak tool output, ambiguous prompt instructions, or no stop condition in your app layer. The debug handler output should tell you which step is repeating.

For extra confidence, reduce temperature to 0 while debugging. That removes randomness and makes loop behavior much easier to reproduce.

Next Steps

• •Add custom callback handlers that write traces to JSON logs instead of printing to stdout.
• •Learn how to use structured outputs so agents stop guessing after a tool result.
• •Put a max-iteration or timeout wrapper around your agent calls before deploying to production.

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.