Agentic Loops

Agentic Loops

An agentic loop is the core execution cycle. Understanding how to configure and debug it will save you a lot of time when building complex workflows.

Max Steps

Set a maxSteps limit to prevent runaway loops. When reached, the agent returns whatever it has so far along with a reason for stopping.

Stopping Conditions

Define custom stopping conditions based on the agent’s output, tool results, or elapsed time. This gives you fine-grained control over when a task is considered done.

Retry Strategy

Configure automatic retries with exponential backoff for tool failures or model errors. Set a max retry count per step to prevent infinite retries.

The loop in detail

An agentic loop is the cycle of reasoning steps the agent takes from receiving a goal to completing it. Understanding how Queue executes this loop — and how to configure it — gives you precise control over agent behavior.

Step structure

Each step in a loop consists of: a model call with the full context, an optional tool call emitted by the model, execution of that tool call, and appending the result to context before the next step.

A run with no tool calls is a single step. A run with 10 tool calls is at least 10 steps. Complex tasks can take 30-50 steps before completing.

Configuring the loop

max_steps

Sets a hard limit on the number of reasoning steps. When hit, the agent stops and returns its current state with stop_reason: max_steps_reached. Set this low during development to catch runaway loops early.

timeout_seconds

Wall-clock time limit for the entire run. If the agent is mid-step when the timeout hits, the current step is completed and the run ends gracefully.

stop_conditions

Define custom stopping conditions in code. Queue evaluates them after each step. Useful for tasks with variable completion criteria — for example, stopping when all tests pass or when a specific file has been modified.

Retry behavior

Queue retries on transient failures: network errors, model API timeouts, and tool execution errors. Retries use exponential backoff with jitter. Configure max retries per step and the backoff ceiling in queue.yaml:

retry: max_attempts: 3 backoff_multiplier: 2 max_backoff_seconds: 30

Parallel steps

Queue supports parallel tool execution: when the model emits multiple independent tool calls in a single step, Queue runs them concurrently and merges the results before the next reasoning step. This significantly speeds up tasks that involve reading many files.

Debugging a stuck loop

If an agent seems to be looping without progress, check the trace. Common causes: the model keeps calling a tool that returns an error, the goal is ambiguous and the agent cannot determine when it is done, or the context window is full and compression is losing key information.

Use queue trace --verbose <run-id> to see the full text of each model call and every tool result, which usually reveals the issue immediately.