LlamaIndex Tutorial (Python): debugging agent loops for beginners

This tutorial shows you how to spot and debug agent loops in a LlamaIndex Python app before they burn tokens or hang your process. You’ll build a small agent, instrument its steps, and add guardrails so you can see exactly why it keeps calling tools instead of finishing.

What You'll Need

• •Python 3.10+
• •llama-index
• •llama-index-llms-openai
• •An OpenAI API key in OPENAI_API_KEY
• •A terminal and a basic Python project
• •Optional: python-dotenv if you want to load env vars from a .env file

Step-by-Step

1. •Start with a clean install and set your API key. For debugging loops, keep the setup minimal so you can tell whether the problem is in the agent logic, the tool, or the model behavior.

pip install llama-index llama-index-llms-openai python-dotenv
export OPENAI_API_KEY="your-key-here"

2. •Build one simple tool that returns deterministic output. Agent loops are easier to debug when the tool behavior is stable and obvious.

from llama_index.core.tools import FunctionTool

def get_account_balance(account_id: str) -> str:
    return f"Account {account_id} balance is $1,250.00"

balance_tool = FunctionTool.from_defaults(
    fn=get_account_balance,
    name="get_account_balance",
    description="Get the balance for a bank account by account_id.",
)

3. •Create an agent with a low iteration limit and verbose logging enabled. This is the fastest way to catch repeated tool calls before they become infinite-looking loops.

from llama_index.llms.openai import OpenAI
from llama_index.core.agent.workflow import FunctionAgent

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

agent = FunctionAgent(
    tools=[balance_tool],
    llm=llm,
    system_prompt=(
        "You are a banking assistant. "
        "Use tools only when needed, then answer directly."
    ),
    max_iterations=3,
)

4. •Run a question that should finish in one tool call, then inspect the response path. If the agent keeps calling the same tool, you’ve reproduced the loop in a controlled way.

response = await agent.run(
    "What is the balance for account 12345?"
)

print(response)

5. •Add explicit tracing around each step so you can see whether the loop is caused by bad tool output or weak instructions. In practice, most loops come from ambiguous prompts, non-final tool outputs, or tools that return text the model thinks needs more processing.

from typing import List

class DebugToolWrapper:
    def __init__(self, tool):
        self.tool = tool

    def __call__(self, *args, **kwargs):
        print(f"[tool-call] {self.tool.metadata.name} args={args} kwargs={kwargs}")
        result = self.tool(*args, **kwargs)
        print(f"[tool-result] {result}")
        return result

debug_balance_tool = FunctionTool.from_defaults(
    fn=DebugToolWrapper(get_account_balance),
    name="get_account_balance",
    description="Get the balance for a bank account by account_id.",
)

6. •If you still see repeated calls, tighten the prompt and make the tool output more final. The model should not have to infer whether it has enough information; tell it exactly when to stop.

agent = FunctionAgent(
    tools=[debug_balance_tool],
    llm=llm,
    system_prompt=(
        "You are a banking assistant.\n"
        "- Call get_account_balance at most once.\n"
        "- After receiving the balance, answer directly.\n"
        "- Do not ask follow-up questions unless account_id is missing."
    ),
    max_iterations=2,
)

response = await agent.run("Check account 12345 balance.")
print(response)

Testing It

Run the script and confirm you see exactly one tool call for a direct balance question. If you see multiple calls with the same arguments, your loop is usually coming from either an underspecified system prompt or a tool response that looks incomplete.

Try three inputs: one with a valid account ID, one missing an account ID, and one asking an unrelated question. A healthy setup should call the tool only for the valid account case and stop quickly on everything else.

If you want deeper visibility, compare runs with temperature=0 versus higher values. For debugging loops, keep temperature at zero until behavior is stable.

Next Steps

• •Add structured outputs so your agent can distinguish “done” from “needs another tool call.”
• •Learn LlamaIndex callbacks and tracing so you can inspect every step of an agent run.
• •Wrap external APIs with validation and timeouts before exposing them as tools to agents.

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.