Advanced Agentic Workflows: Mastering Tool Combination and Context Circulation in Gemini API

How to Combine Google Search, Google Maps, and Custom Functions in a Single Gemini API Call With Context Circulation, Parallel Tool IDs, and Multi-Step Agentic Chains

Google’s March 2026 Gemini API updates introduce the ability to execute built-in tools like Google Search alongside custom function declarations in a single request. This system leverages context circulation to autonomously chain tool outputs across multi-step agentic workflows.

Why This Matters

While ideal LLM agents often struggle with state management across disparate tools, the introduction of unique tool response IDs and context circulation provides a deterministic way to map parallel function calls to results. This technical advancement moves beyond simple prompt-response loops to sophisticated reasoning chains where real-time grounding data from Search or Maps directly informs the parameters of custom business logic, such as inventory lookups or booking systems, without losing track of execution state.

Key Insights

• Google Search and custom function declarations can now be passed within the same Tool object as of the March 2026 Gemini API update.
• Parallel tool execution requires developers to return every function_response with a unique ‘id’ field that matches the model’s function_call id.
• Grounding with Google Maps on Gemini 2.5/2.0 Flash models provides real-time place data and ‘google_maps_widget_context_token’ for frontend UI integration.
• The ‘include_server_side_tool_invocations’ flag in ToolConfig is the mandatory trigger for enabling multi-tool context circulation.
• Context circulation requires returning all parts of a response, including ‘thought_signature’, in subsequent turns to preserve the model’s reasoning chain.

Working Examples

Configuration for combining Google Search and custom functions in a single call.

response_1 = client.models.generate_content(
    model="gemini-3-flash-preview",
    contents="What is the northernmost city in the US? What's the weather like there?",
    config=types.GenerateContentConfig(
        tools=[
            types.Tool(
                google_search=types.GoogleSearch(),
                function_declarations=[get_weather_func],
            ),
        ],
        tool_config=types.ToolConfig(
            include_server_side_tool_invocations=True,
        ),
    ),
)

Implementing location-aware grounding using the Google Maps tool.

maps_response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Best Italian restaurants within a 15-minute walk?",
    config=types.GenerateContentConfig(
        tools=[types.Tool(google_maps=types.GoogleMaps())],
        tool_config=types.ToolConfig(
            retrieval_config=types.RetrievalConfig(
                lat_lng=types.LatLng(latitude=34.050481, longitude=-118.248526),
            )
        ),
    ),
)

Practical Applications

• Use Case: E-commerce agents performing parallel SKU inventory lookups and shipping estimations using unique tool IDs to map results. Pitfall: Failing to provide matching IDs for every function_response, which causes the model to misattribute data to the wrong function call.
• Use Case: Automated travel assistants using Google Search to identify trending venues and custom functions to execute bookings based on discovered data. Pitfall: Disabling server-side tool invocations, which prevents the model from using search results to autonomously populate function arguments.
• Use Case: Financial analysis tools chaining Google Search for data retrieval, Code Execution for statistical processing, and custom functions for database persistence. Pitfall: Omitting the ‘thought_signature’ in multi-turn history, which disrupts the model’s internal reasoning state across the chain.

References:

• https://ai.google.dev/gemini-api/docs/tool-combination
• https://ai.google.dev/gemini-api/docs/maps-grounding