quickstarts/rest/Function_calling_REST.ipynb (760 lines of code) (raw):

{ "cells": [ { "cell_type": "markdown", "metadata": { "id": "Tce3stUlHN0L" }, "source": [ "##### Copyright 2025 Google LLC." ] }, { "cell_type": "code", "execution_count": null, "metadata": { "cellView": "form", "id": "tuOe1ymfHZPu" }, "outputs": [], "source": [ "# @title Licensed under the Apache License, Version 2.0 (the \"License\");\n", "# you may not use this file except in compliance with the License.\n", "# You may obtain a copy of the License at\n", "#\n", "# https://www.apache.org/licenses/LICENSE-2.0\n", "#\n", "# Unless required by applicable law or agreed to in writing, software\n", "# distributed under the License is distributed on an \"AS IS\" BASIS,\n", "# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n", "# See the License for the specific language governing permissions and\n", "# limitations under the License." ] }, { "cell_type": "markdown", "metadata": { "id": "--TyBtqKrCHg" }, "source": [ "# Gemini API: Function calling with REST\n", "\n", "<a target=\"_blank\" href=\"https://colab.research.google.com/github/google-gemini/cookbook/blob/main/quickstarts/rest/Function_calling_REST.ipynb\"><img src=\"https://colab.research.google.com/assets/colab-badge.svg\" height=30/></a>" ] }, { "cell_type": "markdown", "metadata": { "id": "4244NXM5rJt5" }, "source": [ "This notebook provides quick code examples that show you how to get started with function calling using `curl`.\n", "\n", "You can run this in Google Colab, or you can copy/paste the `curl` commands into your terminal.\n", "\n", "To run this notebook, your API key must be stored it in a Colab Secret named GOOGLE_API_KEY. If you are running in a different environment, you can store your key in an environment variable. See [Authentication](https://github.com/google-gemini/cookbook/blob/main/quickstarts/Authentication.ipynb) to learn more." ] }, { "cell_type": "code", "execution_count": null, "metadata": { "id": "pxd3u97ZsR5c" }, "outputs": [], "source": [ "import os\n", "from google.colab import userdata\n", "\n", "os.environ['GOOGLE_API_KEY'] = userdata.get('GOOGLE_API_KEY')" ] }, { "cell_type": "markdown", "metadata": { "id": "lmdFGEHrrMg8" }, "source": [ "## How function calling works" ] }, { "cell_type": "markdown", "metadata": { "id": "nLN0s1FIrepp" }, "source": [ "Function calling lets developers create a description of a function in their code, then pass that description to a language model in a request. The response from the model includes the name of a function that matches the description and the arguments to call it with. Function calling lets you use functions as tools in generative AI applications, and you can define more than one function within a single request. Function calling returns JSON with the name of a function and the arguments to use in your code.\n", "\n", "Functions are described using *function declarations*. After you pass a list of\n", "function declarations in a query to a language model, the model returns an\n", "object in an [OpenAPI compatible schema](https://spec.openapis.org/oas/v3.0.3#schema)\n", "format that includes the names of functions and their arguments and tries to\n", "answer the user query with one of the returned functions. The language model\n", "understands the purpose of a function by analyzing its function declaration. The\n", "model doesn't actually call the function. Instead, a developer uses the\n", "[OpenAPI compatible schema](https://spec.openapis.org/oas/v3.0.3#schema) object\n", "in the response to call the function that the model returns.\n", "\n", "When you implement function calling, you create one or more *function\n", "declarations*, then add the function declarations to a `tools` object that's\n", "passed to the model. Each function declaration contains information about one\n", "function that includes the following:\n", "\n", "* Function name\n", "* Function parameters in an\n", " [OpenAPI compatible schema](https://spec.openapis.org/oas/v3.0.3#schemawr) format.\n", " A select subset (add a link) is\n", " supported. When using curl, the schema is specified using JSON.\n", "* Function description (optional). For the best results, it is recommended that you\n", " include a description.\n", "\n", "This notebook includes curl examples that make REST calls with the\n", "`GenerativeModel` class and its methods." ] }, { "cell_type": "markdown", "metadata": { "id": "vnC8xzmOrgt0" }, "source": [ "## Supported models" ] }, { "cell_type": "markdown", "metadata": { "id": "ocMX8ebNrj0A" }, "source": [ "All the Gemini models support function calling." ] }, { "cell_type": "markdown", "metadata": { "id": "-Z7dneXGrmGo" }, "source": [ "## Function calling cURL samples\n", "\n", "When you use cURL, the function and parameter information is included in the\n", "`tools` element. Each function declaration in the `tools` element contains the\n", "function name, its parameters specified using the\n", "[OpenAPI compatible schema](https://spec.openapis.org/oas/v3.0.3#schema), and\n", "a function description. The following samples demonstrate how to use curl\n", "commands with function calling:" ] }, { "cell_type": "markdown", "metadata": { "id": "zG9ktjHdrpKA" }, "source": [ "### Single-turn curl sample\n", "\n", "Single-turn is when you call the language model one time. With function calling,\n", "a single-turn use case might be when you provide the model a natural language\n", "query and a list of functions. In this case, the model uses the function\n", "declaration, which includes the function name, parameters, and description, to\n", "predict which function to call and the arguments to call it with.\n", "\n", "The following curl sample is an example of passing in a description of a\n", "function that returns information about where a movie is playing. Several\n", "function declarations are included in the request, such as `find_movies` and\n", "`find_theaters`." ] }, { "cell_type": "code", "execution_count": 6, "metadata": { "id": "vlf-DZSVrIu-" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "{\n", " \"candidates\": [\n", " {\n", " \"content\": {\n", " \"parts\": [\n", " {\n", " \"functionCall\": {\n", " \"name\": \"find_theaters\",\n", " \"args\": {\n", " \"movie\": \"Barbie\",\n", " \"location\": \"Mountain View, CA\"\n", " }\n", " }\n", " }\n", " ],\n", " \"role\": \"model\"\n", " },\n", " \"finishReason\": \"STOP\",\n", " \"index\": 0,\n", " \"safetyRatings\": [\n", " {\n", " \"category\": \"HARM_CATEGORY_HATE_SPEECH\",\n", " \"probability\": \"NEGLIGIBLE\"\n", " },\n", " {\n", " \"category\": \"HARM_CATEGORY_SEXUALLY_EXPLICIT\",\n", " \"probability\": \"NEGLIGIBLE\"\n", " },\n", " {\n", " \"category\": \"HARM_CATEGORY_HARASSMENT\",\n", " \"probability\": \"NEGLIGIBLE\"\n", " },\n", " {\n", " \"category\": \"HARM_CATEGORY_DANGEROUS_CONTENT\",\n", " \"probability\": \"NEGLIGIBLE\"\n", " }\n", " ]\n", " }\n", " ],\n", " \"promptFeedback\": {\n", " \"safetyRatings\": [\n", " {\n", " \"category\": \"HARM_CATEGORY_SEXUALLY_EXPLICIT\",\n", " \"probability\": \"NEGLIGIBLE\"\n", " },\n", " {\n", " \"category\": \"HARM_CATEGORY_HATE_SPEECH\",\n", " \"probability\": \"NEGLIGIBLE\"\n", " },\n", " {\n", " \"category\": \"HARM_CATEGORY_HARASSMENT\",\n", " \"probability\": \"NEGLIGIBLE\"\n", " },\n", " {\n", " \"category\": \"HARM_CATEGORY_DANGEROUS_CONTENT\",\n", " \"probability\": \"NEGLIGIBLE\"\n", " }\n", " ]\n", " }\n", "}\n" ] } ], "source": [ "%%bash\n", "\n", "curl \"https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=$GOOGLE_API_KEY\" \\\n", " -H 'Content-Type: application/json' \\\n", " -d '{\n", " \"contents\": {\n", " \"role\": \"user\",\n", " \"parts\": {\n", " \"text\": \"Which theaters in Mountain View show Barbie movie?\"\n", " }\n", " },\n", " \"tools\": [\n", " {\n", " \"function_declarations\": [\n", " {\n", " \"name\": \"find_movies\",\n", " \"description\": \"find movie titles currently playing in theaters based on any description, genre, title words, etc.\",\n", " \"parameters\": {\n", " \"type\": \"object\",\n", " \"properties\": {\n", " \"location\": {\n", " \"type\": \"string\",\n", " \"description\": \"The city and state, e.g. San Francisco, CA or a zip code e.g. 95616\"\n", " },\n", " \"description\": {\n", " \"type\": \"string\",\n", " \"description\": \"Any kind of description including category or genre, title words, attributes, etc.\"\n", " }\n", " },\n", " \"required\": [\n", " \"description\"\n", " ]\n", " }\n", " },\n", " {\n", " \"name\": \"find_theaters\",\n", " \"description\": \"find theaters based on location and optionally movie title which are is currently playing in theaters\",\n", " \"parameters\": {\n", " \"type\": \"object\",\n", " \"properties\": {\n", " \"location\": {\n", " \"type\": \"string\",\n", " \"description\": \"The city and state, e.g. San Francisco, CA or a zip code e.g. 95616\"\n", " },\n", " \"movie\": {\n", " \"type\": \"string\",\n", " \"description\": \"Any movie title\"\n", " }\n", " },\n", " \"required\": [\n", " \"location\"\n", " ]\n", " }\n", " },\n", " {\n", " \"name\": \"get_showtimes\",\n", " \"description\": \"Find the start times for movies playing in a specific theater\",\n", " \"parameters\": {\n", " \"type\": \"object\",\n", " \"properties\": {\n", " \"location\": {\n", " \"type\": \"string\",\n", " \"description\": \"The city and state, e.g. San Francisco, CA or a zip code e.g. 95616\"\n", " },\n", " \"movie\": {\n", " \"type\": \"string\",\n", " \"description\": \"Any movie title\"\n", " },\n", " \"theater\": {\n", " \"type\": \"string\",\n", " \"description\": \"Name of the theater\"\n", " },\n", " \"date\": {\n", " \"type\": \"string\",\n", " \"description\": \"Date for requested showtime\"\n", " }\n", " },\n", " \"required\": [\n", " \"location\",\n", " \"movie\",\n", " \"theater\",\n", " \"date\"\n", " ]\n", " }\n", " }\n", " ]\n", " }\n", " ]\n", "}' 2> /dev/null" ] }, { "cell_type": "markdown", "metadata": { "id": "mPry4O2vsclo" }, "source": [ "### Multi-turn curl examples\n", "\n", "You can implement a multi-turn function calling scenario by doing the following:\n", "\n", "1. Get a function call response by calling the language model. This is the first\n", " turn.\n", "1. Call the language model using the function call response from the first turn\n", " and the function response you get from calling that function. This is the\n", " second turn.\n", "\n", "The response from the second turn either summarizes the results to answer your\n", "query in the first turn, or contains a second function call you can use to get\n", "more information for your query.\n", "\n", "This topic includes two multi-turn curl examples:\n", "\n", "* Curl example that uses a function response from a previous turn\n", "* Curl example that calls a language model multiple times" ] }, { "cell_type": "markdown", "metadata": { "id": "hbGg-7mSsn26" }, "source": [ "#### Curl example that uses a response from a previous turn\n", "\n", "The following curl sample calls the function and arguments returned by the\n", "previous single-turn example to get a response. The method and parameters\n", "returned by the single-turn example are in this JSON.\n", "\n", "```json\n", "\"functionCall\": {\n", " \"name\": \"find_theaters\",\n", " \"args\": {\n", " \"movie\": \"Barbie\",\n", " \"location\": \"Mountain View, CA\"\n", " }\n", "}\n", "```" ] }, { "cell_type": "code", "execution_count": 7, "metadata": { "id": "_yb-YAv-r2tf" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "{\n", " \"candidates\": [\n", " {\n", " \"content\": {\n", " \"parts\": [\n", " {\n", " \"text\": \"OK. I found two theaters in Mountain View that are showing the Barbie movie: AMC Mountain View 16 and Regal Edwards 14.\"\n", " }\n", " ],\n", " \"role\": \"model\"\n", " },\n", " \"finishReason\": \"STOP\",\n", " \"index\": 0,\n", " \"safetyRatings\": [\n", " {\n", " \"category\": \"HARM_CATEGORY_SEXUALLY_EXPLICIT\",\n", " \"probability\": \"NEGLIGIBLE\"\n", " },\n", " {\n", " \"category\": \"HARM_CATEGORY_HATE_SPEECH\",\n", " \"probability\": \"NEGLIGIBLE\"\n", " },\n", " {\n", " \"category\": \"HARM_CATEGORY_HARASSMENT\",\n", " \"probability\": \"NEGLIGIBLE\"\n", " },\n", " {\n", " \"category\": \"HARM_CATEGORY_DANGEROUS_CONTENT\",\n", " \"probability\": \"NEGLIGIBLE\"\n", " }\n", " ]\n", " }\n", " ]\n", "}\n" ] } ], "source": [ "%%bash\n", "\n", "curl \"https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=$GOOGLE_API_KEY\" \\\n", " -H 'Content-Type: application/json' \\\n", " -d '{\n", " \"contents\": [{\n", " \"role\": \"user\",\n", " \"parts\": [{\n", " \"text\": \"Which theaters in Mountain View show Barbie movie?\"\n", " }]\n", " }, {\n", " \"role\": \"model\",\n", " \"parts\": [{\n", " \"functionCall\": {\n", " \"name\": \"find_theaters\",\n", " \"args\": {\n", " \"location\": \"Mountain View, CA\",\n", " \"movie\": \"Barbie\"\n", " }\n", " }\n", " }]\n", " }, {\n", " \"role\": \"function\",\n", " \"parts\": [{\n", " \"functionResponse\": {\n", " \"name\": \"find_theaters\",\n", " \"response\": {\n", " \"name\": \"find_theaters\",\n", " \"content\": {\n", " \"movie\": \"Barbie\",\n", " \"theaters\": [{\n", " \"name\": \"AMC Mountain View 16\",\n", " \"address\": \"2000 W El Camino Real, Mountain View, CA 94040\"\n", " }, {\n", " \"name\": \"Regal Edwards 14\",\n", " \"address\": \"245 Castro St, Mountain View, CA 94040\"\n", " }]\n", " }\n", " }\n", " }\n", " }]\n", " }],\n", " \"tools\": [{\n", " \"functionDeclarations\": [{\n", " \"name\": \"find_movies\",\n", " \"description\": \"find movie titles currently playing in theaters based on any description, genre, title words, etc.\",\n", " \"parameters\": {\n", " \"type\": \"OBJECT\",\n", " \"properties\": {\n", " \"location\": {\n", " \"type\": \"STRING\",\n", " \"description\": \"The city and state, e.g. San Francisco, CA or a zip code e.g. 95616\"\n", " },\n", " \"description\": {\n", " \"type\": \"STRING\",\n", " \"description\": \"Any kind of description including category or genre, title words, attributes, etc.\"\n", " }\n", " },\n", " \"required\": [\"description\"]\n", " }\n", " }, {\n", " \"name\": \"find_theaters\",\n", " \"description\": \"find theaters based on location and optionally movie title which are is currently playing in theaters\",\n", " \"parameters\": {\n", " \"type\": \"OBJECT\",\n", " \"properties\": {\n", " \"location\": {\n", " \"type\": \"STRING\",\n", " \"description\": \"The city and state, e.g. San Francisco, CA or a zip code e.g. 95616\"\n", " },\n", " \"movie\": {\n", " \"type\": \"STRING\",\n", " \"description\": \"Any movie title\"\n", " }\n", " },\n", " \"required\": [\"location\"]\n", " }\n", " }, {\n", " \"name\": \"get_showtimes\",\n", " \"description\": \"Find the start times for movies playing in a specific theater\",\n", " \"parameters\": {\n", " \"type\": \"OBJECT\",\n", " \"properties\": {\n", " \"location\": {\n", " \"type\": \"STRING\",\n", " \"description\": \"The city and state, e.g. San Francisco, CA or a zip code e.g. 95616\"\n", " },\n", " \"movie\": {\n", " \"type\": \"STRING\",\n", " \"description\": \"Any movie title\"\n", " },\n", " \"theater\": {\n", " \"type\": \"STRING\",\n", " \"description\": \"Name of the theater\"\n", " },\n", " \"date\": {\n", " \"type\": \"STRING\",\n", " \"description\": \"Date for requested showtime\"\n", " }\n", " },\n", " \"required\": [\"location\", \"movie\", \"theater\", \"date\"]\n", " }\n", " }]\n", " }]\n", "}' 2> /dev/null" ] }, { "cell_type": "markdown", "metadata": { "id": "eMpUbIvQt2qx" }, "source": [ "#### Curl example that calls a language model multiple times\n", "\n", "The following curl example calls the language model multiple times to call a\n", "function. Each time the model calls the function, it can use a different\n", "function to answer a different user query in the request." ] }, { "cell_type": "code", "execution_count": 9, "metadata": { "id": "OKjGRZDUsxwj" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "{\n", " \"candidates\": [\n", " {\n", " \"content\": {\n", " \"parts\": [\n", " {\n", " \"functionCall\": {\n", " \"name\": \"find_movies\",\n", " \"args\": {\n", " \"location\": \"Mountain View, CA\",\n", " \"description\": \"comedy\"\n", " }\n", " }\n", " }\n", " ],\n", " \"role\": \"model\"\n", " },\n", " \"finishReason\": \"STOP\",\n", " \"index\": 0,\n", " \"safetyRatings\": [\n", " {\n", " \"category\": \"HARM_CATEGORY_HARASSMENT\",\n", " \"probability\": \"NEGLIGIBLE\"\n", " },\n", " {\n", " \"category\": \"HARM_CATEGORY_SEXUALLY_EXPLICIT\",\n", " \"probability\": \"NEGLIGIBLE\"\n", " },\n", " {\n", " \"category\": \"HARM_CATEGORY_DANGEROUS_CONTENT\",\n", " \"probability\": \"NEGLIGIBLE\"\n", " },\n", " {\n", " \"category\": \"HARM_CATEGORY_HATE_SPEECH\",\n", " \"probability\": \"NEGLIGIBLE\"\n", " }\n", " ]\n", " }\n", " ],\n", " \"promptFeedback\": {\n", " \"safetyRatings\": [\n", " {\n", " \"category\": \"HARM_CATEGORY_SEXUALLY_EXPLICIT\",\n", " \"probability\": \"NEGLIGIBLE\"\n", " },\n", " {\n", " \"category\": \"HARM_CATEGORY_HATE_SPEECH\",\n", " \"probability\": \"NEGLIGIBLE\"\n", " },\n", " {\n", " \"category\": \"HARM_CATEGORY_HARASSMENT\",\n", " \"probability\": \"NEGLIGIBLE\"\n", " },\n", " {\n", " \"category\": \"HARM_CATEGORY_DANGEROUS_CONTENT\",\n", " \"probability\": \"NEGLIGIBLE\"\n", " }\n", " ]\n", " }\n", "}\n" ] } ], "source": [ "%%bash\n", "\n", "curl \"https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=$GOOGLE_API_KEY\" \\\n", " -H 'Content-Type: application/json' \\\n", " -d '{\n", " \"contents\": [{\n", " \"role\": \"user\",\n", " \"parts\": [{\n", " \"text\": \"Which theaters in Mountain View show Barbie movie?\"\n", " }]\n", " }, {\n", " \"role\": \"model\",\n", " \"parts\": [{\n", " \"functionCall\": {\n", " \"name\": \"find_theaters\",\n", " \"args\": {\n", " \"location\": \"Mountain View, CA\",\n", " \"movie\": \"Barbie\"\n", " }\n", " }\n", " }]\n", " }, {\n", " \"role\": \"function\",\n", " \"parts\": [{\n", " \"functionResponse\": {\n", " \"name\": \"find_theaters\",\n", " \"response\": {\n", " \"name\": \"find_theaters\",\n", " \"content\": {\n", " \"movie\": \"Barbie\",\n", " \"theaters\": [{\n", " \"name\": \"AMC Mountain View 16\",\n", " \"address\": \"2000 W El Camino Real, Mountain View, CA 94040\"\n", " }, {\n", " \"name\": \"Regal Edwards 14\",\n", " \"address\": \"245 Castro St, Mountain View, CA 94040\"\n", " }]\n", " }\n", " }\n", " }\n", " }]\n", " },\n", " {\n", " \"role\": \"model\",\n", " \"parts\": [{\n", " \"text\": \" OK. Barbie is showing in two theaters in Mountain View, CA: AMC Mountain View 16 and Regal Edwards 14.\"\n", " }]\n", " },{\n", " \"role\": \"user\",\n", " \"parts\": [{\n", " \"text\": \"Can you recommend some comedy movies on show in Mountain View?\"\n", " }]\n", " }],\n", " \"tools\": [{\n", " \"functionDeclarations\": [{\n", " \"name\": \"find_movies\",\n", " \"description\": \"find movie titles currently playing in theaters based on any description, genre, title words, etc.\",\n", " \"parameters\": {\n", " \"type\": \"OBJECT\",\n", " \"properties\": {\n", " \"location\": {\n", " \"type\": \"STRING\",\n", " \"description\": \"The city and state, e.g. San Francisco, CA or a zip code e.g. 95616\"\n", " },\n", " \"description\": {\n", " \"type\": \"STRING\",\n", " \"description\": \"Any kind of description including category or genre, title words, attributes, etc.\"\n", " }\n", " },\n", " \"required\": [\"description\"]\n", " }\n", " }, {\n", " \"name\": \"find_theaters\",\n", " \"description\": \"find theaters based on location and optionally movie title which are is currently playing in theaters\",\n", " \"parameters\": {\n", " \"type\": \"OBJECT\",\n", " \"properties\": {\n", " \"location\": {\n", " \"type\": \"STRING\",\n", " \"description\": \"The city and state, e.g. San Francisco, CA or a zip code e.g. 95616\"\n", " },\n", " \"movie\": {\n", " \"type\": \"STRING\",\n", " \"description\": \"Any movie title\"\n", " }\n", " },\n", " \"required\": [\"location\"]\n", " }\n", " }, {\n", " \"name\": \"get_showtimes\",\n", " \"description\": \"Find the start times for movies playing in a specific theater\",\n", " \"parameters\": {\n", " \"type\": \"OBJECT\",\n", " \"properties\": {\n", " \"location\": {\n", " \"type\": \"STRING\",\n", " \"description\": \"The city and state, e.g. San Francisco, CA or a zip code e.g. 95616\"\n", " },\n", " \"movie\": {\n", " \"type\": \"STRING\",\n", " \"description\": \"Any movie title\"\n", " },\n", " \"theater\": {\n", " \"type\": \"STRING\",\n", " \"description\": \"Name of the theater\"\n", " },\n", " \"date\": {\n", " \"type\": \"STRING\",\n", " \"description\": \"Date for requested showtime\"\n", " }\n", " },\n", " \"required\": [\"location\", \"movie\", \"theater\", \"date\"]\n", " }\n", " }]\n", " }]\n", "}' 2> /dev/null" ] } ], "metadata": { "colab": { "name": "Function_calling_REST.ipynb", "toc_visible": true }, "kernelspec": { "display_name": "Python 3", "name": "python3" } }, "nbformat": 4, "nbformat_minor": 0 }