O que é o Gemini 3.1 Pro Customtools? Entenda em 5 minutos como usar o modelo de prioridade de ferramentas personalizadas

Muitos desenvolvedores ficam confusos ao ver o nome do modelo gemini-3.1-pro-preview-customtools: o que significa customtools? Qual a diferença entre ele e o padrão gemini-3.1-pro-preview? Este artigo vai te ajudar a entender tudo em 5 minutos.

Valor central: Ao terminar de ler este artigo, você entenderá quando usar a versão padrão, quando usar a versão customtools e como fazer a escolha certa no desenvolvimento de Agents.

O que é o Gemini 3.1 Pro Customtools

Explicação em uma frase

O gemini-3.1-pro-preview-customtools é uma variante especializada do modelo lançada pelo Google em 19 de fevereiro de 2026, simultaneamente com a versão padrão do Gemini 3.1 Pro. A única diferença central entre ele e a versão padrão é: ele prioriza o uso das ferramentas personalizadas que você registrou, em vez de executar comandos bash por padrão.

O Changelog oficial do Google diz textualmente:

Lançamos um endpoint separado gemini-3.1-pro-preview-customtools, que é melhor em priorizar ferramentas personalizadas, para usuários que constroem com uma mistura de bash e ferramentas.

Por que essa variante é necessária?

No desenvolvimento de Agents, os desenvolvedores geralmente registram dois tipos de capacidades para o modelo:

1. Bash/Execução de código: Permite que o modelo execute comandos shell diretamente.
2. Ferramentas Personalizadas (Custom Tools): Funções estruturadas definidas pelo desenvolvedor, como view_file, search_code, create_pr, etc.

Onde está o problema? A versão padrão do Gemini 3.1 Pro às vezes "fica com preguiça", pulando as ferramentas personalizadas que você projetou com tanto cuidado para usar comandos bash diretamente. Por exemplo, você registra a ferramenta view_file, mas o modelo pode acabar executando um cat filename.py, ignorando sua ferramenta.

Isso é problemático em certos cenários:

• Ferramentas personalizadas podem ter controle de permissões e registro de logs.
• O formato de retorno das ferramentas personalizadas é estruturado, facilitando o processamento posterior.
• As ferramentas personalizadas podem estar conectadas a sistemas externos (bancos de dados, APIs, etc.).

A variante customtools foi criada justamente para resolver isso: garantir que o modelo priorize as ferramentas que você registrou.

Principais diferenças entre o Gemini 3.1 Pro Standard e a versão Customtools

🎯 Entendimento chave: O "nível de inteligência" de ambos os modelos é exatamente o mesmo. A única diferença é que, ao decidir entre "devo usar o bash ou a ferramenta que você registrou", a versão customtools terá uma tendência maior a escolher a sua ferramenta personalizada.

Em quais cenários usar o Gemini 3.1 Pro Customtools

Cenários que exigem o customtools

Cenários que NÃO exigem o customtools

Recomendação oficial do Google

No FAQ do guia de desenvolvedores do Gemini 3, o Google diz claramente:

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.

Tradução: Se você perceber que a versão padrão está ignorando suas ferramentas personalizadas e usando o bash diretamente, tente mudar para o modelo gemini-3.1-pro-preview-customtools.

Gemini 3.1 Pro Customtools: Como chamar a API

Chamada básica: exatamente igual à versão padrão

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)

Chamada de Agent com ferramentas personalizadas

O verdadeiro poder da versão customtools está na combinação com o 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

🚀 Início Rápido: Através da plataforma APIYI (apiyi.com), a versão padrão e a versão customtools utilizam a mesma API Key. Basta alterar o parâmetro model para alternar entre elas, o que é perfeito para realizar testes A/B e descobrir qual versão se adapta melhor ao seu Agent.

Relação entre o Gemini 3.1 Pro Customtools e Frameworks de Agent

Compatibilidade com os principais frameworks de Agent

A versão customtools é especialmente valiosa para os seguintes cenários de desenvolvimento de Agents:

Comparação de comportamento: Gemini 3.1 Pro Customtools vs. Versão Padrão

Para entender a diferença de forma mais intuitiva, vamos dar uma olhada em um exemplo prático:

O mesmo pedido, reações diferentes dos dois modelos

Pedido do usuário: "Ajude-me a visualizar o conteúdo do arquivo src/main.py"

Ferramenta registrada: view_file(file_path: string)

Ambas as formas conseguem obter o conteúdo do arquivo, mas a chamada via ferramenta personalizada oferece as seguintes vantagens:

1. Controle de permissões: Sua ferramenta view_file pode verificar se o caminho está na lista de permissões (whitelist).
2. Saída formatada: A ferramenta pode retornar um JSON estruturado em vez de texto puro.
3. Auditoria de logs: As chamadas de ferramentas são registradas automaticamente pelo framework.
4. Tratamento de erros: A ferramenta pode fornecer mensagens de erro amigáveis em vez de um erro bruto do bash.

Evolução dos modelos de Tool Calling do Google Gemini

O customtools é a primeira vez que o Google oferece uma variante de modelo dedicada para chamadas de ferramentas. Abaixo está o mapa completo dos modelos relacionados a ferramentas do Google Gemini:

Isso mostra que o Google está segmentando os modelos por cenário de uso, em vez de tentar cobrir tudo com um único modelo genérico. É provável que surjam mais variantes especializadas no futuro.

Perguntas Frequentes

Resumo: Consulta Rápida Gemini 3.1 Pro Customtools

Resumo em uma frase: O gemini-3.1-pro-preview-customtools é o "modo dedicado para Agents" do Gemini 3.1 Pro — ele faz o modelo ser mais "obediente" ao usar as ferramentas que você registrou em vez de simplesmente rodar comandos bash. O preço não muda, a inteligência não muda; apenas a estratégia de seleção de ferramentas é mais adequada para o desenvolvimento de Agents.

Recomendamos acessar as duas versões simultaneamente através da plataforma APIYI (apiyi.com) e escolher a mais adequada após realizar testes A/B no seu projeto real. Para desenvolvedores de Agents, a versão customtools é quase sempre a melhor escolha.

Referências

1. Documentação do Google AI: Página do modelo Gemini 3.1 Pro Preview

   • Link: ai.google.dev/gemini-api/docs/models/gemini-3.1-pro-preview
   • Descrição: Contém a comparação entre a versão padrão e a versão customtools.

2. Changelog da API do Gemini: Atualização de 19 de fevereiro de 2026

   • Link: ai.google.dev/gemini-api/docs/changelog
   • Descrição: Registro do lançamento inicial da variante customtools.

3. Guia do Desenvolvedor do Gemini 3: Sugestões de seleção de ferramentas no FAQ

   • Link: ai.google.dev/gemini-api/docs/gemini-3
   • Descrição: Quando mudar da versão padrão para a versão customtools.

4. Documentação do Google AI: Guia de Function Calling

   • Link: ai.google.dev/gemini-api/docs/function-calling
   • Descrição: Detalhes da API de chamada de função para modelos Gemini.

📝 Autor: Equipe APIYI | Para trocas técnicas, visite APIYI apiyi.com
📅 Data de atualização: 20 de fevereiro de 2026
🏷️ Palavras-chave: gemini-3.1-pro-preview-customtools, ferramentas personalizadas, desenvolvimento de Agentes, function calling, chamada de ferramentas, chamada de API