My LlamaIndex agent keeps calling the same tool. Why?

Rius shows which tool repeats, with what arguments, and what the model saw between the calls, so you can find why your LlamaIndex agent loops. Open the trace, collapse the repeated calls into one row, and read the model’s input before each call. The pre-defined Tool Loop alert flags the pattern the next time it happens.

How it works

The LlamaIndex integration turns a query into a nested trace. Retrieval steps are retriever spans, embedding calls are embedding spans, and model calls are LLM spans with the model, token usage and messages. Rius computes the cost from those spans. Retrieved content and messages are content attributes, so they appear only while content capture is on.

A loop usually comes from one of three causes, and the trace tells them apart:

• The stop condition is never met. The agent repeats the same search with the same query because no result satisfies it. The tool results look the same on every call.
• A broken tool schema. The model retries the identical call and expects a different outcome. The arguments are identical and the results are errors or empty.
• A planner and executor cycling. They return to the same lookup and make no progress while the token bill grows.

The Tool Loop alert fires when the same tool is called with identical parameters at least 3 times in a row inside one trace within a 10-minute window. Calls count as identical when the tool name and normalized arguments match. At most one other tool call may sit between neighboring repeats, so a tool the agent returns to after other work does not fire. It fires once per trace and tool.

Set it up

1. Install the LlamaIndex instrumentation and call rius.init(api_key="ri_...", service_name="my-agent") before you build your query engines. The LlamaIndex integration page covers this in full, and the Integrations page covers the other frameworks.

pip install "glassflow-rius[llama-index]" llama-index

2. Open Traces and find a run that looped. A trace with an unusually high span count, token total or cost is a good candidate. Your own session ID also works: paste it into the search box on the Spans tab to list every span in that session.
3. On the Spans tab, open the All kinds menu and choose Tool to see only tool calls. Sort by Time and check whether the same tool name keeps appearing in a row.
4. Open the trace. Back-to-back calls of the same tool collapse into one row, such as fetch_article · 3 attempts · recovered. Expand the row and compare the attempts. If the arguments and the results match, the agent is not learning anything from the call.
5. Select the LLM span after a repeated call and open Input / Output. Switch to Since previous llm call to see what was added to the prompt. If the tool result is the only change, or nothing changed, the model is not getting what it needs to stop. Step through the spans with j and k to read each call in turn.
6. Check the context growth strip above the tree. Input tokens that climb with every call show a runaway history, and each bar selects the call it belongs to.
7. Under Alerts, check that Tool Loop is not disabled and has a channel attached. Pre-defined alerts can be disabled but not deleted.

Keep content capture on for the tools you want watched. Calls whose arguments were not captured are never counted as identical, so Tool Loop cannot fire on them.

What you get

• The cause in the trace. Repeated attempts sit in one row with their arguments and results, and the diff of the model’s input shows what it was given between calls.
• The cost of the loop. Tokens and a list-price cost estimate in US dollars show on the trace, and the context growth strip shows where the prompt ballooned.
• A catch next time. Tool Loop sends a notification when the same call repeats, with defaults of 3 identical calls and a 10-minute window. You can turn on renotify to repeat the message while a firing stays unacknowledged.
• A filterable record. Add a filter on the trace list and save the search for Everyone in this workspace so teammates can reopen the same runs. To hand a run to someone outside the workspace, use Share: a shared view carries metadata only, never span content.

For how this fits with the rest of your monitoring, see Monitor AI agents in production. Rius does not decide for you which of the three causes applies. You read it from the spans.

When something else fits

• Tool Loop watches for the same tool with identical arguments. If your agent loops with slightly different arguments each time, the alert does not fire, so use the trace views or a custom alert on cost or tokens instead.
• Tool Loop cannot be narrowed to one service. If one agent needs its own bar, a custom alert on a cost or token threshold is the better fit.
• If you need to fix the prompt, the tool schema or the agent’s stop condition, that change happens in your LlamaIndex code. Rius shows you where to make it.

Related