Heuristic:Googleapis Python genai AFC Max Remote Calls Limit
| Knowledge Sources | |
|---|---|
| Domains | Function_Calling, Safety |
| Last Updated | 2026-02-15 14:00 GMT |
Overview
Automatic Function Calling (AFC) is capped at 10 remote calls by default to prevent infinite loops between the model and user-defined functions.
Description
When AFC is enabled, the SDK enters a loop where the model can request function calls, the SDK executes them locally, and sends results back to the model. Without a limit, a misbehaving model could trigger an infinite loop of function calls, consuming API quota and compute resources.
The SDK imposes a hard default of 10 maximum remote calls per `generate_content` invocation. Each iteration of the AFC loop decrements a counter; when it reaches zero, the loop terminates and returns the last response. The limit is configurable via `AutomaticFunctionCallingConfig.maximum_remote_calls`.
Usage
This heuristic applies whenever you use Automatic Function Calling with `generate_content`. Consider adjusting the limit when:
- Complex multi-step tasks: Increase beyond 10 if your agent legitimately needs more tool-use rounds.
- Simple retrieval: Decrease to 1-3 for single-tool lookups to reduce latency and cost.
- Cost control: Each remote call is a separate API request; lower limits reduce billing.
The Insight (Rule of Thumb)
- Action: Set `maximum_remote_calls` in `AutomaticFunctionCallingConfig` to control the AFC loop iteration limit.
- Value: Default is 10. Set to 0 or negative to disable AFC entirely (with a warning logged).
- Trade-off: Higher values allow more complex multi-step reasoning but risk runaway loops and increased API costs. Lower values are safer but may truncate legitimate multi-step workflows.
- Detection: The SDK logs `'Reached max remote calls for automatic function calling.'` at INFO level when the limit is hit.
Reasoning
The default of 10 was chosen as a practical balance:
- Most function-calling workflows complete in 1-3 rounds (single tool lookup, retrieve-then-process).
- Complex agentic workflows may need 5-8 rounds for multi-step planning.
- 10 rounds provides headroom for complex cases while preventing truly runaway loops.
- Setting to 0: The SDK explicitly checks for `<= 0` and logs a warning before disabling AFC, providing a clean opt-out mechanism.
- Default tracking: The SDK distinguishes between the default value of 10 and an explicitly set value of 10, so warnings about disabling AFC only trigger when the user explicitly configured a zero/negative value (not when the default is in effect).
Code Evidence
Default constant from `_extra_utils.py:55`:
_DEFAULT_MAX_REMOTE_CALLS_AFC = 10
AFC loop with decrementing counter from `models.py:5610-5644`:
remaining_remote_calls_afc = _extra_utils.get_max_remote_calls_afc(
parsed_config
)
logger.info(
f'AFC is enabled with max remote calls: {remaining_remote_calls_afc}.'
)
automatic_function_calling_history: list[types.Content] = []
response = types.GenerateContentResponse()
i = 0
while remaining_remote_calls_afc > 0:
i += 1
response = self._generate_content(
model=model, contents=contents, config=parsed_config
)
# ... process function calls ...
remaining_remote_calls_afc -= 1
if remaining_remote_calls_afc == 0:
logger.info('Reached max remote calls for automatic function calling.')
Disable AFC when max_remote_calls <= 0 from `_extra_utils.py:424-432`:
if (
config_model.automatic_function_calling.maximum_remote_calls
and int(config_model.automatic_function_calling.maximum_remote_calls) <= 0
):
logger.warning(
'max_remote_calls... is less than or equal to 0. '
'Disabling automatic function calling.'
)
return True