What is automatic function calling in the Gemini Python SDK, and when do you disable it?

## What AFC actually is The manual loop — detect calls, dispatch, append a function response, re-request — is mechanical, so the `google-genai` SDK will write it for you. Pass a plain Python function in `config.tools` and two things happen. First, **declaration derivation**: the SDK inspects the callable's signature, type annotations and docstring, and synthesises the `FunctionDeclaration` that would otherwise be hand-written. Your annotations become the parameter schema; your docstring becomes the description the model uses to decide when to call it. That makes annotations and docstrings load-bearing production artefacts rather than documentation. Second, **automatic execution**: when the model responds with a function call, the SDK calls your function in your process with the model's arguments, wraps the return value as a function response, appends both turns to the history, and issues the next request — repeating until the model answers in text. What comes back to your code is the final response, with the intermediate hops having happened invisibly. Crucially, this is *client-side*. Nothing about your function reaches Google. The execution model has not changed at all; only the authorship of the loop has. ## The controls AFC is configured through `automatic_function_calling` on the generation config, built from `types.AutomaticFunctionCallingConfig`: - `disable=True` turns it off entirely, so raw `function_call` parts come back to you and you write the loop. - `maximum_remote_calls` bounds how many automatic round trips the SDK will perform before it stops — 10 by default. This is the SDK's guard against a model that keeps calling forever, and it is not a substitute for your own budget checks. Note also that AFC only engages for **callables**. If you pass `types.FunctionDeclaration` objects, there is nothing for the SDK to execute, so you get the calls back regardless of the flag. ## When the convenience is right - Prototypes, notebooks and internal scripts, where the tools are pure reads and the failure mode is a stack trace you will read anyway. - Small, side-effect-free helpers — arithmetic, formatting, a lookup in an in-process dict. - Demos and evaluation harnesses where loop code would obscure the point. ## When to disable it **Side effects need a gate.** If a tool sends an email, charges a card, or writes to a database, you almost certainly want a decision point between "the model asked" and "it happened" — a policy check, an allow-list, or a human confirmation. AFC removes that seam. **Observability.** Production systems need per-call traces: which tool, which arguments, how long, what outcome. Writing the loop yourself is where those spans are emitted. Debugging a system whose tool hops are invisible is miserable. **Error semantics.** You will want timeouts, bounded retries, circuit breakers, and structured error payloads that let the model recover gracefully. Owning the loop is what makes those possible. **Concurrency.** When Gemini emits several independent calls in a turn, you want them dispatched concurrently with a bounded fan-out. Hand-rolled loops make that explicit. **Validation.** The schema constrains shape, not intent. Arguments derived from user text may be adversarial, so you want an explicit validation and authorization step before dispatch. **Cost control.** Each automatic hop is a full billed request carrying the whole accumulated history. Your own loop can enforce a token or currency budget and stop early, which `maximum_remote_calls` only approximates. **Streaming and UX.** If you want to show the user "looking up your orders…" between hops, you need to see the hops. ## A middle path You are not forced to choose globally. Because the setting lives on the request config, you can enable AFC for a read-only assistant path and disable it for the path that can mutate data, sharing the same client. Some teams also keep the callables as the single source of truth — for schema derivation — while disabling automatic execution, so declarations stay in sync with the code without giving up the loop. ## Portability note AFC is a property of the SDK, not of the Gemini API. Raw REST calls, and other language SDKs, do not necessarily give you the same behaviour, so code that depends on it does not transfer cleanly. If you are building an abstraction over several providers, write the loop explicitly — it is the only shape all of them share.