Feature Request: Native AFC & Multi-Tool Combination Support (Built-in Grounding + Custom Python Callables) on Vertex AI

# Feature Request: Native AFC & Multi-Tool Combination Support (Built-in Grounding + Custom Python Callables) on Vertex AI

**Please make sure you read the contribution guide and file the issues in the right place.**
[Contribution guide.](https://google.github.io/adk-docs/contributing-guide/)

---

## 🔴 Required Information
*Please ensure all items in this section are completed to allow for efficient triaging. Requests without complete information may be rejected / deprioritized. If an item is not applicable to you - please mark it as N/A*

### Is your feature request related to a specific problem?
Yes. When building agentic workflows in ADK 2.0.0, developers frequently need to mix built-in server-side grounding tools (like `google_maps_grounding` or `google_search`) with custom client-side Python callables in a single agent.

Currently, doing so on the Vertex AI backend causes the underlying `google-genai` SDK client validator to automatically disable **Automatic Function Calling (AFC)** and log a repetitive, confusing `RuntimeWarning` on every single model turn:
```text
Tools at indices [1] are not compatible with automatic function calling (AFC).
AFC is disabled. If AFC is intended, please include python callables in the tool
list, and do not include function declaration and MCP server in the tool list.
```

Although the ADK framework successfully bypasses this SDK block by using its own custom **Manual Function Calling (MFC)** history-circulation loop inside `InMemoryRunner` (allowing the execution to complete successfully on single-region endpoints like `us-central1`), the warning creates substantial console noise for ADK developers, and completely breaks native AFC capability for direct GenAI SDK developers.

---

### Describe the Solution You'd Like
We would like native support for mixing built-in grounding search tools and custom client-side callable function tools cleanly without warnings or disabled AFC.

#### Proposed Solutions:

1. **In the `google-genai` Python SDK**:
* **Update `find_afc_incompatible_tool_indexes()`**: Modify the validator (`google/genai/_extra_utils.py:L121`) to keep client-side AFC active for custom `FunctionDeclarations` as long as the executable Python callables are registered in the client's local `function_map`.
* **Allow `include_server_side_tool_invocations` on Vertex AI**: Permit this context-circulation configuration flag on Vertex AI (`models.py:L4135` inside `_ToolConfig_to_vertex()`) for Gemini 3 models on the `v1beta1` endpoint, rather than hardcoding a client-side `ValueError` crash.

2. **In the `google-adk` Python SDK**:
* **Grounding Bypass Sub-agent Wrapper**: Create a `GoogleMapsGroundingAgentTool` class that automatically wraps `google_maps_grounding` inside an isolated sub-agent tool under the hood when `bypass_multi_tools_limit=True` is specified (identical to how the ADK currently bypasses the limit for the standard `GoogleSearchTool` in `llm_agent.py:L149`).

---

### Impact on your work
This feature is important for enabling clean, warning-free enterprise agentic implementations on Vertex AI. Bypassing this client-side warning will significantly improve the developer experience and adoption when building mixed-tool workflows (combining built-in search grounding and custom business tools) under the ADK 2.0 framework.

---

### Willingness to contribute
No, but we are highly interested in collaborating, providing additional logs, and validating potential preview/beta fixes in our Google Cloud workspaces.

---

## 🟡 Recommended Information

### Describe Alternatives You've Considered

#### Alternative A: The Context Injection Pattern
* **What we did**: Fetched the custom data (such as Client IP or CRM profiles) locally in Python inside `run.py` prior to calling the agent, and injected it as text context (e.g., `[Client IP: X.X.X.X]`).
* **Why it's not ideal**: While this works and completely avoids warning logs, it strips the model of its agentic autonomy. The model cannot dynamically decide *when* to call the custom tool mid-workflow based on conversation logic.

#### Alternative B: ADK's Manual Interception (MFC Fallback)
* **What we did**: Let the ADK `Runner` manually intercept the `function_call` and route the `function_response` loop.
* **Why it's not ideal**: While it executes successfully on single-region endpoints (like `us-central1`), it floods the console logs with repetitive, multi-line SDK compatibility warning blocks on every query turn.

---

### Proposed API / Implementation

In `google.adk.tools`, we would like to be able to initialize the maps grounding tool with a bypass flag:
```python
from google.adk.tools import google_maps_grounding

# Automatically wraps maps grounding inside a sub-agent tool under the hood
google_maps_grounding.bypass_multi_tools_limit = True
```

This should be handled in `google/adk/agents/llm_agent.py` similarly to the standard `GoogleSearchTool` logic:
```python
# Proposed addition inside _convert_tool_union_to_tools() in llm_agent.py:
if multiple_tools and isinstance(tool_union, GoogleMapsGroundingTool):
from ..tools.google_maps_grounding_agent_tool import create_maps_agent
from ..tools.google_maps_grounding_agent_tool import GoogleMapsGroundingAgentTool

maps_tool = cast(GoogleMapsGroundingTool, tool_union)
if maps_tool.bypass_multi_tools_limit:
return [GoogleMapsGroundingAgentTool(create_maps_agent(model))]
```

---

### Additional Context

**ADK & GenAI Environment Details:**
* **ADK Library Version:** `2.0.0` (GA)
* **GenAI SDK Version:** `1.75.0`
* **Python Version:** `3.13`
* **Desktop OS:** Linux
* **Model:** `gemini-3.5-flash` (Vertex AI, us multi-region)

**Live timing logs on the 'us' multi-region endpoint showing the successful manual intercept loop working despite the disabled AFC warning:**
```text
Tools at indices [1] are not compatible with automatic function calling (AFC).
AFC is disabled. If AFC is intended, please include python callables in the tool
list, and do not include function declaration and MCP server in the tool list.
⚡ 🗺️ Google Maps Grounding Retrieval (+6.97s)
[DATABASE LOG] Saving: The Pink Door (4.6★) at 1919 Post Alley, Seattle, WA 98101, USA
⚡ 🧠 concierge_agent (function_response) (+0.00s)
⚡ 🧠 concierge_agent (function_call) (+2.12s)
⚡ 🧠 concierge_agent (function_response) (+0.13s)
⚡ 🏁 Response Synthesis & Completion (+4.64s)
```