+200 XP

Gemini · Function calling and structured outputs

Giving Gemini a function it can call turns it from a text generator into something that can read your calendar, hit your pricing API, or query your database. Getting clean JSON back means your code can use the result without regex hacks. These two capabilities are the backbone of every serious Gemini integration, and they work very differently under the hood.

Function calling is a negotiation, not an execution

The most important mental shift: Gemini never runs your function. It only decides *that* a function should be called and *with what arguments*. You run the code. You send the result back. Gemini continues.

That round trip is the tool-calling loop:

  1. You send a prompt plus a list of function *declarations* (name, description, parameters).
  2. Gemini responds either with normal text, or with a functionCall part containing the chosen function and arguments.
  3. Your code executes that function for real.
  4. You send the result back as a functionResponse.
  5. Gemini uses the result to produce its final answer (or call another function).

The model is doing structured intent recognition. Your job is to wire up the actual execution and keep passing state back into the conversation.

Declaring a function

A function declaration is a schema. Gemini reads the description fields to decide when and how to call it, so treat those as prompt engineering, not documentation. Vague descriptions produce wrong calls.

python
from google import genai
from google.genai import types

client = genai.Client()

get_weather = types.FunctionDeclaration(
    name="get_weather",
    description="Get the current temperature for a city. Use only when the user asks about weather.",
    parameters={
        "type": "object",
        "properties": {
            "city": {"type": "string", "description": "City name, e.g. 'Lisbon'"},
            "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
        },
        "required": ["city"],
    },
)

weather_tool = types.Tool(function_declarations=[get_weather])

This uses the unified Google Gen AI SDK, the current recommended Python library. The same SDK targets both the Gemini API (via AI Studio keys) and Vertex AI by changing client config, so you write the loop once.

Running the loop

Here is the full round trip with a Flash model. Model IDs change every few months, so keep the name in one constant and check the models page for the current Flash ID.

python
MODEL = "gemini-3-flash-preview"  # swap for the current Flash model ID

def get_weather_impl(city, unit="celsius"):
    return {"city": city, "temp": 19, "unit": unit}  # real API call goes here

config = types.GenerateContentConfig(tools=[weather_tool])
contents = ["What's the weather in Lisbon right now?"]

resp = client.models.generate_content(model=MODEL, contents=contents, config=config)

if resp.function_calls:
    call = resp.function_calls[0]
    result = get_weather_impl(**call.args)

    contents.append(resp.candidates[0].content)  # the model's call, untouched
    contents.append(types.Content(role="user", parts=[
        types.Part.from_function_response(name=call.name, response=result)
    ]))

    final = client.models.generate_content(model=MODEL, contents=contents, config=config)
    print(final.text)  # "It's 19°C in Lisbon right now."

The key lines are the two contents.append calls. You replay the model's own turn back into the history, then append the result. Skip the first append and Gemini loses track of what it asked for.

Append that turn as-is. Gemini 3 models attach a thought signature to function call parts, an encrypted record of the model's reasoning, and the API expects it back on the next request. Appending resp.candidates[0].content unchanged handles this for you. If you rebuild the call part by hand from its name and args, you drop the signature and the request can fail validation.

Letting Gemini call several functions

Give it more than one declaration and Gemini picks the right one, or asks for several. Parallel function calling is when a single response contains multiple functionCall parts ("compare weather in Lisbon and Madrid" yields two calls at once). Loop over resp.function_calls, execute each, and append all the responses together before the next turn.

You can also constrain behavior with tool_config. Setting the function calling mode to ANY forces Gemini to call a function rather than reply in prose, which is useful when a tool call is the only acceptable outcome:

python
config = types.GenerateContentConfig(
    tools=[weather_tool],
    tool_config=types.ToolConfig(
        function_calling_config=types.FunctionCallingConfig(mode="ANY")
    ),
)

Modes are AUTO (default, model decides), ANY (must call something), and NONE (never call). Use ANY with an allowed_function_names list to corral the model into a specific subset.

Structured outputs: when you want data, not a tool

Function calling is for *acting*. Structured output is for *extracting*. If you just want Gemini to return clean JSON you can parse, don't fake it with a tool. Use the response schema feature, which constrains the model's decoding so the output matches your schema.

This is constrained decoding: Gemini is restricted at generation time to only produce tokens that keep the output valid against your schema. You are not hoping for JSON. You are getting it.

python
from pydantic import BaseModel

class Invoice(BaseModel):
    vendor: str
    total: float
    currency: str
    line_items: list[str]

resp = client.models.generate_content(
    model=MODEL,
    contents="Extract the invoice details from this email: ...",
    config=types.GenerateContentConfig(
        response_mime_type="application/json",
        response_json_schema=Invoice.model_json_schema(),
    ),
)

invoice = Invoice.model_validate_json(resp.text)
print(invoice.total, invoice.currency)

The Gemini API accepts standard JSON Schema through response_json_schema, so a Pydantic model's model_json_schema() drops straight in, and you validate the result back into typed objects. No prompt that begs "return only JSON." No stray markdown fences to strip. Output keys come back in the order your schema defines them. You'll still see response_schema and propertyOrdering in older code: they work, but the JSON Schema path is the one to use for new projects.

When the schema is dynamic

If your shape is decided at runtime, pass a plain schema dict:

python
schema = {
    "type": "object",
    "properties": {
        "sentiment": {"type": "string", "enum": ["positive", "neutral", "negative"]},
        "topics": {"type": "array", "items": {"type": "string"}},
    },
    "required": ["sentiment", "topics"],
}

For classification, an enum on a single field like sentiment forces the answer to be exactly one of your labels and nothing else. That is the cleanest way to do single-label classification.

Choosing between the two

They overlap, so be deliberate:

  • Structured output when you control the whole interaction and just need parsed data back from one call. Faster, simpler, guaranteed shape.
  • Function calling when Gemini needs to reach *outside* itself: live data, your APIs, side effects, multi-step reasoning where each step depends on real results.

A common pattern combines them: function calls fetch real data, and the final answer comes back through a response schema so your downstream code stays typed. Gemini 3 models accept tools and a response schema in the same request, so this no longer needs a separate extraction call.

Don't hand-roll what the platform gives you

Some "functions" already exist as built-in tools. Grounding with Google Search, code execution, and URL context are native tools you enable in config rather than implement yourself. If you need fresh facts, turn on Search grounding instead of writing your own search function:

python
config = types.GenerateContentConfig(
    tools=[
        types.Tool(google_search=types.GoogleSearch()),
        weather_tool,
    ]
)

On Gemini 3 models you can combine built-in tools with your own function declarations, as above. Older models and some Vertex AI configurations still restrict this, so check the tools docs for the model you deploy.

Function Calling with the Gemini API

Watch on YouTube

Knowledge check

1. What is the most important conceptual distinction about how Gemini handles function calling?

2. Why does the lesson say the function's `description` fields should be treated as prompt engineering rather than documentation?

3. In the tool-calling loop, what does your code send back to Gemini after actually executing the chosen function?

MULTIPLE CHOICE

4. Select ALL correct statements about the tool-calling loop and function declarations.

Select all the correct answers.

MULTIPLE CHOICE

5. Select ALL correct statements about the benefits and design of function calling and structured outputs described in the lesson.

Select all the correct answers.

Prototype in AI Studio, then scale the right way

Before writing any loop, build the function declaration visually in Google AI Studio. You can define tools, watch Gemini emit functionCall parts, and copy working code in your language. It is the fastest way to tune those description strings.

When you move to production, the decision is *where* the loop runs:

  • Gemini API (ai.google.dev) for app backends and quick services. The SDK code above is all you need.
  • Vertex AI when you need enterprise controls: IAM, VPC, data residency, and managed deployment. Same SDK, different client init.
  • Agent Development Kit (ADK) when one model with a handful of tools grows into a real agent with planning, memory, and many tools. ADK gives you the loop, state, and tool orchestration as a framework so you stop writing append-the-response plumbing by hand. See the ADK docs.

For internal Workspace automation, you don't always need any of this. Apps Script can call Gemini and act on Docs, Sheets, or Gmail directly, which is often the shortest path to a working tool inside Google Workspace.

Hard-won details that save you hours

Descriptions are prompts. Gemini's accuracy at choosing and filling functions tracks closely with the quality of your description fields and parameter docs. Spell out *when* to use a function and *when not to*.

Validate every argument. Gemini fills arguments from a schema, but it can still hallucinate a plausible-but-wrong value, especially for IDs or enums it half-remembers. Treat function arguments like untrusted user input. Validate before you execute anything with side effects.

Use `required` and `enum` aggressively. Every constraint you put in the schema is a constraint the model must satisfy. Enums eliminate whole classes of garbage values. Required fields stop half-filled calls.

Pick the tier per task. Flash handles most tool routing and extraction with low latency and cost. Reach for Pro when the decision about *which* tool to call requires real reasoning over a long context, or when extraction depends on subtle multi-document logic.

Feed function results back, always. The most common bug is forgetting to append the model's own function call before the response. Without it, the conversation history is inconsistent, the final answer drifts, and on Gemini 3 the missing thought signature can make the request fail.

Key Takeaways

  • You execute, Gemini decides. The loop is: declare functions, receive a functionCall, run it yourself, append both the model's unmodified turn and your functionResponse, then generate the final answer.
  • Use response_json_schema (a Pydantic model's model_json_schema() works) to get schema-valid JSON through constrained decoding. Stop prompting for JSON and stripping markdown fences.
  • Function calling reaches outside the model for live data and side effects; structured output parses data from a single call. On Gemini 3 you can use both, plus built-in tools like Search, in one request.
  • Tool accuracy is mostly schema quality, so invest in description fields, enums, and required.
  • Prototype in AI Studio, then move to the Gemini API, Vertex AI, or ADK depending on scale, enterprise controls, or agent orchestration. Keep model IDs in one place and always validate function arguments before acting on them.