gemini-3.1-pro-preview y gemini-3.1-pro-preview-customtools son dos endpoints de modelos lanzados por Google el mismo día, con el mismo precio y la misma capacidad de razonamiento, pero con comportamientos radicalmente distintos. Este artículo compara las diferencias entre ambos desde 6 dimensiones clave para ayudarte a tomar la decisión correcta en el desarrollo de tus Agents.
Valor principal: Al terminar de leer, sabrás perfectamente en qué escenarios usar la versión estándar y en cuáles la versión customtools, evitando errores comunes en el desarrollo de Agents.
Conclusión rápida: ¿Cuándo usar cada versión?
Si tienes prisa, consulta directamente esta tabla:
| Tu escenario | Cuál elegir | Razón |
|---|---|---|
| Conversación pura / Q&A | Versión estándar | Calidad más estable |
| Traducción / Análisis de texto | Versión estándar | No requiere llamadas a herramientas |
| Generación de código (sin herramientas) | Versión estándar | Genera el código directamente |
Asistente de programación (con herramientas como view_file) |
Versión customtools | Asegura que las herramientas se invoquen correctamente |
| DevOps Agent (bash + herramientas personalizadas) | Versión customtools | Evita que el modelo use siempre bash para saltarse las herramientas |
| Flujos de trabajo MCP | Versión customtools | Garantía de prioridad de herramientas |
| ¿No estás seguro? | Usa primero la estándar, si ignora las herramientas cambia a customtools | Recomendación oficial de Google |
🎯 Cita oficial de Google: "Si estás usando gemini-3.1-pro-preview y el modelo ignora tus herramientas personalizadas en favor de comandos bash, prueba el modelo gemini-3.1-pro-preview-customtools en su lugar."
Diferencia 1: Prioridad en la llamada a herramientas — La diferencia clave
Esta es la única diferencia fundamental entre las dos versiones. Cuando el modelo posee simultáneamente las capacidades de "ejecución en bash" y "herramientas personalizadas", ¿cómo elige?
El problema de la versión estándar: Usa bash a escondidas
Cuando registras la herramienta view_file en la versión estándar, pero le pides que examine un archivo:
Usuario: "Ver el contenido de src/main.py"
Comportamiento de la versión estándar: Ejecuta el comando bash `cat src/main.py` ← ¡Se saltó tu herramienta!
En las discusiones de desarrolladores en Hacker News, varios usuarios reportaron problemas similares:
- "El modelo intenta editar archivos de formas extrañas en lugar de usar las herramientas de edición de texto proporcionadas".
- "La capacidad de llamada a herramientas es deficiente, a menudo toma desvíos innecesarios".
- "Es propenso a quedarse atrapado en bucles sin poder avanzar".
La corrección de la versión customtools: Respeta tus herramientas
Usuario: "Ver el contenido de src/main.py"
Comportamiento de la versión customtools: Llama a view_file("src/main.py") ← Usa la herramienta que registraste ✓
| Escenario | Comportamiento versión estándar | Comportamiento versión customtools |
|---|---|---|
| Ver archivos | cat src/main.py (bash) |
view_file("src/main.py") |
| Buscar código | grep -r "TODO" *.py (bash) |
search_code("TODO", "*.py") |
| Editar archivos | sed -i 's/old/new/' file (bash) |
edit_file(path, old, new) |
| Listar archivos | ls -la src/ (bash) |
list_files("src/") |
| Ejecutar pruebas | pytest tests/ (bash) |
run_tests("tests/") |
Diferencia 2: Rendimiento de calidad general — La versión estándar es más estable
Google incluyó una advertencia importante en su documentación oficial:
"Si bien gemini-3.1-pro-preview-customtools está optimizado para flujos de trabajo agénticos que utilizan herramientas personalizadas y bash, es posible que observes fluctuaciones en la calidad en algunos casos de uso que no se benefician de dichas herramientas."
Esto significa que la versión customtools podría ser menos estable que la versión estándar en los siguientes escenarios:
| Tipo de escenario | Calidad versión estándar | Calidad versión customtools | Notas |
|---|---|---|---|
| Conversación de texto puro | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | Puede haber pequeñas fluctuaciones |
| Escritura de textos largos | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | No involucra herramientas, la estándar es mejor |
| Razonamiento matemático | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | La capacidad central de razonamiento es la misma |
| Generación de código (sin herramientas) | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | La versión estándar es ligeramente superior |
| Agente + Herramientas personalizadas | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | customtools es notablemente mejor |
| Uso mixto de bash + herramientas | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | La ventaja principal de customtools |
Conclusión clave: La versión customtools no es un modelo "más potente", sino una versión optimizada "enfocada en la llamada a herramientas". En escenarios que no requieren herramientas, la versión estándar es en realidad mejor.
💡 Sugerencia de elección: Si más del 50% de las solicitudes de tu aplicación no implican llamadas a herramientas, te recomendamos mantener la versión estándar por defecto y cambiar a la versión customtools solo en flujos de trabajo de Agentes. APIYI (apiyi.com) permite cambiar dinámicamente el parámetro
modelen el código según el escenario.
Diferencia 3: Parámetros y especificaciones del modelo — Exactamente iguales
Ambas versiones son idénticas en cuanto a sus "especificaciones de hardware":
| Especificación | Versión estándar | Versión customtools |
|---|---|---|
| Contexto de entrada | 1,048,576 tokens | 1,048,576 tokens |
| Salida máxima | 65,536 tokens | 65,536 tokens |
| Precio de entrada (≤200K) | $2.00 / 1M tokens | $2.00 / 1M tokens |
| Precio de entrada (>200K) | $4.00 / 1M tokens | $4.00 / 1M tokens |
| Precio de salida (≤200K) | $12.00 / 1M tokens | $12.00 / 1M tokens |
| Precio de salida (>200K) | $18.00 / 1M tokens | $18.00 / 1M tokens |
| Caché de contexto | $0.20-$0.40 / 1M | $0.20-$0.40 / 1M |
| ARC-AGI-2 | 77.1% | Igual (no publicado por separado) |
| SWE-Bench | 80.6% | Igual (no publicado por separado) |
| GPQA Diamond | 94.3% | Igual (no publicado por separado) |
| Sistema de razonamiento | Bajo / Medio / Alto | Bajo / Medio / Alto |
| Entrada multimodal | Texto/Imagen/Audio/Video | Texto/Imagen/Audio/Video |
Punto clave: Google no ha publicado datos de benchmarks específicos para la versión customtools porque el modelo subyacente es el mismo. La diferencia radica únicamente en el ajuste del comportamiento de las llamadas a herramientas (tool calling).
Diferencia 4: Método de llamada a la API — Solo cambia el parámetro model
Ejemplo de código: Cambia entre la versión estándar y customtools con un solo clic
import openai
client = openai.OpenAI(
api_key="TU_API_KEY",
base_url="https://api.apiyi.com/v1" # Interfaz unificada de APIYI
)
# Definir herramientas personalizadas
tools = [{
"type": "function",
"function": {
"name": "view_file",
"description": "Ver el contenido de un archivo específico",
"parameters": {
"type": "object",
"properties": {
"file_path": {"type": "string", "description": "Ruta del archivo"}
},
"required": ["file_path"]
}
}
}]
# Versión estándar: podría omitir la herramienta
resp_standard = client.chat.completions.create(
model="gemini-3.1-pro-preview",
messages=[{"role": "user", "content": "Ver src/main.py"}],
tools=tools
)
# Versión customtools: prioriza el uso de herramientas
resp_custom = client.chat.completions.create(
model="gemini-3.1-pro-preview-customtools",
messages=[{"role": "user", "content": "Ver src/main.py"}],
tools=tools
)
# Comparar la diferencia de comportamiento
print("Versión estándar:", resp_standard.choices[0].message)
print("customtools:", resp_custom.choices[0].message)
Diferencia 5: Experiencia real del desarrollador — Feedback de la comunidad
Los comentarios de los desarrolladores en Hacker News y GitHub revelan los puntos críticos de la versión estándar en escenarios de Agentes:
Problemas de la versión estándar en escenarios de Agentes
Feedback de desarrolladores proveniente de discusiones en Hacker News:
| Descripción del problema | Análisis de la causa | ¿Puede solucionarlo customtools? |
|---|---|---|
| «El modelo intenta editar archivos de formas extrañas, sin usar las herramientas de edición de texto proporcionadas» | La versión estándar tiende a usar bash | Puede solucionarlo — Prioriza el uso de herramientas personalizadas |
| «Capacidad deficiente de llamada a herramientas, a menudo da rodeos» | Baja prioridad de las herramientas | Puede solucionarlo — Eleva la prioridad de las herramientas |
| «Se queda atrapado en bucles fácilmente, sin poder avanzar» | Confusión al alternar entre herramientas y bash | Solución parcial — La ruta de las herramientas es más clara |
| «Consume una gran cantidad de tokens de pensamiento y luego hace algo inexplicable» | Conflicto entre el razonamiento del modelo y la selección de herramientas | Solución parcial — La selección de herramientas es más determinista |
| «Necesita constantemente que se le diga que continúe o termine» | Problema del bucle principal del Agente | No puede solucionarlo — Es un problema general del modelo |
La práctica de GitHub Copilot
El equipo de GitHub Copilot señaló al integrar Gemini 3.1 Pro:
"El modelo destaca en el ciclo edit-then-test (editar y luego probar), con una alta precisión de herramientas, logrando objetivos con menos llamadas a herramientas".
Esto demuestra que, bajo un marco de llamada a herramientas adecuado, la capacidad de Agente de Gemini 3.1 Pro es muy potente. La versión customtools está diseñada precisamente para que esta «alta precisión de herramientas» se active de forma más fiable.
🚀 Sugerencia práctica: Si estás construyendo productos tipo asistente de código, te recomendamos empezar directamente con la versión customtools para evitar que se salte herramientas, un problema común en la versión estándar. Puedes desplegarlo y probarlo rápidamente a través de APIYI (apiyi.com).
Diferencia 6: Frameworks de Agentes y herramientas de codificación aplicables
| Herramienta/Framework | Versión recomendada | Razón |
|---|---|---|
| Agente de desarrollo propio (con herramientas personalizadas) | customtools | Asegura que las herramientas se llamen correctamente |
| Productos tipo Claude Code | customtools | Requiere herramientas como view_file, edit_file, etc. |
| Cursor | customtools | El conjunto de herramientas del IDE necesita garantía de prioridad |
| GitHub Copilot | Adaptación ya integrada | Copilot ha optimizado por su cuenta las llamadas a herramientas |
| Agente de LangChain | customtools | Las herramientas registradas en el framework deben llamarse con prioridad |
| Agente de protocolo MCP | customtools | Las herramientas MCP necesitan prioridad |
| Aplicaciones RAG puras | Versión estándar | Normalmente no implica conflictos entre bash y herramientas |
| Aplicaciones de Chat | Versión estándar | No implica llamadas a herramientas |
| API de generación de contenido | Versión estándar | Salida de texto puro |
Cómo determinar si necesitas cambiar de la versión estándar a la versión customtools
Lista de diagnóstico rápido
Si experimentas las siguientes situaciones al usar la versión estándar, significa que deberías cambiar a la versión customtools:
- El modelo ejecuta
caten lugar de llamar a tu herramientaview_file - El modelo ejecuta
grepen lugar de llamar a tu herramientasearch_code - El modelo ejecuta
seden lugar de llamar a tu herramientaedit_file - Aparecen comandos bash con frecuencia en los registros de llamadas a herramientas
- La tasa de llamadas a herramientas del modelo es inferior a la esperada (menos del 50%)
- El modelo parece "no saber" que hay herramientas personalizadas disponibles
Si marcas 2 o más casillas, te recomendamos cambiar de inmediato a gemini-3.1-pro-preview-customtools.
Avanzado: Cómo alternar dinámicamente entre ambas versiones en el código
La mejor práctica no es "elegir una u otra", sino enrutar dinámicamente según el tipo de solicitud:
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
)
💰 Nota sobre costos: El precio de ambas versiones es exactamente el mismo; el enrutamiento dinámico no genera ningún costo adicional. A través de la interfaz unificada de APIYI (apiyi.com), cambiar de modelo es tan sencillo como modificar una cadena de texto.
Preguntas frecuentes
Q1: ¿Será más cara la versión customtools?
No. El precio de ambas versiones es exactamente el mismo: entrada $2.00 / 1M de tokens, salida $12.00 / 1M de tokens. A través de la plataforma APIYI (apiyi.com), puedes usar ambas versiones con la misma API Key.
Q2: Solo uso function calling pero no he dado permisos de ejecución a bash, ¿necesito la versión customtools?
Normalmente no. La versión customtools resuelve principalmente el problema de que «cuando bash y las herramientas personalizadas coexisten, el modelo prioriza bash». Si tu Agent no tiene capacidad de ejecución en bash, la llamada a herramientas de la versión estándar ya es lo suficientemente fiable.
Q3: ¿En qué consisten exactamente las «fluctuaciones de calidad» de la versión customtools?
Google no ha publicado datos específicos. Según el feedback de los desarrolladores, esto se manifiesta principalmente en escenarios que no involucran herramientas, como diálogos puros o generación de textos largos, donde la consistencia y el estilo de la redacción pueden variar ligeramente. Para escenarios de Agents con un uso intensivo de herramientas, la calidad general de la versión customtools es, de hecho, mejor.
Q4: ¿Puedo usar ambas versiones al mismo tiempo?
Por supuesto. Lo recomendable es realizar un enrutamiento dinámico en tu código según el tipo de solicitud: envía las peticiones que involucren llamadas a herramientas a la versión customtools, y las peticiones de texto puro a la versión estándar. Gracias a la interfaz unificada de APIYI (apiyi.com), solo necesitas cambiar el parámetro model.
Resumen: Comparativa rápida entre Versión Estándar vs. Customtools (6 puntos)
| # | Dimensión de comparación | Versión Estándar | Versión customtools | Sugerencia de elección |
|---|---|---|---|---|
| 1 | Prioridad de herramientas | Puede priorizar bash | Prioriza herramientas personalizadas | Usa customtools para Agents |
| 2 | Calidad general | Equilibrada en todo escenario | Pequeñas fluctuaciones fuera de herramientas | Usa estándar para tareas generales |
| 3 | Especificaciones/Precio | Exactamente igual | Exactamente igual | Sin diferencia de costes |
| 4 | Llamada a la API | Solo cambia el parámetro model |
Solo cambia el parámetro model |
Cambio con un solo clic |
| 5 | Feedback de la comunidad | Llamada a herramientas poco fiable | Llamada a herramientas más fiable | Elige customtools para escenarios de Agents |
| 6 | Frameworks aplicables | Chat/RAG/Inferencia pura | Cursor/Claude Code/MCP | Depende de tu tipo de aplicación |
Resumen en una frase: customtools no es una actualización, sino una versión especializada: el mismo cerebro, pero con una estrategia de selección de herramientas diferente. Usa customtools para desarrollar Agents y la versión estándar para el resto de escenarios. Puedes alternar libremente entre ambas versiones en APIYI (apiyi.com) usando la misma API Key.
Guía rápida de decisión
| Tu pregunta | Respuesta |
|---|---|
| Solo hago aplicaciones de chat | Usa la versión estándar |
| Estoy desarrollando un Agent | Usa la versión customtools |
| ¿Cuál de las dos versiones es más potente? | La capacidad de razonamiento es la misma, pero customtools es más fiable en llamadas a herramientas |
| ¿Necesito cambiar el código para cambiar de versión? | Solo cambia el parámetro model, el resto del código permanece igual |
| ¿Hay diferencia en los costes? | Son exactamente iguales |
Referencias
-
Documentación de Google AI: Página del modelo Gemini 3.1 Pro Preview
- Enlace:
ai.google.dev/gemini-api/docs/models/gemini-3.1-pro-preview - Descripción: Introducción al endpoint customtools y notas de uso.
- Enlace:
-
Guía para desarrolladores de Gemini 3: FAQ — Cuándo cambiar de modelo
- Enlace:
ai.google.dev/gemini-api/docs/gemini-3 - Descripción: Recomendación oficial sobre el momento oportuno para pasar de la versión estándar a la versión customtools.
- Enlace:
-
Changelog de Gemini API: Registro de lanzamiento del 19 de febrero de 2026
- Enlace:
ai.google.dev/gemini-api/docs/changelog - Descripción: Anuncio del primer lanzamiento de la variante customtools.
- Enlace:
-
Discusión en Hacker News: Comentarios de desarrolladores sobre las llamadas a herramientas (tool calling) de Gemini 3.1 Pro
- Enlace:
news.ycombinator.com/item?id=47074735 - Descripción: Experiencias reales de desarrolladores y reportes de problemas.
- Enlace:
-
Changelog de GitHub Copilot: Integración de Gemini 3.1 Pro
- Enlace:
github.blog/changelog/2026-02-19-gemini-3-1-pro-is-now-in-public-preview-in-github-copilot - Descripción: Evaluación de la precisión de las herramientas en escenarios de asistentes de codificación.
- Enlace:
📝 Autor: APIYI Team | Para intercambio técnico, visita APIYI apiyi.com
📅 Fecha de actualización: 20 de febrero de 2026
🏷️ Palabras clave: gemini-3.1-pro-preview-customtools, comparativa versión estándar, desarrollo de Agents, llamada a herramientas, function calling, selección de modelo
