Python: Add GeminiChatClient (#4847)

* Add agent-framework-gemini package

* Add AGENTS.md documentation

* Add LICENSE file

* Add README.md for agent-framework-gemini package

* Add Google Gemini API keys to .env.example

* Add Google Gemini chat client implementation

* Add tests for GeminiChatClient

* Add Google Gemini agent examples

* Fix client inheritence order

* Update Gemini agent examples

* Update documentation

* Update AGENTS.md

* Add tests for JSON string handling in GeminiChatClient

* Add final response assembly test in GeminiChatClient

* Add tests for handling empty candidates in GeminiChatClient

* Improve Pydantic response handling in GeminiChatClient

* Add tests for function result resolution and callable tool normalization

* Add test for function result resolution when call_id is generated

* Refactor GeminiChatClient to correct inheritance order

Also updates constructor parameter order for environment file handling

* Enhance documentation and clarify Gemini-specific fields

* Update ThinkingConfig with new attributes and type

* Add tests for GoogleSearch and GoogleMaps configs

* Suppress valid-type mypy error on GeminiChatOptionsT

* Move service_url method near overrides

* Order _prepare_config kwargs by base then Gemini-specific

* Use FunctionCallingConfigMode for clarity and type safety

* Fix code_execution doc

* Add agent-framework-gemini to project dependencies

* Remove package from core dependencies

Initial release will be done without agent-framework-gemini in
core[all].

* Move integration tests into one file

* Remove __init__.py file from gemini tests directory

* Introduce RawGeminiChatClient as lightweight chat client

Updated GeminiChatClient to inherit from RawGeminiChatClient, maintaining full functionality with added features.

* Updated variable names from `model_id` to `model`

Across the codebase, including environment variables and client initialization. Adjusted related tests and sample scripts to reflect this change, ensuring consistency in the usage of the Gemini model identifier.

* Update AGENTS.md

* Update Gemini package to alpha status

* Fix docstrings in Gemini tests

* Change 'model_id' to 'model' in response handling

* Fix model property change in response handling

* Add built-in tool factory methods to Gemini client

Replaces boolean tool options (code_execution, google_search_grounding,
google_maps_grounding) with static factory methods that return types.Tool
objects: get_code_interpreter_tool, get_web_search_tool, get_mcp_tool,
get_file_search_tool, and get_maps_grounding_tool.

Simplifies _prepare_tools to a single translation boundary between
FunctionTool (framework) and FunctionDeclaration (Gemini API), with
types.Tool objects passed through unchanged.

* Surface code execution parts

_parse_parts now maps executable_code and code_execution_result
parts to text Content objects so callers can see the code run
and its output. Unknown part types log at debug level rather than
being silently dropped.

* Update Gemini client documentation

* Unify Gemini model name

Co-authored-by: Eduard van Valkenburg <eavanvalkenburg@users.noreply.github.com>

* Update Agent Framework core version

Co-authored-by: Eduard van Valkenburg <eavanvalkenburg@users.noreply.github.com>

* Add Python 3.14 in classifiers

* Replace kwargs with parameters in tool factories

* Refactor chat options handling in Gemini client

* Add tests for handling unknown and consumed keys

* Update Gemini documentation

Now reflects new options and built-in tool factory methods

* Change build system to flit

Co-authored-by: Eduard van Valkenburg <eavanvalkenburg@users.noreply.github.com>

* Fix build system in pyproject.toml

* Fix type checking for generate_content_stream

---------

Co-authored-by: Eduard van Valkenburg <eavanvalkenburg@users.noreply.github.com>

python/packages/gemini/samples/README.md

@@ -0,0 +1,18 @@
+# Google Gemini Examples
+
+This folder contains examples demonstrating how to use Google Gemini models with the Agent Framework.
+
+## Examples
+
+| File | Description |
+|------|-------------|
+| [`gemini_basic.py`](gemini_basic.py) | Basic agent with a weather tool, demonstrating both streaming and non-streaming responses. |
+| [`gemini_advanced.py`](gemini_advanced.py) | Extended thinking via `ThinkingConfig` for reasoning-heavy questions (Gemini 2.5+). |
+| [`gemini_with_google_search.py`](gemini_with_google_search.py) | Google Search grounding for up-to-date answers. |
+| [`gemini_with_google_maps.py`](gemini_with_google_maps.py) | Google Maps grounding for location and mapping information. |
+| [`gemini_with_code_execution.py`](gemini_with_code_execution.py) | Built-in code execution tool for computing precise answers in a sandboxed environment. |
+
+## Environment Variables
+
+- `GEMINI_API_KEY`: Your Google AI Studio API key (get one from [Google AI Studio](https://aistudio.google.com/apikey))
+- `GEMINI_MODEL`: The Gemini model to use (e.g., `gemini-2.5-flash`, `gemini-2.5-pro`)

python/packages/gemini/samples/gemini_advanced.py

@@ -0,0 +1,47 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Shows how to enable extended thinking with ThinkingConfig.
+
+Allows the model to reason through complex problems before responding.
+
+Requires the following environment variables to be set:
+- GEMINI_API_KEY
+- GEMINI_MODEL
+"""
+
+import asyncio
+
+from agent_framework import Agent
+from dotenv import load_dotenv
+
+from agent_framework_gemini import GeminiChatClient, GeminiChatOptions, ThinkingConfig
+
+load_dotenv()
+
+
+async def main() -> None:
+    """Example of extended thinking with a Python version comparison question."""
+    print("=== Extended thinking ===")
+
+    options: GeminiChatOptions = {
+        "thinking_config": ThinkingConfig(thinking_budget=2048),
+    }
+
+    agent = Agent(
+        client=GeminiChatClient(),
+        name="PythonAgent",
+        instructions="You are a helpful Python expert.",
+        default_options=options,
+    )
+
+    query = "What new language features were introduced in Python between 3.10 and 3.14?"
+    print(f"User: {query}")
+    print("Agent: ", end="", flush=True)
+    async for chunk in agent.run(query, stream=True):
+        if chunk.text:
+            print(chunk.text, end="", flush=True)
+    print("\n")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/packages/gemini/samples/gemini_basic.py

@@ -0,0 +1,78 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Shows how to use GeminiChatClient with an agent and a custom tool.
+
+Covers both non-streaming and streaming responses.
+
+Requires the following environment variables to be set:
+- GEMINI_API_KEY
+- GEMINI_MODEL
+"""
+
+import asyncio
+from random import randint
+from typing import Annotated
+
+from agent_framework import Agent, tool
+from dotenv import load_dotenv
+
+from agent_framework_gemini import GeminiChatClient
+
+load_dotenv()
+
+
+# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production
+@tool(approval_mode="never_require")
+def get_weather(
+    location: Annotated[str, "The location to get the weather for."],
+) -> str:
+    """Get the weather for a given location."""
+    conditions = ["sunny", "cloudy", "rainy", "stormy"]
+    return f"The weather in {location} is {conditions[randint(0, 3)]} with a high of {randint(10, 30)}°C."
+
+
+async def non_streaming_example() -> None:
+    """Runs the agent and waits for the complete response before printing it."""
+    print("=== Non-streaming ===")
+
+    agent = Agent(
+        client=GeminiChatClient(),
+        name="WeatherAgent",
+        instructions="You are a helpful weather agent.",
+        tools=[get_weather],
+    )
+
+    query = "What's the weather like in Karlsruhe, Germany?"
+    print(f"User: {query}")
+    result = await agent.run(query)
+    print(f"Result: {result}\n")
+
+
+async def streaming_example() -> None:
+    """Runs the agent and prints each chunk as it is received."""
+    print("=== Streaming ===")
+
+    agent = Agent(
+        client=GeminiChatClient(),
+        name="WeatherAgent",
+        instructions="You are a helpful weather agent.",
+        tools=[get_weather],
+    )
+
+    query = "What's the weather like in Portland and in Paris?"
+    print(f"User: {query}")
+    print("Agent: ", end="", flush=True)
+    async for chunk in agent.run(query, stream=True):
+        if chunk.text:
+            print(chunk.text, end="", flush=True)
+    print("\n")
+
+
+async def main() -> None:
+    """Run non-streaming and streaming examples."""
+    await non_streaming_example()
+    await streaming_example()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/packages/gemini/samples/gemini_with_code_execution.py

@@ -0,0 +1,43 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Shows how to enable Gemini's built-in code execution tool.
+
+Allows the model to write and run code in a sandboxed environment to answer questions.
+
+Requires the following environment variables to be set:
+- GEMINI_API_KEY
+- GEMINI_MODEL
+"""
+
+import asyncio
+
+from agent_framework import Agent
+from dotenv import load_dotenv
+
+from agent_framework_gemini import GeminiChatClient
+
+load_dotenv()
+
+
+async def main() -> None:
+    """Run the code execution example."""
+    print("=== Code execution ===")
+
+    agent = Agent(
+        client=GeminiChatClient(),
+        name="CodeAgent",
+        instructions="You are a helpful assistant. Use code execution to compute precise answers.",
+        tools=[GeminiChatClient.get_code_interpreter_tool()],
+    )
+
+    query = "What are the first 20 prime numbers? Compute them in code."
+    print(f"User: {query}")
+    print("Agent: ", end="", flush=True)
+    async for chunk in agent.run(query, stream=True):
+        if chunk.text:
+            print(chunk.text, end="", flush=True)
+    print("\n")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/packages/gemini/samples/gemini_with_google_maps.py

@@ -0,0 +1,43 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Shows how to enable Google Maps grounding.
+
+Allows Gemini to retrieve location and mapping information before responding.
+
+Requires the following environment variables to be set:
+- GEMINI_API_KEY
+- GEMINI_MODEL
+"""
+
+import asyncio
+
+from agent_framework import Agent
+from dotenv import load_dotenv
+
+from agent_framework_gemini import GeminiChatClient
+
+load_dotenv()
+
+
+async def main() -> None:
+    """Run the Google Maps grounding example."""
+    print("=== Google Maps grounding ===")
+
+    agent = Agent(
+        client=GeminiChatClient(),
+        name="MapsAgent",
+        instructions="You are a helpful travel assistant. Use Google Maps to provide accurate location information.",
+        tools=[GeminiChatClient.get_maps_grounding_tool()],
+    )
+
+    query = "What are some highly rated restaurants in the city center of Karlsruhe, Germany?"
+    print(f"User: {query}")
+    print("Agent: ", end="", flush=True)
+    async for chunk in agent.run(query, stream=True):
+        if chunk.text:
+            print(chunk.text, end="", flush=True)
+    print("\n")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/packages/gemini/samples/gemini_with_google_search.py

@@ -0,0 +1,43 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Shows how to enable Google Search grounding.
+
+Allows Gemini to retrieve up-to-date information from the web before responding.
+
+Requires the following environment variables to be set:
+- GEMINI_API_KEY
+- GEMINI_MODEL
+"""
+
+import asyncio
+
+from agent_framework import Agent
+from dotenv import load_dotenv
+
+from agent_framework_gemini import GeminiChatClient
+
+load_dotenv()
+
+
+async def main() -> None:
+    """Run the Google Search grounding example."""
+    print("=== Google Search grounding ===")
+
+    agent = Agent(
+        client=GeminiChatClient(),
+        name="SearchAgent",
+        instructions="You are a helpful assistant. Use Google Search to provide accurate, up-to-date answers.",
+        tools=[GeminiChatClient.get_web_search_tool()],
+    )
+
+    query = "What is the latest stable release of the .NET SDK?"
+    print(f"User: {query}")
+    print("Agent: ", end="", flush=True)
+    async for chunk in agent.run(query, stream=True):
+        if chunk.text:
+            print(chunk.text, end="", flush=True)
+    print("\n")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())