gemini-3.1-pro-preview e gemini-3.1-pro-preview-customtools são dois endpoints de modelo lançados pelo Google no mesmo dia, com o mesmo preço e a mesma capacidade de raciocínio, mas com comportamentos completamente diferentes. Este artigo compara as diferenças entre os dois a partir de 6 dimensões cruciais, ajudando você a fazer a escolha certa no desenvolvimento de Agents.
Valor central: Ao terminar de ler, você saberá exatamente em qual cenário usar a versão padrão ou a versão customtools, evitando dores de cabeça no desenvolvimento do seu Agent.
Direto ao ponto: quando usar cada versão
Se você está com pressa, dê uma olhada nesta tabela:
| Seu cenário | Qual escolher | Motivo |
|---|---|---|
| Chat puro / Perguntas e respostas | Versão Padrão | Qualidade mais estável |
| Tradução / Análise de texto | Versão Padrão | Não envolve chamadas de ferramentas |
| Geração de código (sem ferramentas) | Versão Padrão | Saída direta de código |
| Assistente de programação (com ferramentas como view_file) | Versão customtools | Garante que a ferramenta seja chamada corretamente |
| Agent de DevOps (bash + ferramentas personalizadas) | Versão customtools | Evita que o modelo use sempre o bash para ignorar ferramentas |
| Fluxo de trabalho MCP | Versão customtools | Garantia de prioridade das ferramentas |
| Na dúvida? | Comece com a padrão; se as ferramentas forem ignoradas, mude para customtools | Recomendação oficial do Google |
🎯 Palavras oficiais do Google: "Se você estiver usando o gemini-3.1-pro-preview e o modelo ignorar suas ferramentas personalizadas em favor de comandos bash, tente o modelo gemini-3.1-pro-preview-customtools."
Diferença 1: Prioridade de chamada de ferramentas — A diferença principal
Esta é a única diferença essencial entre as duas versões. Quando o modelo possui simultaneamente as capacidades de "execução bash" e "ferramentas personalizadas", como ele escolhe?
O problema da versão padrão: usar o bash "na surdina"
Quando você registra a ferramenta view_file na versão padrão, mas pede para ele visualizar um arquivo:
Usuário: "Veja o conteúdo de src/main.py"
Comportamento da versão padrão: Executa o comando bash `cat src/main.py` ← Ignorou sua ferramenta!
Nas discussões de desenvolvedores no Hacker News, vários relataram problemas semelhantes:
- "O modelo tenta editar arquivos de formas estranhas, em vez de usar as ferramentas de edição de texto fornecidas"
- "A capacidade de chamada de ferramentas é inferior, ele costuma 'pegar atalhos'"
- "Fica preso em loops facilmente e não consegue avançar"
A correção da versão customtools: Respeito às suas ferramentas
Usuário: "Veja o conteúdo de src/main.py"
Comportamento da versão customtools: Chama view_file("src/main.py") ← Usa a ferramenta que você registrou ✓
| Cenário | Comportamento da versão padrão | Comportamento da versão customtools |
|---|---|---|
| Visualizar arquivo | cat src/main.py (bash) |
view_file("src/main.py") |
| Pesquisar código | grep -r "TODO" *.py (bash) |
search_code("TODO", "*.py") |
| Editar arquivo | sed -i 's/old/new/' file (bash) |
edit_file(path, old, new) |
| Listar arquivos | ls -la src/ (bash) |
list_files("src/") |
| Executar testes | pytest tests/ (bash) |
run_tests("tests/") |
Diferença 2: Desempenho de qualidade geral — A versão padrão é mais estável
O Google incluiu um aviso importante em sua documentação oficial:
"Embora o gemini-3.1-pro-preview-customtools seja otimizado para fluxos de agentes que utilizam ferramentas personalizadas e bash, você pode notar flutuações na qualidade em alguns casos de uso que não se beneficiam de tais ferramentas."
Isso significa que a versão customtools pode não ser tão estável quanto a padrão nos seguintes cenários:
| Tipo de cenário | Qualidade da versão padrão | Qualidade da versão customtools | Explicação |
|---|---|---|---|
| Conversa em texto puro | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | Pode haver pequenas oscilações |
| Escrita de textos longos | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | Sem ferramentas envolvidas, a versão padrão é superior |
| Raciocínio matemático | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | A capacidade central de raciocínio é a mesma |
| Geração de código (sem ferramentas) | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | Versão padrão levemente superior |
| Agent + Ferramentas personalizadas | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | customtools é visivelmente melhor |
| Uso misto de bash + ferramentas personalizadas | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | A principal vantagem da customtools |
Ponto-chave: A versão customtools não é um modelo "mais forte", mas sim uma versão ajustada para ser "mais focada em chamadas de ferramentas". Em cenários que não envolvem ferramentas, a versão padrão acaba sendo melhor.
💡 Dica de escolha: Se mais de 50% das requisições do seu app não envolvem chamadas de ferramentas, recomendo manter a versão padrão como default e alternar para a customtools apenas em fluxos de Agent. O APIYI (apiyi.com) permite alternar o parâmetro
modeldinamicamente no código, dependendo do cenário.
Diferença 3: Parâmetros e especificações do modelo — Completamente idênticos
As duas versões são exatamente iguais no nível de "especificações de hardware":
| Especificação | Versão Padrão | Versão customtools |
|---|---|---|
| Contexto de entrada | 1.048.576 tokens | 1.048.576 tokens |
| Saída máxima | 65.536 tokens | 65.536 tokens |
| Preço de entrada (≤200K) | $2.00 / 1M tokens | $2.00 / 1M tokens |
| Preço de entrada (>200K) | $4.00 / 1M tokens | $4.00 / 1M tokens |
| Preço de saída (≤200K) | $12.00 / 1M tokens | $12.00 / 1M tokens |
| Preço de saída (>200K) | $18.00 / 1M tokens | $18.00 / 1M tokens |
| Cache de contexto | $0.20-$0.40 / 1M | $0.20-$0.40 / 1M |
| ARC-AGI-2 | 77.1% | Igual (não publicado separadamente) |
| SWE-Bench | 80.6% | Igual (não publicado separadamente) |
| GPQA Diamond | 94.3% | Igual (não publicado separadamente) |
| Sistema de pensamento | Low / Medium / High | Low / Medium / High |
| Entrada multimodal | Texto/Imagem/Áudio/Vídeo | Texto/Imagem/Áudio/Vídeo |
Destaque: O Google não publicou dados de benchmark separados para a versão customtools, pois o modelo subjacente é o mesmo. A diferença reside apenas no ajuste (tuning) do comportamento de chamada de ferramentas.
Diferença 4: Método de chamada da API — Apenas o parâmetro model muda
Exemplo de código: Alternando entre a versão padrão e a versão customtools
import openai
client = openai.OpenAI(
api_key="YOUR_API_KEY",
base_url="https://api.apiyi.com/v1" # Interface unificada da APIYI
)
# Define ferramentas personalizadas
tools = [{
"type": "function",
"function": {
"name": "view_file",
"description": "Visualiza o conteúdo de um arquivo específico",
"parameters": {
"type": "object",
"properties": {
"file_path": {"type": "string", "description": "Caminho do arquivo"}
},
"required": ["file_path"]
}
}
}]
# Versão padrão: Pode pular a ferramenta
resp_standard = client.chat.completions.create(
model="gemini-3.1-pro-preview",
messages=[{"role": "user", "content": "Ver src/main.py"}],
tools=tools
)
# Versão customtools: Prioriza o uso da ferramenta
resp_custom = client.chat.completions.create(
model="gemini-3.1-pro-preview-customtools",
messages=[{"role": "user", "content": "Ver src/main.py"}],
tools=tools
)
# Compara a diferença de comportamento
print("Versão padrão:", resp_standard.choices[0].message)
print("customtools:", resp_custom.choices[0].message)
Diferença 5: Experiência real do desenvolvedor — Feedback da comunidade
Os feedbacks de desenvolvedores no Hacker News e GitHub revelam os pontos de dor da versão padrão em cenários de Agentes:
Problemas da versão padrão em cenários de Agentes
Feedback de desenvolvedores em discussões no Hacker News:
| Descrição do problema | Análise da causa | O customtools resolve? |
|---|---|---|
| "O modelo tenta editar arquivos de formas estranhas, sem usar as ferramentas de edição de texto fornecidas" | A versão padrão prioriza o bash | Resolve — Prioriza o uso de ferramentas personalizadas |
| "Capacidade ruim de chamada de ferramentas, frequentemente faz rodeios" | Baixa prioridade das ferramentas | Resolve — Aumenta a prioridade das ferramentas |
| "Facilmente entra em loops e não consegue avançar" | Confusão na alternância entre ferramentas e bash | Resolve parcialmente — O caminho das ferramentas fica mais claro |
| "Consome muitos tokens de pensamento e depois faz algo sem sentido" | Conflito entre o raciocínio do modelo e a escolha da ferramenta | Resolve parcialmente — A escolha da ferramenta é mais assertiva |
| "Preciso ficar dizendo o tempo todo para ele continuar ou terminar" | Problema no loop principal do Agente | Não resolve — Este é um problema geral do modelo |
A prática do GitHub Copilot
A equipe do GitHub Copilot destacou ao integrar o Gemini 3.1 Pro:
"O modelo apresenta um excelente desempenho no ciclo edit-then-test (editar e testar), com alta precisão de ferramentas, atingindo o objetivo com menos chamadas de ferramentas."
Isso mostra que, sob o framework correto de chamada de ferramentas, a capacidade de Agente do Gemini 3.1 Pro é muito forte. A versão customtools foi feita justamente para que essa "alta precisão de ferramentas" seja acionada de forma mais confiável.
🚀 Sugestão prática: Se você está construindo produtos do tipo assistente de código, recomendamos começar direto pela versão customtools para evitar o problema de "pular" ferramentas da versão padrão. Você pode implantar e testar rapidamente através do APIYI (apiyi.com).
Diferença 6: Frameworks de Agentes e ferramentas de codificação recomendados
| Ferramenta/Framework | Versão recomendada | Motivo |
|---|---|---|
| Agente próprio (com ferramentas personalizadas) | customtools | Garante que as ferramentas sejam chamadas corretamente |
| Produtos estilo Claude Code | customtools | Necessita de ferramentas como view_file, edit_file, etc. |
| Cursor | customtools | O conjunto de ferramentas da IDE precisa de garantia de prioridade |
| GitHub Copilot | Já possui adaptação nativa | O Copilot otimizou as chamadas de ferramentas por conta própria |
| Agente LangChain | customtools | As ferramentas registradas no framework precisam ser chamadas com prioridade |
| Agente de protocolo MCP | customtools | Ferramentas MCP precisam de prioridade |
| Aplicações RAG puras | Versão padrão | Geralmente não envolvem conflitos entre bash e ferramentas |
| Aplicações de Chat | Versão padrão | Não envolvem chamadas de ferramentas |
| API de geração de conteúdo | Versão padrão | Saída apenas em texto |
如何判断是否需要从标准版切换到 customtools 版
快速诊断清单
如果你在使用标准版时遇到以下情况,说明应该切换到 customtools 版:
- 模型执行
cat而不是调用你的view_file - 模型执行
grep而不是调用你的search_code - 模型执行
sed而不是调用你的edit_file - 模型在工具调用日志中频繁出现 bash 命令
- 模型的工具调用率低于预期 (低于 50%)
- 模型似乎「不知道」有自定义工具可用
出现 2 条以上,建议立即切换到 gemini-3.1-pro-preview-customtools。
进阶: 在代码中动态切换两个版本
最佳实践不是「二选一」,而是根据请求类型动态路由:
import openai
client = openai.OpenAI(
api_key="YOUR_API_KEY",
base_url="https://api.apiyi.com/v1" # APIYI 统一接口
)
def smart_route(messages, tools=None):
"""根据是否需要工具,动态选择模型版本"""
if tools and len(tools) > 0:
# 有自定义工具 → 用 customtools 版确保工具被调用
model = "gemini-3.1-pro-preview-customtools"
else:
# 纯对话/推理 → 用标准版确保质量稳定
model = "gemini-3.1-pro-preview"
return client.chat.completions.create(
model=model,
messages=messages,
tools=tools
)
# 场景 1: 纯推理 → 自动选标准版
resp1 = smart_route(
messages=[{"role": "user", "content": "解释量子纠缠原理"}]
)
# 场景 2: Agent 工作流 → 自动选 customtools 版
tools = [{"type": "function", "function": {
"name": "view_file",
"description": "查看文件",
"parameters": {"type": "object", "properties": {
"path": {"type": "string"}
}, "required": ["path"]}
}}]
resp2 = smart_route(
messages=[{"role": "user", "content": "查看 config.py"}],
tools=tools
)
💰 成本提示: 两个版本价格完全相同,动态路由不会增加任何额外成本。通过 APIYI apiyi.com 的统一接口,切换模型就像改一个字符串一样简单。
Perguntas Frequentes
Q1: A versão customtools é mais cara?
Não. O preço das duas versões é exatamente o mesmo: Entrada $2.00 / 1M tokens, Saída $12.00 / 1M tokens. Ao fazer a chamada através da plataforma APIYI (apiyi.com), você pode usar as duas versões com a mesma API Key.
Q2: Eu uso apenas function calling, mas não dei permissão de execução para o bash. Preciso usar a versão customtools?
Geralmente não. A versão customtools foi criada principalmente para resolver o problema de "quando o bash e ferramentas personalizadas coexistem, o modelo prioriza o bash". Se o seu Agent não tem capacidade de execução bash, a chamada de ferramentas da versão padrão já é suficientemente confiável.
Q3: O que exatamente é essa “flutuação de qualidade” da versão customtools?
O Google não divulgou dados específicos. Pelo feedback dos desenvolvedores, isso se reflete principalmente em cenários que não envolvem ferramentas, como conversas puras ou geração de textos longos, onde a consistência da saída e o estilo de escrita podem variar um pouco. Para cenários de Agents com uso intensivo de ferramentas, a qualidade geral da versão customtools acaba sendo superior.
Q4: Posso usar as duas versões ao mesmo tempo?
Com certeza. O recomendado é fazer um roteamento dinâmico no seu código baseando-se no tipo de requisição: envie requisições que envolvem chamadas de ferramentas para a versão customtools e requisições de texto puro para a versão padrão. Através da interface unificada da APIYI (apiyi.com), basta alterar o parâmetro model.
Resumo: Comparativo rápido de 6 pontos entre Versão Padrão vs. Customtools
| # | Dimensão de Comparação | Versão Padrão | Versão customtools | Sugestão de Escolha |
|---|---|---|---|---|
| 1 | Prioridade de Ferramentas | Pode priorizar o bash | Prioriza ferramentas personalizadas | Use customtools para Agents |
| 2 | Qualidade Geral | Equilibrada em todos os cenários | Pequenas flutuações em cenários sem ferramentas | Use padrão para tarefas gerais |
| 3 | Especificações/Preço | Exatamente iguais | Exatamente iguais | Sem diferença de custo |
| 4 | Chamada de API | Apenas o parâmetro model muda |
Apenas o parâmetro model muda |
Troca instantânea |
| 5 | Feedback da Comunidade | Chamada de ferramenta instável | Chamada de ferramenta mais confiável | Cenários de Agent: vá de customtools |
| 6 | Frameworks Aplicáveis | Chat/RAG/Inferência pura | Cursor/Claude Code/MCP | Depende do tipo da sua aplicação |
Resumo em uma frase: A customtools não é uma versão de upgrade, mas sim uma versão especializada — o mesmo cérebro, mas com uma estratégia diferente de escolha de ferramentas. Desenvolva Agents com a customtools e use a versão padrão para os demais cenários. Você pode alternar livremente entre as duas versões na APIYI (apiyi.com) usando a mesma API Key.
Guia Rápido de Decisão
| Sua dúvida | Resposta |
|---|---|
| Só faço aplicações de chat | Use a versão padrão |
| Estou desenvolvendo um Agent | Use a versão customtools |
| Qual das duas versões é mais "forte"? | A capacidade de raciocínio é a mesma, mas a customtools é mais confiável em chamadas de ferramentas |
| Preciso mudar o código para trocar? | Basta alterar o parâmetro model, o restante do código permanece igual |
| Existe diferença de custo? | Absolutamente nenhuma |
Referências
-
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: Introdução ao endpoint customtools e precauções de uso.
- Link:
-
Guia do Desenvolvedor Gemini 3: FAQ — Quando trocar de modelo
- Link:
ai.google.dev/gemini-api/docs/gemini-3 - Descrição: Recomendações oficiais sobre o momento ideal para migrar da versão padrão para a versão customtools.
- Link:
-
Changelog da API Gemini: Registro de lançamento de 19 de fevereiro de 2026
- Link:
ai.google.dev/gemini-api/docs/changelog - Descrição: Anúncio oficial do primeiro lançamento da variante customtools.
- Link:
-
Discussão no Hacker News: Feedback de desenvolvedores sobre a chamada de ferramentas (tool calling) do Gemini 3.1 Pro
- Link:
news.ycombinator.com/item?id=47074735 - Descrição: Experiências reais de desenvolvedores e relatos de problemas.
- Link:
-
Changelog do GitHub Copilot: Integração do Gemini 3.1 Pro
- Link:
github.blog/changelog/2026-02-19-gemini-3-1-pro-is-now-in-public-preview-in-github-copilot - Descrição: Avaliação da precisão das ferramentas em cenários de assistente de codificação.
- Link:
📝 Autor: APIYI Team | Para troca de conhecimentos técnicos, visite APIYI apiyi.com
📅 Data de atualização: 20 de fevereiro de 2026
🏷️ Palavras-chave: gemini-3.1-pro-preview-customtools, comparação com versão padrão, desenvolvimento de Agents, chamada de ferramentas, function calling, seleção de modelo
