Kết hợp các công cụ tích hợp và tính năng gọi hàm

Gemini cho phép kết hợp các công cụ tích hợp sẵn, chẳng hạn như google_search, và tính năng gọi hàm (còn gọi là công cụ tuỳ chỉnh) trong một lượt tương tác duy nhất bằng cách giữ nguyên và hiển thị nhật ký bối cảnh của các lệnh gọi công cụ. Các tổ hợp công cụ tuỳ chỉnh và tích hợp sẵn cho phép các quy trình công việc phức tạp, có tính đại diện, trong đó, ví dụ: mô hình có thể tự dựa vào dữ liệu web theo thời gian thực trước khi gọi logic kinh doanh cụ thể của bạn.

Sau đây là ví dụ cho phép kết hợp các công cụ tuỳ chỉnh và tích hợp sẵn với google_search và hàm tuỳ chỉnh getWeather:

# This will only work for SDK newer than 2.0.0
from google import genai

client = genai.Client()

getWeather = {
    "type": "function",
    "name": "getWeather",
    "description": "Gets the weather for a requested city.",
    "parameters": {
        "type": "object",
        "properties": {
            "city": {
                "type": "string",
                "description": "The city and state, e.g. Utqiaġvik, Alaska",
            },
        },
        "required": ["city"],
    },
}

# The Interactions API manages context automatically across tool calls.
# The model will first use Google Search, then call getWeather.
interaction = client.interactions.create(
    model="gemini-3.5-flash",
    input="What is the northernmost city in the United States? What's the weather like there today?",
    tools=[
        {"type": "google_search"},
        getWeather,
    ],
)

# Process steps: the interaction contains search results and a function call
for step in interaction.steps:
    if step.type == "function_call":
        print(f"Function call: {step.name} with args: {step.arguments}")
        # In a real application, you would execute the function here
        # and provide the result back to the model.

// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({});

const getWeather = {
    type: "function",
    name: "getWeather",
    description: "Get the weather in a given location",
    parameters: {
        type: "object",
        properties: {
            location: {
                type: "string",
                description: "The city and state, e.g. San Francisco, CA"
            }
        },
        required: ["location"]
    }
};

// The Interactions API manages context automatically across tool calls.
// The model will first use Google Search, then call getWeather.
const interaction = await client.interactions.create({
    model: "gemini-3.5-flash",
    input: "What is the northernmost city in the United States? What's the weather like there today?",
    tools: [
        { type: "google_search" },
        getWeather,
    ],
});

// Process steps: the interaction contains search results and a function call
for (const step of interaction.steps) {
    if (step.type === "function_call") {
        console.log(`Function call: ${step.name} with args: ${JSON.stringify(step.arguments)}`);
        // In a real application, you would execute the function here
        // and provide the result back to the model.
    }
}

# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
  "model": "gemini-3.5-flash",
  "input": "What is the northernmost city in the United States? What'\''s the weather like there today?",
  "tools": [
    { "type": "google_search" },
    {
      "type": "function",
      "name": "getWeather",
      "description": "Get the weather in a given location",
      "parameters": {
          "type": "object",
          "properties": {
              "location": {
                  "type": "string",
                  "description": "The city and state, e.g. San Francisco, CA"
              }
          },
          "required": ["location"]
      }
    }
  ]
}'

Cách hoạt động

Các mô hình Gemini 3 sử dụng lưu thông bối cảnh công cụ để cho phép kết hợp các công cụ tuỳ chỉnh và tích hợp sẵn. Tính năng lưu thông bối cảnh công cụ giúp giữ nguyên và hiển thị bối cảnh của các công cụ tích hợp sẵn, đồng thời chia sẻ bối cảnh đó với các công cụ tuỳ chỉnh trong cùng một lượt tương tác.

Bật tính năng kết hợp công cụ

• Đưa function_declarations vào cùng với các công cụ tích hợp sẵn mà bạn muốn sử dụng để kích hoạt hành vi kết hợp.

Các bước trả về của API

Trong một phản hồi tương tác, API sẽ trả về các bước riêng biệt cho lệnh gọi công cụ tích hợp sẵn và lệnh gọi hàm (công cụ tuỳ chỉnh):

• Các bước công cụ tích hợp sẵn: API tự động quản lý các bước này, giữ nguyên bối cảnh trên các lượt.
• Các bước gọi hàm: API trả về các bước function_call cho các hàm tuỳ chỉnh của bạn. Bạn thực thi hàm và cung cấp lại kết quả.

Các trường quan trọng trong các bước được trả về

Một số trường trong các bước được trả về là rất quan trọng để duy trì bối cảnh công cụ và cho phép kết hợp công cụ:

• id: Có trong các bước function_call và function_response. Giá trị nhận dạng duy nhất ánh xạ một lệnh gọi đến phản hồi của lệnh gọi đó.
• signature: Có trong các bước thought, cũng như tất cả các bước gọi công cụ (ví dụ: function_call) và kết quả (ví dụ: function_response) cho các mô hình Gemini 3 trở lên. Bối cảnh được mã hoá này cho phép lưu thông bối cảnh công cụ trên các lượt tương tác.

Quản lý các trường này:

• Chế độ có trạng thái (Đề xuất): Khi bạn sử dụng previous_interaction_id, máy chủ sẽ tự động xử lý cả hai trường id và signature.
• Chế độ không trạng thái: Khi quản lý nhật ký cuộc trò chuyện theo cách thủ công, bạn phải đảm bảo rằng bạn truyền cả hai trường id và signature trở lại mô hình trong các yêu cầu tiếp theo để xác thực tính xác thực và duy trì bối cảnh. SDK chính thức sẽ tự động xử lý việc này nếu bạn truyền đối tượng phản hồi đầy đủ trở lại nhật ký.

Dữ liệu dành riêng cho công cụ

Một số công cụ tích hợp sẵn trả về các đối số dữ liệu mà người dùng có thể thấy, dành riêng cho loại công cụ.

Mã thông báo và giá

Xin lưu ý rằng các phần gọi công cụ tích hợp sẵn trong yêu cầu được tính vào prompt_token_count. Vì các bước công cụ trung gian này hiện có thể thấy và được trả về cho bạn, nên chúng là một phần của nhật ký cuộc trò chuyện. Điều này chỉ áp dụng cho trường hợp yêu cầu chứ không áp dụng cho phản hồi.

Công cụ Google Tìm kiếm là một trường hợp ngoại lệ đối với quy tắc này. Google Tìm kiếm đã áp dụng mô hình giá riêng ở cấp truy vấn, vì vậy, mã thông báo không bị tính phí gấp đôi (xem trang Giá).

Đọc trang Mã thông báo để biết thêm thông tin.

Các điểm hạn chế

• Chuyển về chế độ validated theo mặc định (không hỗ trợ chế độ auto) khi bật tính năng lưu thông bối cảnh công cụ.
• Các công cụ tích hợp sẵn như google_search dựa vào thông tin vị trí và thời gian hiện tại. Vì vậy, nếu system_instruction hoặc function_declaration.description có thông tin vị trí và thời gian xung đột, thì tính năng kết hợp công cụ có thể hoạt động không hiệu quả.

Các công cụ được hỗ trợ

Tính năng lưu thông bối cảnh công cụ tiêu chuẩn áp dụng cho các công cụ phía máy chủ (tích hợp sẵn). Tính năng Thực thi mã cũng là một công cụ phía máy chủ, nhưng có giải pháp tích hợp sẵn riêng cho tính năng lưu thông bối cảnh. Tính năng Sử dụng máy tính và gọi hàm là các công cụ phía máy khách, đồng thời cũng có các giải pháp tích hợp sẵn cho tính năng lưu thông bối cảnh.

Bước tiếp theo

• Tìm hiểu thêm về tính năng Gọi hàm trong Gemini API.
• Khám phá các công cụ được hỗ trợ:
  • Google Tìm kiếm
  • Google Maps
  • Bối cảnh URL
  • Tìm kiếm tệp