本頁面由 Cloud Translation API 翻譯而成。

函式呼叫參照

函式呼叫功能可提升 LLM 提供相關且符合情境答案的能力。

您可以使用 Function Calling API，為生成式 AI 模型提供自訂函式。模型不會直接呼叫這些函式，而是產生結構化資料輸出內容，指定函式名稱和建議的引數。

這項輸出內容可呼叫外部 API 或資訊系統，例如資料庫、客戶關係管理系統和文件存放區。LLM 可使用產生的 API 輸出內容，提升回覆品質。

如要查看函式呼叫的更多概念說明文件，請參閱「函式呼叫」。

支援的模型

Gemini 3 Pro 預先發布版模型
Gemini 2.5 Pro
Gemini 2.5 Flash 預先發布版模型
Gemini 2.5 Flash-Lite 預先發布版模型
Gemini 2.5 Flash
Gemini 2.5 Flash-Lite
Gemini 2.5 Flash (支援 Live API 原生音訊) 預先發布版模型
Gemini 2.0 Flash with Live API Preview model
Gemini 2.0 Flash
Gemini 2.0 Flash-Lite

限制：

要求中提供的函式宣告數量上限為 128 個。

語法範例

傳送函式呼叫 API 要求的語法。

curl

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \

https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/${MODEL_ID}:generateContent \
-d '{
  "contents": [{
    ...
  }],
  "tools": [{
    "function_declarations": [
      {
        ...
      }
    ]
  }]
}'

參數清單

如需實作詳情，請參閱範例。

`FunctionDeclaration`

定義模型可根據 OpenAPI 3.0 規格產生 JSON 輸入內容的函式。

參數
`name`	`string` 要呼叫的函式名稱。開頭須為英文字母或底線，必須是 a-z、A-Z、0-9，或包含底線、半形句點或破折號，長度上限為 64 個字元。
`description`	選填：`string` 函式的說明和用途。模型會根據這項資訊，決定如何及是否呼叫函式。為獲得最佳結果，建議您加入說明。
`parameters`	選填：`Schema` 以 OpenAPI JSON 結構定義物件格式說明函式的參數：OpenAPI 3.0 規格。
`response`	選填：`Schema` 以 OpenAPI JSON 結構定義物件格式說明函式的輸出內容：OpenAPI 3.0 規格。

詳情請參閱「函式呼叫」一文。

`Schema`

根據 OpenAPI 3.0 結構定義規格，定義函式呼叫中輸入和輸出資料的格式。

參數
類型	`string` Enum。資料類型。必須是下列其中一項： `STRING` `INTEGER` `BOOLEAN` `NUMBER` `ARRAY` `OBJECT`
`description`	選填：`string` 資料說明。
`enum`	選填：`string[]` 具有列舉格式的原始型別元素可能值。
`items`	選填：`Schema[]` `Type.ARRAY` 元素的結構定義
`properties`	選填：`Schema` 「`Type.OBJECT`」屬性的結構定義
`required`	選填：`string[]` `Type.OBJECT` 的必要屬性。
`nullable`	選填：`bool` 指出值是否可能為 `null`。

`FunctionCallingConfig`

FunctionCallingConfig 可控制模型的行為，並決定要呼叫的函式類型。

參數

參數
`mode`	選填：`enum/string[]` `AUTO`：預設模型行為。模型可以函式呼叫或自然語言回應的形式進行預測。模型會根據脈絡決定要使用哪種形式。 `NONE`：模型不會以函式呼叫的形式進行任何預測。 `ANY`：模型一律會預測函式呼叫。如果未提供 `allowed_function_names`，模型會從所有可用的函式宣告中挑選。如果提供 `allowed_function_names`，模型會從允許的函式集中挑選。
`allowed_function_names`	選填：`string[]` 要呼叫的函式名稱。只有在 `mode` 為 `ANY` 時，才需要設定這個選項。函式名稱應與 `[FunctionDeclaration.name]` 相符。如果模式設為 `ANY`，模型會從提供的函式名稱集預測函式呼叫。
`stream_function_call_arguments`	選填：`boolean` 如果 `true`，函式呼叫引數會以區塊形式逐步串流傳回。預設值為 `false`。

mode

選填：enum/string[]

AUTO：預設模型行為。模型可以函式呼叫或自然語言回應的形式進行預測。模型會根據脈絡決定要使用哪種形式。
NONE：模型不會以函式呼叫的形式進行任何預測。
ANY：模型一律會預測函式呼叫。如果未提供 allowed_function_names，模型會從所有可用的函式宣告中挑選。如果提供 allowed_function_names，模型會從允許的函式集中挑選。

allowed_function_names

選填：string[]

要呼叫的函式名稱。只有在 mode 為 ANY 時，才需要設定這個選項。函式名稱應與 [FunctionDeclaration.name] 相符。如果模式設為 ANY，模型會從提供的函式名稱集預測函式呼叫。

stream_function_call_arguments

選填：boolean

如果 true，函式呼叫引數會以區塊形式逐步串流傳回。預設值為 false。

`functionCall`

模型傳回的預測 functionCall，其中包含代表 functionDeclaration.name 的字串，以及包含參數及其值的結構化 JSON 物件。

參數

參數
`name`	`string` 要呼叫的函式名稱。
`args`	`Struct` JSON 物件格式的函式參數和值。如需參數詳細資料，請參閱「函式呼叫」。
`thought_signature`	選填：`string` 這是不透明權杖，可封裝模型的內部推理狀態。如果存在，則必須納入下一輪對話，才能維持多步驟工具使用的脈絡。

name

string

要呼叫的函式名稱。

args

Struct

JSON 物件格式的函式參數和值。

如需參數詳細資料，請參閱「函式呼叫」。

thought_signature

選填：string

這是不透明權杖，可封裝模型的內部推理狀態。如果存在，則必須納入下一輪對話，才能維持多步驟工具使用的脈絡。

`functionResponse`

從 FunctionCall 產生的輸出內容，其中包含代表 FunctionDeclaration.name 的字串。也包含結構化 JSON 物件，內含函式的輸出內容 (並將其做為模型的背景資訊)。其中應包含根據模型預測結果製作的 FunctionCall。

參數

參數
`name`	`string` 要呼叫的函式名稱。
`response`	`Struct` JSON 物件格式的函式回應。
`parts`	選填：`FunctionResponsePart[]` 函式回覆中的選用多模態部分。可用於傳回圖片、音訊或影片，以及結構化 JSON 回應。

name

string

要呼叫的函式名稱。

response

Struct

JSON 物件格式的函式回應。

parts

選填：FunctionResponsePart[]

函式回覆中的選用多模態部分。可用於傳回圖片、音訊或影片，以及結構化 JSON 回應。

`FunctionResponsePart`

FunctionResponsePart 包含函式呼叫的多模態資料。

參數

參數
`inline_data`	選填：`FunctionResponseBlob` 函式回應部分的內嵌資料。
`file_data`	選填：`FunctionResponseFileData` 函式回應部分的 URI 相關資料。

inline_data

選填：FunctionResponseBlob

函式回應部分的內嵌資料。

file_data

選填：FunctionResponseFileData

函式回應部分的 URI 相關資料。

`FunctionResponseBlob`

FunctionResponseBlob 包含 FunctionResponsePart 的內嵌資料。

參數

參數
`mime_type`	`string` 內嵌資料的 IANA MIME 類型。
`data`	`bytes` 原始二進位資料。
`display_name`	選填：`string` 內嵌資料的顯示名稱。

mime_type

string

內嵌資料的 IANA MIME 類型。

data

bytes

原始二進位資料。

display_name

選填：string

內嵌資料的顯示名稱。

`FunctionResponseFileData`

FunctionResponseFileData 包含 FunctionResponsePart 的 URI 型資料。

參數

參數
`mime_type`	`string` 檔案資料的 IANA MIME 類型。
`file_uri`	`string` 檔案資料的 URI。
`display_name`	選填：`string` 檔案資料的顯示名稱。

mime_type

string

檔案資料的 IANA MIME 類型。

file_uri

string

檔案資料的 URI。

display_name

選填：string

檔案資料的顯示名稱。

範例

傳送函式宣告

以下是將查詢和函式宣告傳送至模型的基本範例：

REST

使用任何要求資料之前，請先替換以下項目：

PROJECT_ID：您的專案 ID。
MODEL_ID：正在處理的模型 ID。
ROLE：建立訊息的實體身分。
TEXT：要傳送給模型的提示。
NAME：要呼叫的函式名稱。
DESCRIPTION：函式的說明和用途。
如需其他欄位，請參閱「參數清單」表格。

HTTP 方法和網址：

POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/MODEL_ID:generateContent

JSON 要求內文：

{
  "contents": [{
    "role": "ROLE",
    "parts": [{
      "text": "TEXT"
    }]
  }],
  "tools": [{
    "function_declarations": [
      {
        "name": "NAME",
        "description": "DESCRIPTION",
        "parameters": {
          "type": "TYPE",
          "properties": {
            "location": {
              "type": "TYPE",
              "description": "DESCRIPTION"
            }
          },
          "required": [
            "location"
          ]
        }
      }
    ]
  }]
}

如要傳送要求，請選擇以下其中一個選項：

curl

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login 透過使用者帳戶登入 gcloud CLI，或是使用 Cloud Shell 自動登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求內文儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/MODEL_ID:generateContent"

PowerShell

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/MODEL_ID:generateContent" | Select-Object -Expand Content

cURL 指令範例

PROJECT_ID=myproject
LOCATION=us-central1
MODEL_ID=gemini-2.5-flash

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/${MODEL_ID}:generateContent \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{
        "text": "What is the weather in Boston?"
      }]
    }],
    "tools": [{
      "functionDeclarations": [
        {
          "name": "get_current_weather",
          "description": "Get the current weather in a given location",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, for example San Francisco, CA or a zip code such as 95616"
              }
            },
            "required": [
              "location"
            ]
          }
        }
      ]
    }]
  }'

Gen AI SDK for Python

from google import genai
from google.genai.types import GenerateContentConfig, HttpOptions

def get_current_weather(location: str) -> str:
    """Example method. Returns the current weather.

    Args:
        location: The city and state, e.g. San Francisco, CA
    """
    weather_map: dict[str, str] = {
        "Boston, MA": "snowing",
        "San Francisco, CA": "foggy",
        "Seattle, WA": "raining",
        "Austin, TX": "hot",
        "Chicago, IL": "windy",
    }
    return weather_map.get(location, "unknown")

client = genai.Client(http_options=HttpOptions(api_version="v1"))
model_id = "gemini-2.5-flash"

response = client.models.generate_content(
    model=model_id,
    contents="What is the weather like in Boston?",
    config=GenerateContentConfig(
        tools=[get_current_weather],
        temperature=0,
    ),
)

print(response.text)
# Example response:
# The weather in Boston is sunny.

Node.js

const {
  VertexAI,
  FunctionDeclarationSchemaType,
} = require('@google-cloud/vertexai');

const functionDeclarations = [
  {
    function_declarations: [
      {
        name: 'get_current_weather',
        description: 'get weather in a given location',
        parameters: {
          type: FunctionDeclarationSchemaType.OBJECT,
          properties: {
            location: {type: FunctionDeclarationSchemaType.STRING},
            unit: {
              type: FunctionDeclarationSchemaType.STRING,
              enum: ['celsius', 'fahrenheit'],
            },
          },
          required: ['location'],
        },
      },
    ],
  },
];

/**
 * TODO(developer): Update these variables before running the sample.
 */
async function functionCallingBasic(
  projectId = 'PROJECT_ID',
  location = 'us-central1',
  model = 'gemini-2.0-flash-001'
) {
  // Initialize Vertex with your Cloud project and location
  const vertexAI = new VertexAI({project: projectId, location: location});

  // Instantiate the model
  const generativeModel = vertexAI.preview.getGenerativeModel({
    model: model,
  });

  const request = {
    contents: [
      {role: 'user', parts: [{text: 'What is the weather in Boston?'}]},
    ],
    tools: functionDeclarations,
  };
  const result = await generativeModel.generateContent(request);
  console.log(JSON.stringify(result.response.candidates[0].content));
}

Java

import com.google.cloud.vertexai.VertexAI;
import com.google.cloud.vertexai.api.Content;
import com.google.cloud.vertexai.api.FunctionDeclaration;
import com.google.cloud.vertexai.api.GenerateContentResponse;
import com.google.cloud.vertexai.api.Schema;
import com.google.cloud.vertexai.api.Tool;
import com.google.cloud.vertexai.api.Type;
import com.google.cloud.vertexai.generativeai.ChatSession;
import com.google.cloud.vertexai.generativeai.ContentMaker;
import com.google.cloud.vertexai.generativeai.GenerativeModel;
import com.google.cloud.vertexai.generativeai.PartMaker;
import com.google.cloud.vertexai.generativeai.ResponseHandler;
import java.io.IOException;
import java.util.Arrays;
import java.util.Collections;

public class FunctionCalling {
  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-google-cloud-project-id";
    String location = "us-central1";
    String modelName = "gemini-2.0-flash-001";

    String promptText = "What's the weather like in Paris?";

    whatsTheWeatherLike(projectId, location, modelName, promptText);
  }

  // A request involving the interaction with an external tool
  public static String whatsTheWeatherLike(String projectId, String location,
                                           String modelName, String promptText)
      throws IOException {
    // Initialize client that will be used to send requests.
    // This client only needs to be created once, and can be reused for multiple requests.
    try (VertexAI vertexAI = new VertexAI(projectId, location)) {

      FunctionDeclaration functionDeclaration = FunctionDeclaration.newBuilder()
          .setName("getCurrentWeather")
          .setDescription("Get the current weather in a given location")
          .setParameters(
              Schema.newBuilder()
                  .setType(Type.OBJECT)
                  .putProperties("location", Schema.newBuilder()
                      .setType(Type.STRING)
                      .setDescription("location")
                      .build()
                  )
                  .addRequired("location")
                  .build()
          )
          .build();

      System.out.println("Function declaration:");
      System.out.println(functionDeclaration);

      // Add the function to a "tool"
      Tool tool = Tool.newBuilder()
          .addFunctionDeclarations(functionDeclaration)
          .build();

      // Start a chat session from a model, with the use of the declared function.
      GenerativeModel model = new GenerativeModel(modelName, vertexAI)
          .withTools(Arrays.asList(tool));
      ChatSession chat = model.startChat();

      System.out.println(String.format("Ask the question: %s", promptText));
      GenerateContentResponse response = chat.sendMessage(promptText);

      // The model will most likely return a function call to the declared
      // function `getCurrentWeather` with "Paris" as the value for the
      // argument `location`.
      System.out.println("\nPrint response: ");
      System.out.println(ResponseHandler.getContent(response));

      // Provide an answer to the model so that it knows what the result
      // of a "function call" is.
      Content content =
          ContentMaker.fromMultiModalData(
              PartMaker.fromFunctionResponse(
                  "getCurrentWeather",
                  Collections.singletonMap("currentWeather", "sunny")));
      System.out.println("Provide the function response: ");
      System.out.println(content);
      response = chat.sendMessage(content);

      // See what the model replies now
      System.out.println("Print response: ");
      String finalAnswer = ResponseHandler.getText(response);
      System.out.println(finalAnswer);

      return finalAnswer;
    }
  }
}

Go

import (
	"context"
	"fmt"
	"io"

	genai "google.golang.org/genai"
)

// generateWithFuncCall shows how to submit a prompt and a function declaration to the model,
// allowing it to suggest a call to the function to fetch external data. Returning this data
// enables the model to generate a text response that incorporates the data.
func generateWithFuncCall(w io.Writer) error {
	ctx := context.Background()

	client, err := genai.NewClient(ctx, &genai.ClientConfig{
		HTTPOptions: genai.HTTPOptions{APIVersion: "v1"},
	})
	if err != nil {
		return fmt.Errorf("failed to create genai client: %w", err)
	}

	weatherFunc := &genai.FunctionDeclaration{
		Description: "Returns the current weather in a location.",
		Name:        "getCurrentWeather",
		Parameters: &genai.Schema{
			Type: "object",
			Properties: map[string]*genai.Schema{
				"location": {Type: "string"},
			},
			Required: []string{"location"},
		},
	}
	config := &genai.GenerateContentConfig{
		Tools: []*genai.Tool{
			{FunctionDeclarations: []*genai.FunctionDeclaration{weatherFunc}},
		},
		Temperature: genai.Ptr(float32(0.0)),
	}

	modelName := "gemini-2.5-flash"
	contents := []*genai.Content{
		{Parts: []*genai.Part{
			{Text: "What is the weather like in Boston?"},
		},
			Role: "user"},
	}

	resp, err := client.Models.GenerateContent(ctx, modelName, contents, config)
	if err != nil {
		return fmt.Errorf("failed to generate content: %w", err)
	}

	var funcCall *genai.FunctionCall
	for _, p := range resp.Candidates[0].Content.Parts {
		if p.FunctionCall != nil {
			funcCall = p.FunctionCall
			fmt.Fprint(w, "The model suggests to call the function ")
			fmt.Fprintf(w, "%q with args: %v\n", funcCall.Name, funcCall.Args)
			// Example response:
			// The model suggests to call the function "getCurrentWeather" with args: map[location:Boston]
		}
	}
	if funcCall == nil {
		return fmt.Errorf("model did not suggest a function call")
	}

	// Use synthetic data to simulate a response from the external API.
	// In a real application, this would come from an actual weather API.
	funcResp := &genai.FunctionResponse{
		Name: "getCurrentWeather",
		Response: map[string]any{
			"location":         "Boston",
			"temperature":      "38",
			"temperature_unit": "F",
			"description":      "Cold and cloudy",
			"humidity":         "65",
			"wind":             `{"speed": "10", "direction": "NW"}`,
		},
	}

	// Return conversation turns and API response to complete the model's response.
	contents = []*genai.Content{
		{Parts: []*genai.Part{
			{Text: "What is the weather like in Boston?"},
		},
			Role: "user"},
		{Parts: []*genai.Part{
			{FunctionCall: funcCall},
		}},
		{Parts: []*genai.Part{
			{FunctionResponse: funcResp},
		}},
	}

	resp, err = client.Models.GenerateContent(ctx, modelName, contents, config)
	if err != nil {
		return fmt.Errorf("failed to generate content: %w", err)
	}

	respText := resp.Text()

	fmt.Fprintln(w, respText)

	// Example response:
	// The weather in Boston is cold and cloudy with a temperature of 38 degrees Fahrenheit. The humidity is ...

	return nil
}

REST (OpenAI)

您可以使用 OpenAI 程式庫呼叫函式呼叫 API。詳情請參閱使用 OpenAI 程式庫呼叫 Vertex AI 模型。

使用任何要求資料之前，請先替換以下項目：

PROJECT_ID：。
MODEL_ID：正在處理的模型 ID。

HTTP 方法和網址：

POST https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/endpoints/openapi/chat/completions

JSON 要求內文：

{
  "model": "google/MODEL_ID",
  "messages": [
    {
      "role": "user",
      "content": "What is the weather in Boston?"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_current_weather",
        "description": "Get the current weather in a given location",
        "parameters": {
          "type": "OBJECT",
          "properties": {
            "location": {
              "type": "string",
              "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
            }
           },
          "required": ["location"]
        }
      }
    }
  ]
}

如要傳送要求，請選擇以下其中一個選項：

curl

將要求內文儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/endpoints/openapi/chat/completions"

PowerShell

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/endpoints/openapi/chat/completions" | Select-Object -Expand Content

Python (OpenAI)

您可以使用 OpenAI 程式庫呼叫函式呼叫 API。詳情請參閱「使用 OpenAI 程式庫呼叫 Vertex AI 模型」。

import vertexai
import openai

from google.auth import default, transport

# TODO(developer): Update & uncomment below line
# PROJECT_ID = "your-project-id"
location = "us-central1"

vertexai.init(project=PROJECT_ID, location=location)

# Programmatically get an access token
credentials, _ = default(scopes=["https://www.googleapis.com/auth/cloud-platform"])
auth_request = transport.requests.Request()
credentials.refresh(auth_request)

# # OpenAI Client
client = openai.OpenAI(
    base_url=f"https://{location}-aiplatform.googleapis.com/v1beta1/projects/{PROJECT_ID}/locations/{location}/endpoints/openapi",
    api_key=credentials.token,
)

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_current_weather",
            "description": "Get the current weather in a given location",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616",
                    },
                },
                "required": ["location"],
            },
        },
    }
]

messages = []
messages.append(
    {
        "role": "system",
        "content": "Don't make assumptions about what values to plug into functions. Ask for clarification if a user request is ambiguous.",
    }
)
messages.append({"role": "user", "content": "What is the weather in Boston?"})

response = client.chat.completions.create(
    model="google/gemini-2.0-flash-001",
    messages=messages,
    tools=tools,
)

print("Function:", response.choices[0].message.tool_calls[0].id)
print("Arguments:", response.choices[0].message.tool_calls[0].function.arguments)
# Example response:
# Function: get_current_weather
# Arguments: {"location":"Boston"}

使用 `FunctionCallingConfig` 傳送函式宣告

以下範例說明如何將 FunctionCallingConfig 傳遞至模型：

functionCallingConfig 可確保模型輸出內容一律為特定函式呼叫。設定方式：

將函式呼叫 mode 設為 ANY。
在 allowed_function_names 中指定要使用的函式名稱。如果 allowed_function_names 為空，可以傳回任何提供的函式。

REST

PROJECT_ID=myproject
LOCATION=us-central1
MODEL_ID=gemini-2.5-flash

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/${MODEL_ID}:generateContent \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{
        "text": "Do you have the White Pixel 8 Pro 128GB in stock in the US?"
      }]
    }],
    "tools": [{
      "functionDeclarations": [
        {
          "name": "get_product_sku",
          "description": "Get the available inventory for a Google products, for example: Pixel phones, Pixel Watches, Google Home etc",
          "parameters": {
            "type": "object",
            "properties": {
              "product_name": {"type": "string", "description": "Product name"}
            }
          }
        },
        {
          "name": "get_store_location",
          "description": "Get the location of the closest store",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {"type": "string", "description": "Location"}
            },
          }
        }
      ]
    }],
    "toolConfig": {
        "functionCallingConfig": {
            "mode":"ANY",
            "allowedFunctionNames": ["get_product_sku"]
      }
    },
    "generationConfig": {
      "temperature": 0.95,
      "topP": 1.0,
      "maxOutputTokens": 8192
    }
  }'

Gen AI SDK for Python

from google import genai
from google.genai.types import (
    FunctionDeclaration,
    GenerateContentConfig,
    HttpOptions,
    Tool,
)

client = genai.Client(http_options=HttpOptions(api_version="v1"))
model_id = "gemini-2.5-flash"

get_album_sales = FunctionDeclaration(
    name="get_album_sales",
    description="Gets the number of albums sold",
    # Function parameters are specified in JSON schema format
    parameters={
        "type": "OBJECT",
        "properties": {
            "albums": {
                "type": "ARRAY",
                "description": "List of albums",
                "items": {
                    "description": "Album and its sales",
                    "type": "OBJECT",
                    "properties": {
                        "album_name": {
                            "type": "STRING",
                            "description": "Name of the music album",
                        },
                        "copies_sold": {
                            "type": "INTEGER",
                            "description": "Number of copies sold",
                        },
                    },
                },
            },
        },
    },
)

sales_tool = Tool(
    function_declarations=[get_album_sales],
)

response = client.models.generate_content(
    model=model_id,
    contents='At Stellar Sounds, a music label, 2024 was a rollercoaster. "Echoes of the Night," a debut synth-pop album, '
    'surprisingly sold 350,000 copies, while veteran rock band "Crimson Tide\'s" latest, "Reckless Hearts," '
    'lagged at 120,000. Their up-and-coming indie artist, "Luna Bloom\'s" EP, "Whispers of Dawn," '
    'secured 75,000 sales. The biggest disappointment was the highly-anticipated rap album "Street Symphony" '
    "only reaching 100,000 units. Overall, Stellar Sounds moved over 645,000 units this year, revealing unexpected "
    "trends in music consumption.",
    config=GenerateContentConfig(
        tools=[sales_tool],
        temperature=0,
    ),
)

print(response.function_calls)
# Example response:
# [FunctionCall(
#     id=None,
#     name="get_album_sales",
#     args={
#         "albums": [
#             {"album_name": "Echoes of the Night", "copies_sold": 350000},
#             {"copies_sold": 120000, "album_name": "Reckless Hearts"},
#             {"copies_sold": 75000, "album_name": "Whispers of Dawn"},
#             {"copies_sold": 100000, "album_name": "Street Symphony"},
#         ]
#     },
# )]

Node.js

const {
  VertexAI,
  FunctionDeclarationSchemaType,
} = require('@google-cloud/vertexai');

const functionDeclarations = [
  {
    function_declarations: [
      {
        name: 'get_product_sku',
        description:
          'Get the available inventory for a Google products, e.g: Pixel phones, Pixel Watches, Google Home etc',
        parameters: {
          type: FunctionDeclarationSchemaType.OBJECT,
          properties: {
            productName: {type: FunctionDeclarationSchemaType.STRING},
          },
        },
      },
      {
        name: 'get_store_location',
        description: 'Get the location of the closest store',
        parameters: {
          type: FunctionDeclarationSchemaType.OBJECT,
          properties: {
            location: {type: FunctionDeclarationSchemaType.STRING},
          },
        },
      },
    ],
  },
];

const toolConfig = {
  function_calling_config: {
    mode: 'ANY',
    allowed_function_names: ['get_product_sku'],
  },
};

const generationConfig = {
  temperature: 0.95,
  topP: 1.0,
  maxOutputTokens: 8192,
};

/**
 * TODO(developer): Update these variables before running the sample.
 */
async function functionCallingAdvanced(
  projectId = 'PROJECT_ID',
  location = 'us-central1',
  model = 'gemini-2.0-flash-001'
) {
  // Initialize Vertex with your Cloud project and location
  const vertexAI = new VertexAI({project: projectId, location: location});

  // Instantiate the model
  const generativeModel = vertexAI.preview.getGenerativeModel({
    model: model,
  });

  const request = {
    contents: [
      {
        role: 'user',
        parts: [
          {text: 'Do you have the White Pixel 8 Pro 128GB in stock in the US?'},
        ],
      },
    ],
    tools: functionDeclarations,
    tool_config: toolConfig,
    generation_config: generationConfig,
  };
  const result = await generativeModel.generateContent(request);
  console.log(JSON.stringify(result.response.candidates[0].content));
}

Go

import (
	"context"
	"encoding/json"
	"errors"
	"fmt"
	"io"

	"cloud.google.com/go/vertexai/genai"
)

// functionCallsChat opens a chat session and sends 4 messages to the model:
// - convert a first text question into a structured function call request
// - convert the first structured function call response into natural language
// - convert a second text question into a structured function call request
// - convert the second structured function call response into natural language
func functionCallsChat(w io.Writer, projectID, location, modelName string) error {
	// location := "us-central1"
	// modelName := "gemini-2.0-flash-001"
	ctx := context.Background()
	client, err := genai.NewClient(ctx, projectID, location)
	if err != nil {
		return fmt.Errorf("unable to create client: %w", err)
	}
	defer client.Close()

	model := client.GenerativeModel(modelName)

	// Build an OpenAPI schema, in memory
	paramsProduct := &genai.Schema{
		Type: genai.TypeObject,
		Properties: map[string]*genai.Schema{
			"productName": {
				Type:        genai.TypeString,
				Description: "Product name",
			},
		},
	}
	fundeclProductInfo := &genai.FunctionDeclaration{
		Name:        "getProductSku",
		Description: "Get the SKU for a product",
		Parameters:  paramsProduct,
	}
	paramsStore := &genai.Schema{
		Type: genai.TypeObject,
		Properties: map[string]*genai.Schema{
			"location": {
				Type:        genai.TypeString,
				Description: "Location",
			},
		},
	}
	fundeclStoreLocation := &genai.FunctionDeclaration{
		Name:        "getStoreLocation",
		Description: "Get the location of the closest store",
		Parameters:  paramsStore,
	}
	model.Tools = []*genai.Tool{
		{FunctionDeclarations: []*genai.FunctionDeclaration{
			fundeclProductInfo,
			fundeclStoreLocation,
		}},
	}
	model.SetTemperature(0.0)

	chat := model.StartChat()

	// Send a prompt for the first conversation turn that should invoke the getProductSku function
	prompt := "Do you have the Pixel 8 Pro in stock?"
	fmt.Fprintf(w, "Question: %s\n", prompt)
	resp, err := chat.SendMessage(ctx, genai.Text(prompt))
	if err != nil {
		return err
	}
	if len(resp.Candidates) == 0 ||
		len(resp.Candidates[0].Content.Parts) == 0 {
		return errors.New("empty response from model")
	}

	// The model has returned a function call to the declared function `getProductSku`
	// with a value for the argument `productName`.
	jsondata, err := json.MarshalIndent(resp.Candidates[0].Content.Parts[0], "\t", "  ")
	if err != nil {
		return fmt.Errorf("json.MarshalIndent: %w", err)
	}
	fmt.Fprintf(w, "function call generated by the model:\n\t%s\n", string(jsondata))

	// Create a function call response, to simulate the result of a call to a
	// real service
	funresp := &genai.FunctionResponse{
		Name: "getProductSku",
		Response: map[string]any{
			"sku":      "GA04834-US",
			"in_stock": "yes",
		},
	}
	jsondata, err = json.MarshalIndent(funresp, "\t", "  ")
	if err != nil {
		return fmt.Errorf("json.MarshalIndent: %w", err)
	}
	fmt.Fprintf(w, "function call response sent to the model:\n\t%s\n\n", string(jsondata))

	// And provide the function call response to the model
	resp, err = chat.SendMessage(ctx, funresp)
	if err != nil {
		return err
	}
	if len(resp.Candidates) == 0 ||
		len(resp.Candidates[0].Content.Parts) == 0 {
		return errors.New("empty response from model")
	}

	// The model has taken the function call response as input, and has
	// reformulated the response to the user.
	jsondata, err = json.MarshalIndent(resp.Candidates[0].Content.Parts[0], "\t", "  ")
	if err != nil {
		return fmt.Errorf("json.MarshalIndent: %w", err)
	}
	fmt.Fprintf(w, "Answer generated by the model:\n\t%s\n\n", string(jsondata))

	// Send a prompt for the second conversation turn that should invoke the getStoreLocation function
	prompt2 := "Is there a store in Mountain View, CA that I can visit to try it out?"
	fmt.Fprintf(w, "Question: %s\n", prompt)

	resp, err = chat.SendMessage(ctx, genai.Text(prompt2))
	if err != nil {
		return err
	}
	if len(resp.Candidates) == 0 ||
		len(resp.Candidates[0].Content.Parts) == 0 {
		return errors.New("empty response from model")
	}

	// The model has returned a function call to the declared function `getStoreLocation`
	// with a value for the argument `store`.
	jsondata, err = json.MarshalIndent(resp.Candidates[0].Content.Parts[0], "\t", "  ")
	if err != nil {
		return fmt.Errorf("json.MarshalIndent: %w", err)
	}
	fmt.Fprintf(w, "function call generated by the model:\n\t%s\n", string(jsondata))

	// Create a function call response, to simulate the result of a call to a
	// real service
	funresp = &genai.FunctionResponse{
		Name: "getStoreLocation",
		Response: map[string]any{
			"store": "2000 N Shoreline Blvd, Mountain View, CA 94043, US",
		},
	}
	jsondata, err = json.MarshalIndent(funresp, "\t", "  ")
	if err != nil {
		return fmt.Errorf("json.MarshalIndent: %w", err)
	}
	fmt.Fprintf(w, "function call response sent to the model:\n\t%s\n\n", string(jsondata))

	// And provide the function call response to the model
	resp, err = chat.SendMessage(ctx, funresp)
	if err != nil {
		return err
	}
	if len(resp.Candidates) == 0 ||
		len(resp.Candidates[0].Content.Parts) == 0 {
		return errors.New("empty response from model")
	}

	// The model has taken the function call response as input, and has
	// reformulated the response to the user.
	jsondata, err = json.MarshalIndent(resp.Candidates[0].Content.Parts[0], "\t", "  ")
	if err != nil {
		return fmt.Errorf("json.MarshalIndent: %w", err)
	}
	fmt.Fprintf(w, "Answer generated by the model:\n\t%s\n\n", string(jsondata))
	return nil
}

REST (OpenAI)

您可以使用 OpenAI 程式庫呼叫函式呼叫 API。詳情請參閱使用 OpenAI 程式庫呼叫 Vertex AI 模型。

使用任何要求資料之前，請先替換以下項目：

PROJECT_ID：。
MODEL_ID：正在處理的模型 ID。

HTTP 方法和網址：

POST https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/endpoints/openapi/chat/completions

JSON 要求內文：

{
  "model": "google/MODEL_ID",
  "messages": [
  {
    "role": "user",
    "content": "What is the weather in Boston?"
  }
],
"tools": [
  {
    "type": "function",
    "function": {
      "name": "get_current_weather",
      "description": "Get the current weather in a given location",
      "parameters": {
        "type": "OBJECT",
        "properties": {
          "location": {
            "type": "string",
            "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
          }
         },
        "required": ["location"]
      }
    }
  }
],
"tool_choice": "auto"
}

如要傳送要求，請選擇以下其中一個選項：

curl

將要求內文儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/endpoints/openapi/chat/completions"

PowerShell

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/endpoints/openapi/chat/completions" | Select-Object -Expand Content

Python (OpenAI)

您可以使用 OpenAI 程式庫呼叫函式呼叫 API。詳情請參閱「使用 OpenAI 程式庫呼叫 Vertex AI 模型」。

import vertexai
import openai

from google.auth import default, transport

# TODO(developer): Update & uncomment below line
# PROJECT_ID = "your-project-id"
location = "us-central1"

vertexai.init(project=PROJECT_ID, location=location)

# Programmatically get an access token
credentials, _ = default(scopes=["https://www.googleapis.com/auth/cloud-platform"])
auth_request = transport.requests.Request()
credentials.refresh(auth_request)

# OpenAI Client
client = openai.OpenAI(
    base_url=f"https://{location}-aiplatform.googleapis.com/v1beta1/projects/{PROJECT_ID}/locations/{location}/endpoints/openapi",
    api_key=credentials.token,
)

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_current_weather",
            "description": "Get the current weather in a given location",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616",
                    },
                },
                "required": ["location"],
            },
        },
    }
]

messages = []
messages.append(
    {
        "role": "system",
        "content": "Don't make assumptions about what values to plug into functions. Ask for clarification if a user request is ambiguous.",
    }
)
messages.append({"role": "user", "content": "What is the weather in Boston, MA?"})

response = client.chat.completions.create(
    model="google/gemini-2.0-flash-001",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

print("Function:", response.choices[0].message.tool_calls[0].id)
print("Arguments:", response.choices[0].message.tool_calls[0].function.arguments)
# Example response:
# Function: get_current_weather
# Arguments: {"location":"Boston"}

後續步驟

如需詳細說明文件，請參閱下列內容：

函式呼叫

函式呼叫參照 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

支援的模型

語法範例

curl

參數清單

FunctionDeclaration

Schema

FunctionCallingConfig

functionCall

functionResponse

FunctionResponsePart

FunctionResponseBlob

FunctionResponseFileData

範例

傳送函式宣告

REST

curl

PowerShell

cURL 指令範例

Gen AI SDK for Python

Node.js

Java

Go

REST (OpenAI)

curl

PowerShell

Python (OpenAI)

使用 FunctionCallingConfig 傳送函式宣告

REST

Gen AI SDK for Python

Node.js

Go

REST (OpenAI)

curl

PowerShell

Python (OpenAI)

後續步驟

函式呼叫參照

`FunctionDeclaration`

`Schema`

`FunctionCallingConfig`

`functionCall`

`functionResponse`

`FunctionResponsePart`

`FunctionResponseBlob`

`FunctionResponseFileData`

使用 `FunctionCallingConfig` 傳送函式宣告