Refactor function calling to incorporate the tool declaration automatically into the underlying model processors. This avoids duplicating tool declaration in both models and function calling processor which could lead to errors and inconsistencies. This also makes function calling more robust with the ability to define function calling processor on top of other function calling processors, adding capabilities incrementally on other processors.

To that end, we added an "add_tool" method to the model processors and to chain processors and function calling. The tools can then be registered after a model processor is created.

The new code is backward compatible: if the model has registered tools in its constructor, the function calling method will not duplicate the tools.

PiperOrigin-RevId: 891591218

Author: aelissee

documentation/docs/concepts/function-calling.md

@@ -85,38 +85,21 @@ async def smart_home_state() -> AsyncIterable[str]:
 
 ## Configuring the Processor
 
-To enable function calling, you must:
-
-1.  Let the model know which tools are available by providing the tool list in
-    the model config.
-
-2.  **Disable** any built-in automatic function calling in the model (e.g., for
-    `GenaiModel`, set `automatic_function_calling=...disable=True`).
-
-3.  Wrap the model processor with `FunctionCalling`, providing the same list of
-    functions for execution.
+To enable function calling, wrap your model with `FunctionCalling` and provide
+the list of functions:
 
 ```python
 from genai_processors.core import function_calling, genai_model
-from google.genai import types as genai_types
 
-tools = [get_weather, set_alarm]
-
-# 1 & 2: Configure model and disable its internal AFC.
-model = genai_model.GenaiModel(
-    model_name="gemini-2.0-flash",
-    generate_content_config=genai_types.GenerateContentConfig(
-        tools=tools,
-        automatic_function_calling=genai_types.AutomaticFunctionCallingConfig(
-            disable=True
-        ),
-    ),
-)
+model = genai_model.GenaiModel(model_name="gemini-2.0-flash")
 
-# 3. Wrap with FunctionCalling.
-agent = function_calling.FunctionCalling(model=model, fns=tools)
+agent = function_calling.FunctionCalling(model=model, fns=[get_weather, set_alarm])
 ```
 
+Tool declarations are **automatically registered** on the model via
+`register_tools()`. There is no need to pass `tools=` to the model's config or to
+manually disable automatic function calling — `FunctionCalling` handles both.
+
 ## Async Tools and Real-Time Interaction
 
 `FunctionCalling` is designed to work with both turn-based and real-time
@@ -203,13 +186,11 @@ additional tools you can add to your model's tool list:
 ```python
 from genai_processors.core import function_calling
 
-# We explicitly add the list_fc and cancel_fc functions from function calling
-# to let the model cancel async function calls. If tools contains only synced
-# functions, list_fc and cancel_fc can be omitted.
-tools = [my_async_tool, function_calling.list_fc, function_calling.cancel_fc]
-model = genai_model.GenaiModel(..., tools=tools, ...)
-
-agent = function_calling.FunctionCalling(model=model, fns=tools, is_bidi_model=True)
+agent = function_calling.FunctionCalling(
+    model=model,
+    fns=[my_async_tool, function_calling.list_fc, function_calling.cancel_fc],
+    is_bidi_model=True,
+)
 ```
 
 ## Using MCP (Model Context Protocol)

documentation/docs/development/built-in-processors.md

@@ -278,24 +278,14 @@ results back to the model.
 
 ```python
 from genai_processors.core import function_calling
-from google.genai import types as genai_types
 
 def get_weather(city: str) -> str:
     # ... implementation ...
     return f"Weather in {city} is sunny."
 
-tools = [get_weather]
-model_with_tools = genai_model.GenaiModel(
-    ...,
-    generate_content_config=genai_types.GenerateContentConfig(
-        tools=tools,
-        automatic_function_calling=genai_types.AutomaticFunctionCallingConfig(
-            disable=True
-        ),
-    ),
-)
+model_with_tools = genai_model.GenaiModel(...)
 
-agent = function_calling.FunctionCalling(model=model_with_tools, fns=tools)
+agent = function_calling.FunctionCalling(model=model_with_tools, fns=[get_weather])
 ```
 
 *See: [Function Calling Concept](../concepts/function-calling.md) and

examples/chat.py

@@ -162,8 +162,6 @@ async def run_chat() -> None:
 
     model = models.turn_based_model(
         system_instruction=SYSTEM_INSTRUCTIONS,
-        disable_automatic_function_calling=True,
-        tools=tools,
     )
     model = function_calling.FunctionCalling(
         model=realtime.LiveModelProcessor(model),

examples/live_illustrator/illustrator.py

@@ -355,14 +355,6 @@ def create_live_illustrator(
       model_name=MODEL_LISTEN,
       generate_content_config=genai_types.GenerateContentConfig(
           system_instruction=SYSTEM_INSTRUCTION,
-          # We will be handling tool calls on the client side.
-          automatic_function_calling=genai_types.AutomaticFunctionCallingConfig(
-              disable=True
-          ),
-          tools=[
-              image_gen.create_image_from_description,
-              image_gen.create_concept_art,
-          ],
       ),
   )
   end_of_turns_scheduler = ScheduleEndOfTurns(period_sec=image_period_sec)

examples/models.py

@@ -78,7 +78,6 @@ def turn_based_model(
         ]
         | None
     ) = None,
-    disable_automatic_function_calling: bool = False,
 ) -> processor.Processor:
   """Returns a turn-based model based on command line flags.
 
@@ -87,9 +86,10 @@ def turn_based_model(
 
   Args:
     system_instruction: The system instruction to use for the model.
-    tools: The tools to use for the model, or google search tool if None.
-    disable_automatic_function_calling: Whether to disable automatic function
-      calling.
+    tools: Server-side tools to use for the model (e.g. google_search).
+      Client-side function tools should be registered via
+      ``FunctionCalling(fns=...)`` instead — they will be auto-declared on the
+      model. Defaults to Google Search if None.
 
   Returns:
     A turn-based LLM model.
@@ -124,9 +124,6 @@ def turn_based_model(
         tools=tools
         if tools is not None
         else [genai_types.Tool(google_search=genai_types.GoogleSearch())],
-        automatic_function_calling=genai_types.AutomaticFunctionCallingConfig(
-            disable=disable_automatic_function_calling
-        ),
     )
 
     model_instance = genai_model.GenaiModel(

examples/widgets/widgets.py

@@ -183,14 +183,6 @@ def create_dr_widget(
       model_name=MODEL,
       generate_content_config=genai_types.GenerateContentConfig(
           system_instruction=SYSTEM_INSTRUCTION,
-          # We will be handling tool calls on the client side.
-          automatic_function_calling=genai_types.AutomaticFunctionCallingConfig(
-              disable=True
-          ),
-          tools=[
-              image_gen.create_image_from_description,
-              plot_gen.create_plot_from_description,
-          ],
       ),
   )
   fc_processor = function_calling.FunctionCalling(

genai_processors/core/function_calling.py

@@ -148,10 +148,9 @@
 -  `pre_processor` is a processor called once on `input` and on all results
 obtained by tool invocation. This could for instance be an image tokenizer to
 preprocess images and avoid re-tokenizing them on every model invocation.
--  `model` is a model processor that generates content. For the model to know
-which tools are available, the samefunction/tool set should be given both to the
-FunctionCalling and the model constructor. This model can be turn-based or
-bidi but this should be specificed in the FunctionCalling ctor.
+-  `model` is a model processor that generates content. Tool declarations are
+automatically registered on the model via ``add_tools()`` — you only need to
+pass functions to ``FunctionCalling(fns=...)``.
 -  `function_call` executes the function calls returned by the model. This is
 a private processor in this file. The function response is then fed back to the
 model for another iteration. If there is no function call to execute and the
@@ -162,35 +161,27 @@
 They are all in the same substream as identified by `substream_name` in the
 FunctionCalling ctor.
 
-When used with GenAI models (i.e. Gemini API), the model should be defined as
-follows:
+When used with GenAI models (i.e. Gemini API), the setup is simply:
 
 ```python
 genai_processor = genai_model.GenaiModel(
     api_key=API_KEY,
     model_name='gemini-2.5-flash',
-    generate_content_config=genai_types.GenerateContentConfig(
-        tools=[fns],
-        automatic_function_calling=genai_types.AutomaticFunctionCallingConfig(
-            disable=True
-        ),
-    ),
 )
+
+agent = FunctionCalling(genai_processor, fns=[get_weather, set_alarm])
 ```
 
-where `fns` are the python functions to be called. Note that we disable the
-automatic function calling feature here to avoid duplicate function calls with
-the GenAI automatic function calling feature.
+Tool declarations and disabling of automatic function calling are handled
+automatically via the ``add_tools()`` delegation.
 
-If you want to allow cancelling ongoing async functions add `cancel_fc` and
-`list_fc` tool defined in this file:
+If you want to allow cancelling ongoing async functions, add ``cancel_fc`` and
+``list_fc`` defined in this file:
 
 ```python
-generate_content_config=genai_types.GenerateContentConfig(
-    tools=[fns, function_calling.cancel_fc, function_calling.list_fc],
-    automatic_function_calling=genai_types.AutomaticFunctionCallingConfig(
-        disable=True
-    ),
+agent = FunctionCalling(
+    genai_processor,
+    fns=[get_weather, function_calling.cancel_fc, function_calling.list_fc],
 )
 ```
 
@@ -441,17 +432,15 @@ def __init__(
         processor.
       pre_processor: An optional pre-processor to pass the model input (prompt,
         function responses, model output from previous iterations) through.
-      fns: The functions to register for function calling. Those functions must
-        be known to `model`, and will be called only if `model` returns a
-        function call with the matching name. For Gemini API, this means the
-        same functions should be passed in the `GenerationConfig(tools=[...])`
-        to the `model` constructor. If the function name is not found in the
-        `fns` list, the function calling processor will return the unknown
-        function call part and will raise a `ValueError`. If the execution of
-        the function fails, the function calling processor will return a
-        function response with the error message. MCP tools are automatically
-        converted to callables when passed in as functions to this processor,
-        this happens the first time the model is called.
+      fns: The functions to register for function calling. Tool declarations are
+        automatically registered on the model via ``add_tools()`` — you do not
+        need to pass them separately to the model's config. If the function name
+        is not found in the `fns` list, the function calling processor will
+        return the unknown function call part and will raise a `ValueError`. If
+        the execution of the function fails, the function calling processor will
+        return a function response with the error message. MCP tools are
+        automatically converted to callables when passed in as functions to this
+        processor, this happens the first time the model is called.
       max_function_calls: maximum number of function calls to make (default set
         to 5 of turn-based models and infinity for bidi aka realtime models).
         When this limit is reached, the function calling loop will wait for the
@@ -461,8 +450,12 @@ def __init__(
     self._model = model
     self._substream_name = substream_name
     self._is_bidi_model = is_bidi_model
-    self._fns = fns
+    self._fns = list(fns) if fns else []
+    if is_bidi_model:
+      # Automatically add list_fc and cancel_fc for bidi models.
+      self._fns.extend([cancel_fc, list_fc])
     self._fns_initialized = False
+    self._called = False
     self._pre_processor = (
         pre_processor.to_processor()
         if pre_processor
@@ -471,6 +464,51 @@ def __init__(
     default_max_function_calls = 5 if not is_bidi_model else math.inf
     self._max_function_calls = max_function_calls or default_max_function_calls
 
+  def add_fns(self, fns: list[Callable[..., Any]]) -> None:
+    """Adds functions dynamically before call() is invoked.
+
+    This is useful for wrapper processors that need to inject additional
+    tools without interfering with how the FunctionCalling processor was
+    originally created. Functions added here are treated identically to
+    those passed in the constructor.
+
+    Must be called before `call()` is invoked.
+
+    Args:
+      fns: The functions to add.
+
+    Raises:
+      RuntimeError: if called after `call()` has been invoked.
+    """
+    if self._called:
+      raise RuntimeError('Cannot add functions after call() has been invoked.')
+    if self._fns is None:
+      self._fns = list(fns)
+    else:
+      self._fns = list(self._fns) + list(fns)
+
+  def register_tools(
+      self,
+      tools: list[Callable[..., Any] | genai_types.McpClientSession],
+  ) -> None:
+    """Delegates tool registration to the inner model processor.
+
+    When ``FunctionCalling`` is used as the inner model for another
+    ``FunctionCalling`` (nested pattern), the outer processor calls this
+    method to propagate tool declarations down to the actual model.
+
+    Args:
+      tools: Functions to register. Callables are converted to proto
+        FunctionDeclarations. McpClientSessions are expected to have been
+        converted to callables by FunctionCalling before reaching this method.
+    """
+    if hasattr(self._model, 'register_tools'):
+      self._model.register_tools(tools)
+
+  def children(self) -> list[processor.Processor]:
+    """Returns the list of sub-processors (children) for this processor."""
+    return [self._model]
+
   async def _initialize_mcp_tools(self):
     """Initializes the MCP tools."""
     if self._fns_initialized:
@@ -486,10 +524,42 @@ async def _initialize_mcp_tools(self):
     self._fns_initialized = True
     self._fns = fns
 
+  def _find_last_tool_supporting_processor(
+      self, proc: processor.Processor
+  ) -> processor.Processor | None:
+    """Recursively finds the last processor supporting register_tools."""
+    if hasattr(proc, 'register_tools'):
+      return proc
+
+    for child in reversed(proc.children()):
+      found = self._find_last_tool_supporting_processor(child)
+      if found:
+        return found
+    return None
+
+  def _register_tools_on_model(self) -> None:
+    """Registers tool declarations on the inner model processor.
+
+    Uses a generic tree traversal (via ``children()``) to find the last
+    processor in the hierarchy that supports ``register_tools()``.
+    """
+    if not self._fns:
+      return
+
+    target = self._find_last_tool_supporting_processor(self._model)
+    if target:
+      getattr(target, 'register_tools')(self._fns)
+    else:
+      raise ValueError(
+          f'No processor in the chain supports tool registration: {self._model}'
+      )
+
   async def call(
       self, content: processor.ProcessorStream
   ) -> AsyncIterable[content_api.ProcessorPartTypes]:
+    self._called = True
     await self._initialize_mcp_tools()
+    self._register_tools_on_model()
     state = _FunctionCallState(fn_call_count_limit=self._max_function_calls)
     # To support both bidi and unary models we reduce both cases to bidi.
     model = _to_bidi(self._model) if not self._is_bidi_model else self._model