Skip to content

Function Calling, Search Grounding, and Managed Agents

Connect Gemini to real actions with function calling, ground its answers in live Google Search results, and hand off multi-step work to a managed agent sandbox.

CurrentLast verified

Platforms

  • Gemini API (Python, JavaScript, Java, REST)

What the official documentation says

  • Function calling lets you connect Gemini to external tools and APIs; instead of generating a text response, the model determines when to call a specific function and provides the parameters needed to execute a real-world action.

    Function calling with the Gemini API

  • Function calling has three primary use cases documented — taking actions (scheduling appointments, sending emails, controlling smart home devices), augmenting knowledge (accessing databases, APIs, knowledge bases), and extending capabilities (using a calculator, creating charts).

    Function calling with the Gemini API

  • A function is defined with a type, name, description, and a JSON Schema-style parameters object listing required fields; it is passed to interactions.create as a tool with type "function", and the model returns a function_call step naming the function and its arguments rather than calling it itself.

    Function calling with the Gemini API

  • Grounding with Google Search connects Gemini to real-time web content and works with all available languages, reducing hallucinations, answering questions about recent events, and providing citations.

    Grounding with Google Search

  • Grounding is enabled by adding a tool with type "google_search"; the model then automatically decides whether a search would improve the answer, generates and executes the query itself, and returns a response with inline citation annotations plus google_search_call and google_search_result steps.

    Grounding with Google Search

  • A grounded response's text output includes inline annotations on the text content that link specific claims to their source citations.

    Grounding with Google Search

  • Managed agents provision a configurable agent harness with a single API call — a Linux sandbox where the agent reasons, executes code, manages files, and browses the web autonomously.

    Managed agents on the Gemini API

  • The available managed agents are the Antigravity agent (a general-purpose agent built on Gemini 3.8 Flash, configurable to other models via agent_config, running in a secure Google-hosted Linux sandbox) and Deep Research (an autonomous agent that plans, executes, and synthesizes multi-step research tasks).

    Managed agents on the Gemini API

  • Managed agents are in Public Preview; every agent's sandbox is isolated at the OS level and has unrestricted outbound network access by default, which can be restricted with a network allowlist.

    Managed agents on the Gemini API

  • Managed agent environments are permanently deleted after 7 days of inactivity, and VMs spin down after a brief period of inactivity (the next request restores state with a cold start); you can have up to 1,000 managed agents; environment compute is not billed during the preview.

    Managed agents on the Gemini API

  • Gemini can also be built into agents using external frameworks — LangChain/LangGraph, LlamaIndex, CrewAI, and the Vercel AI SDK are documented integrations.

    Managed agents on the Gemini API

Function calling: Gemini decides, your code acts

Function calling is how Gemini reaches outside plain text generation into real systems — but it never executes anything itself. You describe a function's name, description, and parameters; the model decides when calling it would help, and returns a function_call step naming the function and the arguments to use. Running it is on you.

from google import genai

schedule_meeting_function = {
    "type": "function",
    "name": "schedule_meeting",
    "description": "Schedules a meeting with specified attendees at a given time and date.",
    "parameters": {
        "type": "object",
        "properties": {
            "attendees": {"type": "array", "items": {"type": "string"}},
            "date": {"type": "string", "description": "Date (e.g., '2024-07-29')"},
            "time": {"type": "string", "description": "Time (e.g., '15:00')"},
            "topic": {"type": "string", "description": "The meeting topic."},
        },
        "required": ["attendees", "date", "time", "topic"],
    },
}

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Schedule a meeting with Bob and Alice for 03/14/2025 at 10:00 AM about Q3 planning.",
    tools=[{"type": "function", **schedule_meeting_function}],
)

for step in interaction.steps:
    if step.type == "function_call":
        print(f"Function to call: {step.name}")
        print(f"Arguments: {step.arguments}")

The three documented use cases are worth keeping distinct when you're deciding whether function calling is the right tool: taking actions (booking something, sending an email, controlling a device), augmenting knowledge (reaching a database or API the model has no built-in access to), and extending capabilities (delegating something like precise arithmetic or chart generation to a tool that's actually good at it).

Grounding with Google Search: citations, not just facts

Where function calling hands the work to your code, Google Search grounding hands it to Gemini itself. Add the google_search tool, and the model decides per-request whether a search would help, runs it, and folds the results into its answer — with inline citations, not just a plain-text claim:

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Who won the euro 2024?",
    tools=[{"type": "google_search"}]
)

print(interaction.output_text)

The response's text content carries annotations linking specific claims back to their sources, alongside google_search_call and google_search_result steps recording what was actually searched. This is documented as the feature's core value — reducing hallucination and letting you show users where an answer came from — so treat the citations as part of the output to surface, not metadata to discard.

Managed agents: hand off the whole task

Function calling and grounding both extend one interaction. Managed agents go further — one API call provisions an isolated Linux sandbox where an agent reasons, writes and runs code, manages files, and browses the web across many steps on its own.

Two are currently available: Antigravity, a general-purpose agent built on Gemini 3.8 Flash (configurable to other models via agent_config), and Deep Research, purpose-built for planning, executing, and synthesizing multi-step research.

A few operational details worth knowing before you rely on one:

  • Public Preview. Review an agent's actions and outputs before trusting them in sensitive workflows — this is the documentation's own framing, not an extra caution added here.
  • Network access is unrestricted outbound by default. Use a network allowlist to scope it to the domains the task actually needs.
  • Environments expire. Deleted permanently after 7 days of inactivity; a VM that's been idle spins down and cold-starts on the next request.
  • Up to 1,000 managed agents, with environment compute not billed during the preview — though model tokens and tool usage still are.

If a managed agent's Linux sandbox is more than you need, Gemini also integrates with LangChain/LangGraph, LlamaIndex, CrewAI, and the Vercel AI SDK for building your own agent loop with more control.

Picking the right layer

Reach for function calling when you have a specific, well-defined action your own code should perform. Reach for Google Search grounding when the answer just needs to be current and cited, with no custom logic involved. Reach for a managed agent when the task is genuinely open-ended and multi-step — the kind of thing you'd otherwise be manually looping function calls to accomplish. Combining multimodal input with any of these — asking an agent to act on what's in an image, say — is exactly where Multimodal understanding and this page meet.

How to do it

  1. For function calling, define a function's type, name, description, and JSON Schema parameters, then pass it as a tool to client.interactions.create.
  2. Check the returned steps for a function_call entry, execute the named function yourself with its arguments, and return the result on a follow-up call if needed.
  3. For search grounding, add a tool with type "google_search" and let the model decide per-request whether to search.
  4. Read the grounded response's inline annotations alongside interaction.output_text to surface citations, not just the answer text.
  5. For a multi-step task, provision a managed agent (Antigravity or Deep Research) instead of looping function calls yourself, and scope its network access with an allowlist before granting it sensitive credentials.

On Windows

N/AFunction calling, grounding, and managed agents are all API-level features with no OS-specific behavior.

On mobile

N/AThis tutorial covers server-side and script-based use of tools and agents, not a mobile client.

Use cases

  • Letting Gemini fill out a structured booking or scheduling request from a natural-language message, using function calling to produce the exact arguments an internal API needs.
  • Building a support or research assistant that cites its sources by turning on Google Search grounding instead of relying on the model's training data.
  • Delegating an open-ended, multi-step task — like researching a topic and producing a report — to a managed agent instead of orchestrating every step yourself.

Common mistakes

  • Expecting function calling to execute the action. The model only returns a function_call step with a name and arguments — your own code is responsible for actually calling the function and (usually) returning the result in a follow-up turn.
  • Treating Google Search grounding as always-on. It only runs when the google_search tool is included, and even then the model decides per-request whether a search actually improves the answer.
  • Assuming a grounded response's citations are optional metadata you can ignore. The documentation frames them as central to the feature — providing citations and increasing factual accuracy — not an afterthought.
  • Forgetting managed agents are Public Preview and reviewing agent output as if it were already fully vetted for sensitive workflows; the documentation explicitly recommends reviewing actions and outputs before relying on them.
  • Leaving a managed agent's network access unrestricted by default when it only needs a handful of domains — the network allowlist exists specifically to scope that down.

FAQ

Does Gemini actually run the function it calls?
No. It returns a function_call step describing which function to call and with what arguments — your application code executes it. This keeps the model from taking real-world actions on its own.
What are the three things function calling is documented for?
Taking actions (calling external APIs to do something), augmenting knowledge (pulling in data the model doesn't have), and extending capabilities (offloading tasks like calculation or chart generation to an external tool).
How is Google Search grounding different from function calling?
With grounding, Gemini itself generates and runs the search query and synthesizes the result — you don't implement anything. With function calling, you define the function and your own code executes it after the model asks.
What exactly is a managed agent?
A Google-hosted, OS-level-isolated Linux sandbox provisioned by a single API call, where an agent can reason, run code, manage files, and browse the web on its own. Antigravity (general-purpose) and Deep Research (research-focused) are the two currently available.
Is it safe to let a managed agent run unsupervised on sensitive data?
The documentation says no, not without review — managed agents are Public Preview, and Google's own guidance is to verify an agent's outputs before relying on them in sensitive workflows, and to scope credentials and network access to the minimum required.

Official sources

These are the pages this tutorial is checked against. Follow them if you need the vendor's exact wording.

Source status