How does Rius detect tool loops in AI agents?

Rius detects a tool loop when the same tool is called with identical parameters at least 3 times in a row inside one trace within the time window. The pre-defined Tool Loop alert fires once per trace and tool. You can tune its settings or turn it off, but you cannot delete it.

How it works

Tool Loop is one of the curated detectors Rius ships, described on the Pre-defined alerts page. Repeated identical calls are the signature of an agent that has stopped making progress and is only burning tokens. Rius looks for that pattern in each trace.

• What counts as identical. Two calls are identical when the tool name and the normalized arguments match.
• What counts as a run. Taken in start order, the identical calls must form a run, with at most one other tool call between neighboring repeats. A tool the agent returns to after doing other work is routine, so it does not fire.
• When it fires. The alert fires when the run reaches the configured number of identical calls inside a single trace within the window. The default is at least 3, and 3 is also the minimum.
• How often. You get one firing per trace and tool.
• Content capture. Calls whose arguments were not captured, for example with content capture off, are never counted as identical.

The alert is built to catch cases like these:

• An agent repeats the same search with the same query because no result satisfies its stop condition.
• A broken tool schema makes the model retry the identical call and expect a different outcome.
• A planner and executor cycle on the same lookup while the token bill grows.

The alert has three settings:

An older Tool Loop alert saved with 2 identical calls now works as 3.

Set it up

Tool Loop is already part of Rius, so there is nothing to create. Your job is to make sure the data it needs arrives, then adjust it if the defaults do not fit.

1. Send traces that include your tool calls. With a global init(), the integrations you have installed are turned on automatically.

import rius
 
client = rius.init(
    api_key="ri_...",
    service_name="my-agent",
)

2. Keep content capture on, so the tool arguments reach Rius. It is on by default. If you have turned it off, set it back:

export RIUS_CAPTURE_CONTENT=true

3. Open the Tool Loop details page and set the number of identical calls and the time window. Raise the identical-calls setting if your agents legitimately repeat a call a few times. Lower the time window if you only care about tight loops.
4. Turn on Renotify if you want a repeat notification every N minutes while the firing stays open and unacknowledged.
5. Attach a channel on the same page. Rius delivers alerts to webhook, email and Slack. The Alerts overview covers how alerts and channels fit together.

Narrowing and turning it off. A narrowed version is a copy of a pre-defined alert that watches only what its filters match. Consistent Error Pattern and Swallowed Error can be narrowed. Tool Loop cannot, so it watches your whole workspace and you tune it through its settings. If you do not want it, disable it. You cannot delete a pre-defined alert, only disable it.

What you get

• A firing when an agent repeats the same tool call with the same arguments, so you see a stuck run while it is still burning tokens.
• Fewer false alarms. Calls spread across other work do not count, because at most one other tool call may sit between repeats.
• One firing per trace and tool, so a single loop does not flood your channels.
• Settings you control: the number of identical calls, the time window and whether notifications repeat.
• Delivery to the webhook, email or Slack channels you attach.
• A way to quiet it. You can disable Tool Loop at any time, and the alert stays in place so you can enable it again.

When something else fits

• If you want to be warned about the same error recurring across runs, use Consistent Error Pattern. If you want runs that errored internally but still reported success, use Swallowed Error. Both are on the Pre-defined alerts page, and you can narrow them by service, step or root service.
• If you need a threshold on cost, tokens, latency or error rate rather than a repeated call, a custom alert fits better.

Related