max-iteration-limit-recovery.md 3.17 KB

Max Tool-Calling Iteration Limit: Recovery Guide

What Happens

When an agent repeatedly polls an empty directory in a cron job, it may hit the maximum number of tool-calling iterations allowed. The session is then forcibly terminated with a message like:

You've reached the maximum number of tool-calling iterations allowed.
Please provide a final response summarizing what you've found and accomplished so far.

This is a hard stop. The agent cannot continue checking and must produce a final summary.

Why It Happens

The agent falls into an infinite polling loop, checking the same empty directory over and over. Each terminal call to ls or find counts as one tool iteration. Even though the directory is empty, the agent keeps checking, hoping a command file will appear.

This is a variant of the polling anti-pattern documented in references/cron-polling-anti-patterns.md.

Real-World Example

# Session log excerpt:
> su -c "ls -la /sdcard/VisualAgent/commands/"  → "total 0"
> su -c "ls -la /sdcard/VisualAgent/commands/"  → "total 0"
> su -c "ls -la /sdcard/VisualAgent/commands/"  → "total 0"
# ... 100+ identical checks later ...
> You've reached the maximum number of tool-calling iterations allowed.

Recovery: When You Hit the Limit

  1. Stop immediately — Do not try to make any more tool calls. The system has forced a final response.

  2. Summarize what you found — Report the directory state, any commands processed, and any results written.

  3. If nothing was done, respond [SILENT] — If the directory was empty and no commands were processed, the correct response is [SILENT] (nothing to report).

  4. Do NOT apologize for the loop — The user configured the cron job; hitting the limit is a system safeguard, not a user-facing error. Just report the state.

Prevention: How to Avoid Hitting the Limit

Single Check Pattern

# ONE check, then decide
FILES=$(su -c "find /sdcard/VisualAgent/commands/ -name '*.json' -type f 2>/dev/null")

if [ -z "$FILES" ]; then
    echo "[SILENT]"
    exit 0
fi

# Process all found files
for f in $FILES; do
    # ... execute ...
done

Never Loop Without Progress

If you must poll (e.g., waiting for a command to complete), ensure each iteration makes progress:

  • Check a different condition each time
  • Have a maximum retry count
  • Include a timeout
MAX_RETRIES=3
for i in $(seq 1 $MAX_RETRIES); do
    RESULT=$(su -c "cat /sdcard/VisualAgent/results/expected_result.json 2>/dev/null")
    if [ -n "$RESULT" ]; then
        break
    fi
    sleep 1
done

Use find Instead of ls

find with a file pattern tells you everything you need in one call:

# Lists all .json files, or empty if none
su -c "find /sdcard/VisualAgent/commands/ -name '*.json' -type f"

No need to ls the directory and then find the files separately.

Summary

Scenario Action
Directory empty after first check Respond [SILENT], stop
Hit iteration limit Produce final summary, no more tools
Need to wait for file Use find with max retries, not infinite ls
Multiple files to process List all with find, process in batch