feat: add gemini_tools field to GeminiModel with validation and tests

[pshiko]

Add support for Gemini-specific tools like GoogleSearch and CodeExecution, with validation to prevent FunctionDeclarations and comprehensive test coverage.

Description

Background:
Gemini API provides powerful built-in tools that are distinct from standard FunctionDeclaration-based tools. These tools are defined in separate fields within the Gemini API's Tool type (see https://ai.google.dev/api/caching#Tool). The existing Strands tool interface is designed around standard function declarations and cannot accommodate these Gemini-specific capabilities.

Solution:
This PR implements support for Gemini's built-in tools by adding a new gemini_tools field to GeminiConfig. This approach was chosen over alternatives (modifying core ToolSpec interface or using magic string transformations) because it:

• Minimizes impact scope (changes contained within Gemini provider)
• Maintains type safety (uses genai.types.Tool directly)
• Is future-proof (adapts to Gemini API changes)
• Provides clear separation between standard function tools and Gemini built-in tools

Implementation Details:

1. New Configuration Field:

   class GeminiConfig(TypedDict, total=False):
       model_id: Required[str]
       params: dict[str, Any]
       gemini_tools: list[genai.types.Tool]  # New field for Gemini built-in tools

2. Validation Function: Added _validate_gemini_tools() to ensure gemini_tools doesn't contain FunctionDeclarations (which should use the standard tools interface):

3. Tool Merging:: Updated _format_request_tools() to combine standard function declarations with Gemini-specific tools

Example Usage:

from strands import Agent
from strands.models.gemini import GeminiModel
from google import genai
from google.genai import types

# Use Google Search for grounding with real-time web data
model = GeminiModel(
    model_id="gemini-2.5-flash",
    gemini_tools=[
        types.Tool(google_search=types.GoogleSearch())
    ]
)

agent = Agent(model=model)
response = agent("Who won the euro 2024?")
# Response will be grounded in recent web search results with citations

# Combine with standard function tools
agent_with_both = Agent(
    model=model,
    tools=[my_custom_function_tool]  # Standard function tools still work
)

Limitation

No Tool Usage History: Due to the fundamental differences in how Gemini's built-in tools operate (server-side execution without explicit tool call/result blocks), we don't implement history tracking for gemini_tools - that would require additional design work and a longer discussion on how to normalize this across all model providers. This PR is scoped down to specifically just enabling server side tools to unblock gemini customers

Related Issues

#1049

Documentation PR

Type of Change

New feature
Breaking change

Testing

How have you tested the change? Verify that the changes do not break functionality or introduce warnings in consuming repositories: agents-docs, agents-tools, agents-cli

• I ran hatch run prepare

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[pshiko]

@zastrowm @pgrayy
Do you have any updates on the review?

[mjnong]

What is the status on this

[pshiko]

I resolved conflict.

[mustafashabib]

Curious if we'll get this merged?

[pshiko]

Hi @zastrowm
Could you please take another look at this PR when you have a moment? If there’s anything blocking or unclear, I’d be happy to address it. Thanks! 🙇‍♂️

[zastrowm]

No Tool Usage History: Due to the fundamental differences in how Gemini's built-in tools operate (server-side execution without explicit tool call/result blocks), we don't implement history tracking for gemini_tools - that would require additional design work and a longer discussion on how to normalize this across all model providers. This PR is scoped down to specifically just enabling server side tools to unblock gemini customers

(editor note: I modified the PR description a bit and included this more prominently)

Discussed with @dbschmigelski offline regarding this limitation. We think this makes sense for now - we'd rather index on unblocking customers in the short term and find a way in the future to represent server-side tool calls in history in the future - but we think that will require design work and normalization across providers.

[zastrowm]

Thanks for the contribution @pshiko and sorry for the delay.