Apa itu Gemini 3.1 Pro Customtools? Pahami penggunaan model prioritas alat kustom dalam 5 menit

Banyak developer merasa bingung saat melihat nama model gemini-3.1-pro-preview-customtools: Apa maksud dari customtools? Apa bedanya dengan gemini-3.1-pro-preview standar? Artikel ini akan membantu Anda memahaminya secara tuntas dalam 5 menit.

Nilai Inti: Setelah membaca artikel ini, Anda akan memahami kapan harus menggunakan versi standar, kapan harus menggunakan versi customtools, dan bagaimana cara memilih yang tepat dalam pengembangan Agent.

Apa itu Gemini 3.1 Pro Customtools

Penjelasan Singkat

gemini-3.1-pro-preview-customtools adalah model varian khusus yang dirilis oleh Google pada 19 Februari 2026 bersamaan dengan versi standar Gemini 3.1 Pro. Perbedaan utama antara model ini dengan versi standar hanya satu: memprioritaskan penggunaan alat kustom (custom tools) yang Anda daftarkan, alih-alih menjalankan perintah bash secara default.

Kutipan langsung dari Changelog resmi Google:

Meluncurkan endpoint terpisah gemini-3.1-pro-preview-customtools, yang lebih baik dalam memprioritaskan alat kustom, bagi pengguna yang membangun dengan campuran bash dan alat (tools).

Mengapa Varian Ini Dibutuhkan

Dalam pengembangan Agent, developer biasanya memberikan dua jenis kemampuan kepada model:

1. Eksekusi Bash/Kode: Memungkinkan model menjalankan perintah shell secara langsung.
2. Alat Kustom (Custom Tools): Fungsi terstruktur yang didefinisikan oleh developer, seperti view_file, search_code, create_pr, dan sebagainya.

Di mana letak masalahnya? Gemini 3.1 Pro versi standar terkadang "mengambil jalan pintas", melewatkan alat kustom yang telah Anda rancang dengan cermat dan langsung menggunakan perintah bash untuk menyelesaikan tugas. Misalnya, Anda sudah mendaftarkan alat view_file, tetapi model mungkin malah langsung mengeksekusi cat filename.py, melewati alat Anda.

Hal ini bisa menjadi masalah dalam beberapa skenario:

• Alat kustom mungkin memiliki kontrol izin dan pencatatan log (logging).
• Format pengembalian alat kustom bersifat terstruktur, sehingga memudahkan pemrosesan selanjutnya.
• Alat kustom mungkin terhubung ke sistem eksternal (database, API, dll.).

Varian customtools hadir untuk menyelesaikan masalah ini: membuat model lebih memprioritaskan alat yang Anda daftarkan.

Perbedaan Inti Gemini 3.1 Pro Versi Standar vs Versi Customtools

🎯 Pemahaman Kunci: Tingkat "kecerdasan" kedua model ini sepenuhnya sama. Perbedaannya hanya terletak pada pilihan antara "harus pakai bash atau pakai tool yang Anda daftarkan". Versi customtools akan lebih cenderung memilih tool kustom Anda.

Skenario Apa yang Membutuhkan Gemini 3.1 Pro Customtools

Skenario yang membutuhkan customtools

Skenario yang TIDAK membutuhkan customtools

Saran Resmi dari Google

Google menyatakan dengan jelas dalam FAQ Panduan Pengembang Gemini 3:

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.

Terjemahan: Jika Anda mendapati versi standar mengabaikan tool kustom Anda dan malah menggunakan perintah bash, cobalah beralih ke model gemini-3.1-pro-preview-customtools.

Gemini 3.1 Pro Customtools API Calling Method

Pemanggilan Dasar: Sama persis dengan versi standar

import openai

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # APIYI 统一接口
)

# 只需要换 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)

Pemanggilan Agent dengan Alat Kustom (Custom Tools)

Kekuatan sesungguhnya dari versi customtools terletak pada kombinasinya dengan function calling:

import openai
import json

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # APIYI 统一接口
)

# 定义自定义工具
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

🚀 Mulai Cepat: Melalui platform APIYI apiyi.com, versi standar dan versi customtools menggunakan API Key yang sama. Cukup ubah parameter model untuk beralih, sangat cocok untuk pengujian A/B guna melihat versi mana yang lebih pas untuk Agent Anda.

Hubungan antara Gemini 3.1 Pro Customtools dan Framework Agent

Kesesuaian dengan Framework Agent Populer

Versi customtools sangat berharga untuk skenario pengembangan Agent berikut:

Perbandingan Perilaku Gemini 3.1 Pro Customtools vs Versi Standar

Untuk memahami perbedaannya dengan lebih jelas, mari kita lihat contoh spesifik berikut:

Satu Permintaan, Dua Respon Model yang Berbeda

Permintaan Pengguna: "Tolong bantu saya lihat isi file src/main.py"

Alat yang terdaftar: view_file(file_path: string)

Kedua cara tersebut bisa mendapatkan isi file, tetapi pemanggilan melalui alat kustom memiliki keuntungan berikut:

1. Kontrol Izin: Alat view_file Anda dapat memeriksa apakah jalur file berada dalam daftar putih (whitelist).
2. Output Terformat: Alat dapat mengembalikan JSON yang terstruktur, bukan sekadar teks mentah.
3. Audit Log: Pemanggilan alat akan dicatat secara otomatis oleh framework.
4. Penanganan Error: Alat dapat memberikan pesan kesalahan yang lebih ramah daripada pesan error bash.

Evolusi Model Tool Calling Google Gemini

Customtools adalah varian model pertama dari Google yang didedikasikan khusus untuk pemanggilan alat (tool calling). Berikut adalah peta lengkap model terkait alat di Google Gemini:

Hal ini menunjukkan bahwa Google sedang membagi model berdasarkan skenario penggunaan, alih-alih menggunakan satu model umum untuk semua skenario. Di masa depan, mungkin akan muncul lebih banyak varian khusus lainnya.

Pertanyaan yang Sering Diajukan (FAQ)

Ringkasan: Referensi Cepat Gemini 3.1 Pro Customtools

Kesimpulan dalam satu kalimat: gemini-3.1-pro-preview-customtools adalah "mode khusus Agent" dari Gemini 3.1 Pro — membuat model lebih patuh dalam menggunakan alat yang Anda daftarkan daripada langsung menjalankan bash. Harga tetap, kecerdasan tetap, hanya strategi pemilihan alatnya saja yang lebih cocok untuk pengembangan Agent.

Disarankan untuk mengakses kedua versi secara bersamaan melalui platform APIYI apiyi.com, lalu pilih yang paling sesuai setelah melakukan pengujian A/B pada proyek nyata. Bagi pengembang Agent, versi customtools hampir selalu menjadi pilihan yang lebih baik.

Referensi

1. Dokumentasi Google AI: Halaman model Gemini 3.1 Pro Preview

   • Tautan: ai.google.dev/gemini-api/docs/models/gemini-3.1-pro-preview
   • Keterangan: Berisi penjelasan perbandingan antara versi standar dan versi customtools

2. Gemini API Changelog: Pembaruan 19 Februari 2026

   • Tautan: ai.google.dev/gemini-api/docs/changelog
   • Keterangan: Catatan rilis pertama untuk varian customtools

3. Panduan Pengembang Gemini 3: Saran pemilihan alat dalam FAQ

   • Tautan: ai.google.dev/gemini-api/docs/gemini-3
   • Keterangan: Kapan harus beralih dari versi standar ke versi customtools

4. Dokumentasi Google AI: Panduan Function Calling

   • Tautan: ai.google.dev/gemini-api/docs/function-calling
   • Keterangan: Penjelasan mendalam tentang API pemanggilan fungsi (function calling) untuk model Gemini

📝 Penulis: Tim APIYI | Untuk diskusi teknis silakan kunjungi APIYI apiyi.com
📅 Waktu Pembaruan: 20 Februari 2026
🏷️ Kata Kunci: gemini-3.1-pro-preview-customtools, alat kustom, pengembangan Agent, function calling, pemanggilan alat, pemanggilan API