Gemini API 预览版融合内置工具与函数调用

在 2026-11-03T04:00:00+08:00，谷歌 AI Studio 文档介绍了 Gemini API 的一项预览功能，可结合内置工具与函数调用。该功能支持 Gemini 4 和 Gemini 3 模型，可实现先利用实时网络数据为响应提供依据，再调用自定义业务逻辑等工作流。Interactions API 会在同一次交互中保留并公开工具调用上下文。

Gemini API 将内置工具与自定义函数相结合

Gemini 可以在单次交互中结合使用内置工具（例如 google_search）和函数调用，也称自定义工具。文档介绍了复杂的智能体工作流，其中模型可以先使用实时网络数据，再调用特定于应用程序的逻辑。

示例使用 google_search 和自定义 getWeather 函数。示例指定模型为 gemini-3.8-flash，并指出 Python 示例仅适用于版本高于 2.0.0 的 SDK。Interactions API 会自动管理多次工具调用之间的上下文；示例交互先使用 Google 搜索，然后调用 getWeather。

工具上下文流转可保留交互历史

Gemini 3 模型使用工具上下文流转来保留并公开内置工具的上下文，并在同一次交互中与自定义工具共享上下文。要启用组合行为，开发者需要在内置工具之外一并提供 function_declarations。

API 会分别返回内置工具调用和自定义函数调用的步骤。它会自动管理内置工具步骤，在多轮交互中保留上下文。对于自定义函数，API 会返回 function_call 步骤；开发者执行函数后，再将结果提供给模型。

id 字段会出现在 function_call 和 function_response 步骤中，用于将调用与其响应对应起来。对于 Gemini 3 及更高版本的模型，signature 字段会出现在 thought 步骤以及工具调用和结果步骤中；这种加密上下文可在多次交互中实现工具上下文流转。

在有状态模式下，使用 previous_interaction_id 可让服务器自动处理 id 和 signature 字段。在无状态模式下，开发者需要手动管理对话历史，并在后续请求中将这两个字段传回模型，以验证真实性并维持上下文。当完整响应对象被传回历史记录时，官方 SDK 会自动处理这些字段。

Gemini 工具组合有令牌和模式限制

请求中的内置工具调用部分会计入 prompt_token_count，因为中间工具步骤会被返回，并成为对话历史的一部分。这适用于请求，不适用于响应。Google 搜索是个例外：它采用独立的查询级定价模式，因此其令牌不会被重复计费。

启用工具上下文流转时，文档建议默认使用验证模式；智能模式不受支持。文档还指出，google_search 等内置工具依赖位置信息和当前时间信息。如果 system_instruction 或 function_declaration.description 中的位置信息和时间信息相互冲突，工具组合功能可能无法正常运行。

Gemini API 文档列出支持上下文流转的工具

标准工具上下文流转适用于服务器端内置工具。代码执行也在服务器端，并有自己的内置上下文流转方案，使用 code_execution 和 code_execution_result 步骤。Computer Use 和函数调用是客户端工具，拥有内置的上下文流转方案，使用 function_call 和 function_response 步骤。

各工具向用户显示的数据有所不同：Google 搜索可以将查询作为调用参数返回，并将 search_suggestions 作为响应数据返回；Google Maps 可以返回查询、地点和 google_maps_widget_context_token；URL Context 可以返回要浏览的 urls、status 和 retrieved_url；File Search 不会列出用户可见的调用参数或响应数据。

Gemini API 工具组合详情

• 这项预览功能支持 Gemini 4 和 Gemini 3 模型。
• Gemini 3 模型使用工具上下文流转，在一次交互中与自定义工具共享内置工具上下文。
• 示例将 google_search 与自定义函数 getWeather 结合使用，模型为 gemini-3.8-flash。
• Python 示例需要版本高于 2.0.0 的 SDK。
• 有状态模式使用 previous_interaction_id 自动处理 id 和 signature 字段。
• 无状态模式要求开发者在后续请求中传回 id 和 signature。
• 请求中的内置工具调用部分会计入 prompt_token_count，但响应中不会。
• Google 搜索采用查询级定价，因此其令牌不会被重复计费。
• 启用工具上下文流转时，默认模式为验证模式，且不支持智能模式。

常见问题

哪些 Gemini 模型支持结合使用内置工具和函数调用？

这项预览功能支持 Gemini 4 和 Gemini 3 模型。文档特别指出，Gemini 3 模型使用工具上下文流转，在内置工具和自定义工具之间保留并共享上下文。

Gemini API 如何保留工具调用之间的上下文？

Interactions API 会自动管理多次工具调用之间的上下文。在有状态模式下，previous_interaction_id 可让服务器处理 id 和 signature 字段。在无状态模式下，开发者必须在后续请求中传回这两个字段，以验证真实性并维持上下文。

Google 搜索工具调用会计入提示令牌吗？

请求中的内置工具调用部分会计入 prompt_token_count，但 Google 搜索不会按令牌重复计费，因为它采用独立的查询级定价模式。