# 在 Gemini API 中使用工具

工具扩展了 Gemini 模型的功能，使它们能够在现实世界中采取行动、访问实时信息并执行复杂的计算任务。模型可以在标准请求响应交互和实时流会话中使用工具 [Live API](/docs/live-api/tools).

工具是模型可用来回答查询的特定功能（例如 Google 搜索或代码执行）。 Gemini API 提供一套完全托管的内置工具，或者您可以使用定义自定义工具 [函数调用](/docs/function-calling).

要构建多步骤、面向目标的系统，请参阅 [智能体概述](/docs/agents).

## 可用的内置工具  {% #build-in-tools %}

{% doc-table %}
{% doc-row header="true" %}
{% doc-cell %}
工具
{% /doc-cell %}

{% doc-cell %}
说明
{% /doc-cell %}

{% doc-cell %}
使用案例
{% /doc-cell %}
{% /doc-row %}

{% doc-row header="false" %}
{% doc-cell %}
[Google 搜索](/docs/google-search)
{% /doc-cell %}

{% doc-cell %}
对时事和网络事实的地面反应可减少幻觉。
{% /doc-cell %}

{% doc-cell %}
回答有关最近发生的事件的问题，通过不同来源核实事实。
{% /doc-cell %}
{% /doc-row %}

{% doc-row header="false" %}
{% doc-cell %}
[Google 地图](/docs/maps-grounding)
{% /doc-cell %}

{% doc-cell %}
构建位置感知助手，可以查找地点、获取方向并提供丰富的本地上下文。
{% /doc-cell %}

{% doc-cell %}
规划多站旅行行程，根据用户标准寻找当地商家。
{% /doc-cell %}
{% /doc-row %}

{% doc-row header="false" %}
{% doc-cell %}
[代码执行](/docs/code-execution)
{% /doc-cell %}

{% doc-cell %}
允许模型编写并运行 Python 代码来解决数学问题或准确处理数据。
{% /doc-cell %}

{% doc-cell %}
解决复杂的数学方程，精确处理和分析文本数据。
{% /doc-cell %}
{% /doc-row %}

{% doc-row header="false" %}
{% doc-cell %}
[URL上下文](/docs/url-context)
{% /doc-cell %}

{% doc-cell %}
指导模型读取和分析特定网页或文档的内容。
{% /doc-cell %}

{% doc-cell %}
根据特定 URL 或文档回答问题，跨不同网页检索信息。
{% /doc-cell %}
{% /doc-row %}

{% doc-row header="false" %}
{% doc-cell %}
[电脑使用](/docs/computer-use)
{% /doc-cell %}

{% doc-cell %}
启用 Gemini 来查看屏幕并生成与 Web 浏览器 UI 交互的操作（客户端执行）。
{% /doc-cell %}

{% doc-cell %}
自动执行基于 Web 的重复工作流程，测试 Web 应用程序用户界面。
{% /doc-cell %}
{% /doc-row %}

{% doc-row header="false" %}
{% doc-cell %}
[文件搜索](/docs/file-search)
{% /doc-cell %}

{% doc-cell %}
索引和搜索您自己的文档以启用检索增强生成 (RAG)。
{% /doc-cell %}

{% doc-cell %}
搜索技术手册，通过专有数据回答问题。
{% /doc-cell %}
{% /doc-row %}
{% /doc-table %}

请参阅 [定价页面](/docs/pricing#pricing-for-tools) 有关与特定工具相关的成本的详细信息。

## 工具执行的工作原理  {% #how-tools-execution-works %}

工具允许模型在对话期间请求操作。根据该工具是内置工具（由 Google 管理）还是自定义工具（由您管理），流程会有所不同。

### 内置工具流程  {% #built-in-tool-flow %}

对于内置工具（Google 搜索、Google 地图、URL 上下文、文件搜索、代码执行），整个过程发生在一次 API 调用中：

1. **你** 发送提示：“GOOG最新股价的平方根是多少？”

1. **Gemini** 决定需要工具并在 Google 的服务器上执行它们（例如，搜索股票价格，然后运行 Python 代码来计算平方根）。

1. **Gemini** 发送回基于工具结果的最终答案。

### 自定义工具流程（函数调用）  {% #custom-tool-flow-function-calling %}

对于自定义工具和计算机使用，您的应用程序将处理执行：

1. **你** 发送提示以及函数（工具）声明。

1. **Gemini** 可能会发送回结构化 JSON 以调用特定函数（例如， `{"name": "get_order_status", "args": {"order_id": "123"}}`），始终具有独特的 `id`.

1. **你** 在您的应用程序或环境中执行该函数。

1. **你** 发送函数结果，同样 `id` 作为函数调用，回到Gemini。

1. **Gemini** 使用结果生成最终响应或另一个工具调用。

{% callout type="note" %}
预览：对于那些混合使用 bash 和自定义工具进行构建的人来说，Gemini 3.1 Pro Preview 附带了一个单独的端点，可通过 API 访问，称为 [`gemini-3.1-pro-preview-customtools`](/docs/models/gemini-3.1-pro-preview#gemini-31-pro-preview-customtools).
{% /callout %}

了解更多信息 [函数调用指南](/docs/function-calling).

### 结合内置和自定义工具流程  {% #combining-built-in-and-custom-tools-flow %}

{% callout type="note" %}
预览：Gemini 4 和 Gemini 3 系列型号支持将内置工具与自定义工具一次性组合的选项。
{% /callout %}

对于结合内置工具和自定义工具（函数调用）的请求，模型使用 [工具上下文循环](/docs/tool-combination) 协调不同环境下的执行：

1. **你** 发送提示并声明要启用的内置工具和自定义功能，设置标志以打开组合支持。

1. **Gemini** 执行内置工具，并在生成任何客户端函数调用时向用户产生结果（首先执行的操作取决于提示和模型的决定）。它发回一个响应：

* 确认工具调用

* 工具响应的结果（如果模型生成两个并行函数调用，这可能会出现在 JSON 之后）

* 用于调用函数的结构化 JSON

* 加密思想签名以保留上下文

3. **你** 在您的应用程序或环境中执行该函数。

1. **你** 返回 Gemini 响应的所有部分，以及您的函数调用结果。

1. **Gemini** 使用所有组合上下文生成最终响应。

阅读 [工具组合指南](/docs/tool-combination) 了解如何打开对内置和自定义工具组合的支持以及上下文循环的示例。

## 结构化输出与函数调用  {% #structured-outputs-vs-function-calling %}

Gemini 提供两种生成结构化输出的方法。使用 [函数调用](/docs/function-calling) 当模型需要通过连接到您自己的工具或数据系统来执行中间步骤时。使用 [结构化输出](/docs/structured-output) 当您严格需要模型的最终响应遵守特定架构时，例如渲染自定义 UI。

## 使用工具进行结构化输出  {% #structured-outputs %}

{% callout type="note" %}
预览：此功能仅适用于Gemini 4和Gemini 3系列型号。
{% /callout %}

你可以结合 [结构化输出](/docs/structured-output) 使用内置工具确保基于外部数据或计算的模型响应仍然遵循严格的模式。

参见 [使用工具进行结构化输出](/docs/structured-output?example=recipe#tools)
代码示例。
