Heuristic:Openai Openai node RunTools Loop Limit
| Knowledge Sources | |
|---|---|
| Domains | Function_Calling, Safety |
| Last Updated | 2026-02-15 12:00 GMT |
Overview
Default limit of 10 chat completion rounds in `runTools()` to prevent infinite tool-calling loops and unbounded API costs.
Description
The `Completions.runTools()` helper automates the multi-turn tool calling loop: it sends a request, checks for tool calls, executes them, appends results, and repeats. Without a limit, a model that persistently requests tool calls could loop indefinitely, consuming API tokens. The SDK defaults to a maximum of 10 rounds (`DEFAULT_MAX_CHAT_COMPLETIONS = 10`), configurable via the `maxChatCompletions` option. Each round is a separate API request, so `max_tokens` applies per-round, not across the entire run.
Usage
This heuristic applies when using `chat.completions.runTools()` or `chat.completions.stream()` with tools. Increase `maxChatCompletions` for workflows that legitimately require many tool invocations (e.g., multi-step agent loops). Decrease it for cost-sensitive applications or when the expected number of rounds is small.
The Insight (Rule of Thumb)
- Action: Set `maxChatCompletions` in the `runTools()` options to control the maximum number of API round-trips.
- Value: Default is 10. Set higher for complex agent workflows; lower for simple tool calls.
- Trade-off: Higher limits allow more complex interactions but increase cost and latency. Lower limits prevent runaway loops but may truncate legitimate multi-step operations.
- Important: `max_tokens` is per-request, not per-run. A 10-round run with `max_tokens: 1000` could generate up to 10,000 tokens total.
Reasoning
Unbounded loops are a common failure mode in agent systems. The model may repeatedly request the same tool call, request non-existent tools, or enter a cycle. A default of 10 rounds provides enough headroom for typical use cases (most tool-calling interactions resolve in 1-3 rounds) while preventing runaway costs. The value was chosen as a pragmatic default that balances capability with safety.
Code Evidence
Default constant from `src/lib/AbstractChatCompletionRunner.ts:26`:
const DEFAULT_MAX_CHAT_COMPLETIONS = 10;
Runner options interface from `src/lib/AbstractChatCompletionRunner.ts:27-30`:
export interface RunnerOptions extends RequestOptions {
/** How many requests to make before canceling. Default 10. */
maxChatCompletions?: number;
}