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 APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.View full definition →, 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:
- You send a prompt plus a list of function *declarations* (name, description, parameters).
- Gemini responds either with normal text, or with a
functionCallpart containing the chosen function and arguments. - Your code executes that function for real.
- You send the result back as a
functionResponse. - 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 schemaschemaA schema is the formal blueprint that defines how data is structured, named, typed, and related within a database, file, or message.View full definition →. Gemini reads the description fields to decide when and how to call it, so treat those as prompt engineeringprompt engineeringPrompt engineering is the practice of designing and refining text inputs to guide large language models toward accurate, relevant, and reliable outputs.View full definition →, not documentation. Vague descriptions produce wrong calls.
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.
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:
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 tokenstokensA token is the basic unit of text that language models process, often a word fragment, whole word, or punctuation mark rather than a single character.View full definition → that keep the output valid against your schema. You are not hoping for JSON. You are getting it.
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:
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 reachreachThe number of unique people exposed to your message in a given period. Unlike impressions, reach counts each person once, no matter how often they see it.View full definition → *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:
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
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?
4. Select ALL correct statements about the tool-calling loop and function declarations.
Select all the correct answers.
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 residencydata residencyThe requirement that data is physically stored and processed in a specific country or region, often driven by law or contract.View full definition →, 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 yourfunctionResponse, then generate the final answer. - Use
response_json_schema(a Pydantic model'smodel_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
descriptionfields, enums, andrequired. - 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.