Gemini 3.1 Pro Customtools 是什麼? 5 分鐘搞懂自定義工具優先模型的用法

很多開發者看到 gemini-3.1-pro-preview-customtools 這個模型名時會困惑: customtools 是什麼意思？ 它和標準的 gemini-3.1-pro-preview 有什麼不同？ 本文用 5 分鐘幫你徹底搞清楚。

核心價值: 讀完本文，你將明白什麼時候該用標準版、什麼時候該用 customtools 版，以及如何在 Agent 開發中正確選擇。

什麼是 Gemini 3.1 Pro Customtools

一句話解釋

gemini-3.1-pro-preview-customtools 是谷歌在 2026 年 2 月 19 日與標準版 Gemini 3.1 Pro 同步發佈的專用變體模型。它和標準版的核心區別只有一個: 優先使用你註冊的自定義工具，而不是默認跑 bash 命令。

谷歌官方 Changelog 的原話是:

Launched a separate endpoint gemini-3.1-pro-preview-customtools， which is better at prioritizing custom tools， for users building with a mix of bash and tools.

爲什麼需要這個變體

在 Agent 開發中，開發者通常會同時給模型註冊兩類能力:

1. Bash/代碼執行: 讓模型直接運行 shell 命令
2. 自定義工具 （Custom Tools）: 開發者定義的結構化函數，如 view_file、search_code、create_pr 等

問題出在哪裏？ 標準版 Gemini 3.1 Pro 有時會「偷懶」，跳過你精心設計的自定義工具，直接用 bash 命令完成任務。比如你註冊了 view_file 工具，但模型可能直接執行 cat filename.py，繞過了你的工具。

這在某些場景下是有問題的:

• 自定義工具可能有權限控制和日誌記錄
• 自定義工具的返回格式是結構化的，便於後續處理
• 自定義工具可能連接了外部系統 （數據庫、API 等）

customtools 變體就是爲了解決這個問題: 讓模型優先選擇你註冊的工具。

Gemini 3.1 Pro 標準版 vs Customtools 版核心區別

🎯 關鍵理解: 兩個模型的「智力水平」完全相同。區別只在於面對「該用 bash 還是該用你註冊的工具」這個選擇時，customtools 版會更傾向於選擇你的自定義工具。

什麼場景需要用 Gemini 3.1 Pro Customtools

需要用 customtools 的場景

不需要用 customtools 的場景

谷歌的官方建議

谷歌在 Gemini 3 開發者指南的 FAQ 中明確說:

If you are using gemini-3.1-pro-preview and the model ignores your custom tools in favor of bash commands， try the gemini-3.1-pro-preview-customtools model instead.

翻譯: 如果你發現標準版忽略了你的自定義工具而直接用 bash，換成 customtools 版試試。

Gemini 3.1 Pro Customtools API 調用方法

基本調用: 和標準版完全一樣

import openai

client = openai.OpenAI（
    api_key="YOUR_API_KEY"，
    base_url="https://api.apiyi.com/v1"  # API易 統一接口
）

# 只需要換 model 名稱，其他代碼完全不變
response = client.chat.completions.create（
    model="gemini-3.1-pro-preview-customtools"，
    messages=[
        {"role": "user"， "content": "幫我查看項目中的 main.py 文件內容"}
    ]
）
print（response.choices[0].message.content）

帶自定義工具的 Agent 調用

customtools 版的真正威力在於搭配 function calling:

import openai
import json

client = openai.OpenAI（
    api_key="YOUR_API_KEY"，
    base_url="https://api.apiyi.com/v1"  # API易 統一接口
）

# 定義自定義工具
tools = [
    {
        "type": "function"，
        "function": {
            "name": "view_file"，
            "description": "查看指定文件的內容"，
            "parameters": {
                "type": "object"，
                "properties": {
                    "file_path": {
                        "type": "string"，
                        "description": "文件路徑"
                    }
                }，
                "required": ["file_path"]
            }
        }
    }，
    {
        "type": "function"，
        "function": {
            "name": "search_code"，
            "description": "在代碼庫中搜索關鍵詞"，
            "parameters": {
                "type": "object"，
                "properties": {
                    "query": {
                        "type": "string"，
                        "description": "搜索關鍵詞"
                    }，
                    "file_pattern": {
                        "type": "string"，
                        "description": "文件匹配模式，如 *.py"
                    }
                }，
                "required": ["query"]
            }
        }
    }
]

# customtools 版會優先使用上面定義的工具
response = client.chat.completions.create（
    model="gemini-3.1-pro-preview-customtools"，
    messages=[
        {"role": "user"， "content": "幫我在項目中找到所有包含 TODO 的 Python 文件"}
    ]，
    tools=tools
）

# 模型會調用 search_code 工具而不是直接 grep
tool_call = response.choices[0].message.tool_calls[0]
print（f"工具: {tool_call.function.name}"）
print（f"參數: {tool_call.function.arguments}"）

import openai
import json

client = openai.OpenAI（
    api_key="YOUR_API_KEY"，
    base_url="https://api.apiyi.com/v1"
）

tools = [
    {
        "type": "function"，
        "function": {
            "name": "view_file"，
            "description": "查看指定文件的內容"，
            "parameters": {
                "type": "object"，
                "properties": {
                    "file_path": {"type": "string"， "description": "文件路徑"}
                }，
                "required": ["file_path"]
            }
        }
    }，
    {
        "type": "function"，
        "function": {
            "name": "search_code"，
            "description": "在代碼庫中搜索關鍵詞"，
            "parameters": {
                "type": "object"，
                "properties": {
                    "query": {"type": "string"， "description": "搜索關鍵詞"}，
                    "file_pattern": {"type": "string"， "description": "文件匹配模式"}
                }，
                "required": ["query"]
            }
        }
    }，
    {
        "type": "function"，
        "function": {
            "name": "edit_file"，
            "description": "編輯文件中的指定內容"，
            "parameters": {
                "type": "object"，
                "properties": {
                    "file_path": {"type": "string"， "description": "文件路徑"}，
                    "old_content": {"type": "string"， "description": "要替換的舊內容"}，
                    "new_content": {"type": "string"， "description": "新內容"}
                }，
                "required": ["file_path"， "old_content"， "new_content"]
            }
        }
    }
]

# 模擬工具執行
def execute_tool（name， args）:
    """實際項目中替換爲真實的工具實現"""
    if name == "view_file":
        return f"文件內容: {args['file_path']} （模擬）"
    elif name == "search_code":
        return f"搜索 '{args['query']}' 的結果: 找到 3 處匹配 （模擬）"
    elif name == "edit_file":
        return f"已將 {args['file_path']} 中的內容替換 （模擬）"
    return "未知工具"

# Agent 主循環
messages = [{"role": "user"， "content": "找到項目中所有 TODO 註釋並修復它們"}]
max_turns = 5

for turn in range（max_turns）:
    response = client.chat.completions.create（
        model="gemini-3.1-pro-preview-customtools"，
        messages=messages，
        tools=tools
    ）

    msg = response.choices[0].message
    messages.append（msg）

    if msg.tool_calls:
        for tc in msg.tool_calls:
            args = json.loads（tc.function.arguments）
            result = execute_tool（tc.function.name， args）
            messages.append（{
                "role": "tool"，
                "tool_call_id": tc.id，
                "content": result
            }）
            print（f"[Turn {turn+1}] 調用: {tc.function.name}（{args}）"）
    else:
        print（f"[完成] {msg.content[:200]}"）
        break

🚀 快速開始: 通過 API易 apiyi.com 平臺，標準版和 customtools 版使用同一個 API Key。只需修改 model 參數即可切換，非常適合 A/B 測試哪個版本更適合你的 Agent。

Gemini 3.1 Pro Customtools 和 Agent 框架的關係

主流 Agent 框架的適配情況

customtools 版對以下 Agent 開發場景特別有價值:

Gemini 3.1 Pro Customtools 與標準版的行爲對比

爲了更直觀地理解區別，看一個具體的例子:

同一個請求，兩個模型的不同反應

用戶請求: 「幫我查看 src/main.py 文件的內容」

已註冊工具: view_file（file_path: string）

兩種方式都能獲取文件內容，但通過自定義工具調用有以下優勢:

1. 權限控制: 你的 view_file 工具可以檢查路徑是否在白名單內
2. 格式化輸出: 工具可以返回結構化的 JSON 而非原始文本
3. 日誌審計: 工具調用會被框架自動記錄
4. 錯誤處理: 工具可以提供友好的錯誤信息而非 bash 報錯

谷歌 Gemini 工具調用模型的演進

customtools 是谷歌首次爲工具調用提供專用模型變體。以下是谷歌 Gemini 工具相關模型的完整圖譜:

這表明谷歌正在將模型按使用場景細分，而不是用一個通用模型覆蓋所有場景。未來可能會出現更多專用變體。

常見問題

總結: Gemini 3.1 Pro Customtools 速查

一句話總結: gemini-3.1-pro-preview-customtools 就是 Gemini 3.1 Pro 的「Agent 專用模式」— 讓模型更聽話地使用你註冊的工具而非直接跑 bash。價格不變、智力不變，只是工具選擇策略更適合 Agent 開發。

推薦通過 API易 apiyi.com 平臺同時接入兩個版本，在實際項目中 A/B 測試後選擇最適合的。對於 Agent 開發者來說，customtools 版幾乎總是更好的選擇。

參考資料

1. Google AI 文檔: Gemini 3.1 Pro Preview 模型頁

   • 鏈接: ai.google.dev/gemini-api/docs/models/gemini-3.1-pro-preview
   • 說明: 包含標準版和 customtools 版的對比說明

2. Gemini API Changelog: 2026 年 2 月 19 日更新

   • 鏈接: ai.google.dev/gemini-api/docs/changelog
   • 說明: customtools 變體的首次發佈記錄

3. Gemini 3 開發者指南: FAQ 中的工具選擇建議

   • 鏈接: ai.google.dev/gemini-api/docs/gemini-3
   • 說明: 何時從標準版切換到 customtools 版

4. Google AI 文檔: Function Calling 指南

   • 鏈接: ai.google.dev/gemini-api/docs/function-calling
   • 說明: Gemini 模型的函數調用 API 詳解

📝 作者: APIYI Team | 技術交流請訪問 API易 apiyi.com
📅 更新時間: 2026 年 2 月 20 日
🏷️ 關鍵詞: gemini-3.1-pro-preview-customtools， 自定義工具， Agent 開發， function calling， 工具調用， API 調用