Gemini 中文指南
获取 API 密钥 ↗

组合内置工具与函数调用

↓ 下载 Markdown

Gemini 允许组合 内置工具,例如 google_search, 和 函数调用 (也称为 定制工具)通过保留和公开工具调用的上下文历史记录在单次交互中。内置和自定义工具组合可实现复杂、智能体的工作流程,例如,模型可以在调用特定业务逻辑之前将自身置于实时 Web 数据中。

这是一个启用内置和自定义工具组合的示例 google_search 和一个自定义函数 getWeather:

python
# 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-4-hydrogen",
    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.

它是如何运作的 #

Gemini 3型号使用 工具上下文循环 启用内置和自定义工具组合。工具上下文循环使得可以保留和公开内置工具的上下文,并在同一交互中与自定义工具共享它。

启用工具组合 #

API 返回步骤 #

在交互响应中,API 返回内置工具调用和函数(自定义工具)调用的单独步骤:

  • 内置工具步骤:API 自动管理这些,保留各个回合的上下文。

  • 函数调用步骤:API 返回 function_call 自定义函数的步骤。您执行该函数并返回结果。

返回步骤中的关键字段 #

返回步骤中的某些字段对于维护工具上下文和启用工具组合至关重要:

  • id: 发现于 function_call 和 function_response 步骤。将调用映射到其响应的唯一标识符。
  • signature: 发现于 thought 步骤以及所有工具调用(例如, function_call)和结果(例如, function_response) Gemini 3+ 型号的步骤。这种加密的上下文使得 工具上下文循环 跨互动。

管理这些字段:

  • 有状态模式(推荐): 当你使用 previous_interaction_id,服务器自动处理两者 id 和 signature 字段。
  • 无状态模式:手动管理对话历史记录时,您必须确保通过 id 和 signature 在后续请求中将字段返回到模型以验证真实性并维护上下文。如果您将完整的响应对象传递回历史记录,官方 SDK 会自动处理此问题。

特定于工具的数据 #

一些内置工具返回特定于工具类型的用户可见数据参数。

工具

用户可见的工具调用参数(如果有)

用户可见的工具响应(如果有)

谷歌搜索

queries

search_suggestions

谷歌地图

queries

places

google_maps_widget_context_token

网址上下文

urls

需要浏览的URL

status:浏览状态

retrieved_url: 浏览过的网址

文件搜索

无

无

代币和定价 #

请注意,请求中的内置工具调用部分会计入 prompt_token_count。由于这些中间工具步骤现在可见并返回给您,因此它们是对话历史记录的一部分。这仅适用于 要求, 不 回应.

Google 搜索工具是此规则的一个例外。 Google 搜索已经在查询级别应用了自己的定价模型,因此 token 不会重复收费(请参阅 价格 页)。

阅读 token 页面了解更多信息。

限制 #

  • 默认为 validated 模式(auto 当启用工具上下文循环时,不支持模式)。

  • 内置工具如 google_search 依赖于位置和当前时间信息,所以如果您 system_instruction 或 function_declaration.description 位置和时间信息存在冲突,工具组合功能可能无法正常工作。

支持的工具 #

标准工具上下文循环适用于服务器端(内置)工具。代码执行也是一个服务器端工具,但有自己内置的上下文循环解决方案。 Computer Use和函数调用是客户端工具,也有内置的上下文循环解决方案。

工具执行方上下文流通支持
Google 搜索服务器端支持
Google 地图服务器端支持
URL上下文服务器端支持
文件搜索服务器端支持
代码执行服务器端支持(内置、使用 code_execution 和 code_execution_result 步骤)
电脑使用客户端支持(内置、使用 function_call 和 function_response 步骤)
自定义功能客户端支持(内置、使用 function_call 和 function_response 步骤)

后续步骤 #

搜索标题、API 名称或正文内容