¿Qué es Gemini 3.1 Pro Customtools? Aprende a usar el modelo de prioridad de herramientas personalizadas en 5 minutos

Muchos desarrolladores se confunden al ver el nombre del modelo gemini-3.1-pro-preview-customtools: ¿qué significa customtools? ¿En qué se diferencia del gemini-3.1-pro-preview estándar? Este artículo te lo aclarará por completo en 5 minutos.

Valor clave: Después de leer este artículo, entenderás cuándo usar la versión estándar, cuándo usar la versión customtools y cómo elegir correctamente en el desarrollo de Agentes.

¿Qué es Gemini 3.1 Pro Customtools?

Explicación en una frase

gemini-3.1-pro-preview-customtools es una variante de modelo especializada lanzada por Google el 19 de febrero de 2026, junto con la versión estándar de Gemini 3.1 Pro. La única diferencia clave con la versión estándar es: prioriza el uso de tus herramientas personalizadas registradas, en lugar de ejecutar comandos bash por defecto.

La cita original del Changelog oficial de Google es:

Se lanzó un endpoint separado gemini-3.1-pro-preview-customtools, que prioriza mejor las herramientas personalizadas, para usuarios que desarrollan con una mezcla de bash y herramientas.

¿Por qué se necesita esta variante?

En el desarrollo de Agentes, los desarrolladores suelen registrar dos tipos de capacidades para el modelo:

1. Ejecución de Bash/código: Permite que el modelo ejecute comandos de shell directamente.
2. Herramientas personalizadas (Custom Tools): Funciones estructuradas definidas por el desarrollador, como view_file, search_code, create_pr, etc.

¿Dónde radica el problema? La versión estándar de Gemini 3.1 Pro a veces puede "ser perezosa", saltándose las herramientas personalizadas que has diseñado cuidadosamente y completando la tarea directamente con comandos bash. Por ejemplo, si registraste la herramienta view_file, el modelo podría ejecutar directamente cat filename.py, eludiendo tu herramienta.

Esto puede ser problemático en ciertos escenarios:

• Las herramientas personalizadas pueden tener control de permisos y registro de logs.
• El formato de retorno de las herramientas personalizadas es estructurado, lo que facilita el procesamiento posterior.
• Las herramientas personalizadas pueden conectarse a sistemas externos (bases de datos, API, etc.).

La variante customtools está diseñada para resolver este problema: hacer que el modelo priorice las herramientas que has registrado.

Diferencias clave entre Gemini 3.1 Pro Standard y Customtools

🎯 Punto clave: El "nivel de inteligencia" de ambos modelos es exactamente el mismo. La única diferencia radica en que, al enfrentarse a la elección de "usar bash o usar tus herramientas registradas", la versión customtools se inclinará más por tus herramientas personalizadas.

Cuándo usar Gemini 3.1 Pro Customtools

Escenarios donde se necesita Customtools

Escenarios donde NO se necesita Customtools

Recomendación oficial de Google

Google afirma explícitamente en las Preguntas Frecuentes de la Guía para Desarrolladores de 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.

Traducción: Si descubres que la versión estándar ignora tus herramientas personalizadas y usa bash directamente, prueba con el modelo customtools.

Método de Llamada a la API de Gemini 3.1 Pro Customtools

Llamada Básica: Exactamente igual que la versión estándar

import openai

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # Interfaz unificada de APIYI
)

# Solo necesitas cambiar el nombre del modelo, el resto del código permanece igual
response = client.chat.completions.create(
    model="gemini-3.1-pro-preview-customtools",
    messages=[
        {"role": "user", "content": "帮我查看项目中的 main.py 文件内容"}
    ]
)
print(response.choices[0].message.content)

Llamada de Agente con Herramientas Personalizadas

El verdadero poder de la versión customtools reside en su combinación con la llamada a funciones (function calling):

import openai
import json

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # Interfaz unificada de APIYI
)

# Definir herramientas personalizadas
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"]
            }
        }
    }
]

# La versión customtools priorizará el uso de las herramientas definidas anteriormente
response = client.chat.completions.create(
    model="gemini-3.1-pro-preview-customtools",
    messages=[
        {"role": "user", "content": "帮我在项目中找到所有包含 TODO 的 Python 文件"}
    ],
    tools=tools
)

# El modelo llamará a la herramienta search_code en lugar de usar grep directamente
tool_call = response.choices[0].message.tool_calls[0]
print(f"Herramienta: {tool_call.function.name}")
print(f"Parámetros: {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"]
            }
        }
    }
]

# Simulación de ejecución de herramientas
def execute_tool(name, args):
    """Reemplazar con la implementación real de la herramienta en un proyecto real"""
    if name == "view_file":
        return f"Contenido del archivo: {args['file_path']} (simulado)"
    elif name == "search_code":
        return f"Resultado de la búsqueda de '{args['query']}': 3 coincidencias encontradas (simulado)"
    elif name == "edit_file":
        return f"Contenido de {args['file_path']} reemplazado (simulado)"
    return "Herramienta desconocida"

# Bucle principal del Agente
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"[Turno {turn+1}] Llamada: {tc.function.name}({args})")
    else:
        print(f"[Completado] {msg.content[:200]}")
        break

🚀 Inicio Rápido: A través de la plataforma APIYI apiyi.com, las versiones estándar y customtools utilizan la misma API Key. Solo necesitas modificar el parámetro model para cambiar entre ellas, lo que es ideal para pruebas A/B y determinar qué versión se adapta mejor a tu Agente.

Gemini 3.1 Pro Customtools y la Relación con los Frameworks de Agente

Adaptación a los Frameworks de Agente Principales

La versión customtools es especialmente valiosa para los siguientes escenarios de desarrollo de Agentes:

Comparación del comportamiento de Gemini 3.1 Pro Customtools vs. la versión estándar

Para entender la diferencia de forma más intuitiva, veamos un ejemplo concreto:

El mismo tipo de solicitud, diferentes respuestas de los dos modelos

Solicitud del usuario: «Ayúdame a ver el contenido del archivo src/main.py»

Herramienta registrada: view_file(file_path: string)

Ambas formas pueden obtener el contenido del archivo, pero la invocación a través de una herramienta personalizada tiene las siguientes ventajas:

1. Control de permisos: Tu herramienta view_file puede verificar si la ruta está en la lista blanca.
2. Salida formateada: La herramienta puede devolver JSON estructurado en lugar de texto sin formato.
3. Auditoría de registros: Las invocaciones de la herramienta son registradas automáticamente por el framework.
4. Manejo de errores: La herramienta puede proporcionar mensajes de error amigables en lugar de errores de bash.

Evolución de los modelos de invocación de herramientas de Google Gemini

Customtools es la primera vez que Google ofrece una variante de modelo dedicada para la invocación de herramientas. A continuación, se presenta el mapa completo de los modelos relacionados con las herramientas de Google Gemini:

Esto indica que Google está segmentando los modelos por caso de uso, en lugar de utilizar un modelo genérico para cubrir todos los escenarios. Es probable que en el futuro surjan más variantes especializadas.

Preguntas Frecuentes

Resumen: Guía Rápida de Gemini 3.1 Pro Customtools

En resumen: gemini-3.1-pro-preview-customtools es el "modo dedicado para Agentes" de Gemini 3.1 Pro — hace que el modelo utilice de forma más obediente las herramientas que has registrado en lugar de ejecutar directamente bash. El precio y la inteligencia permanecen inalterados, solo que la estrategia de selección de herramientas es más adecuada para el desarrollo de Agentes.

Se recomienda acceder a ambas versiones simultáneamente a través de la plataforma APIYI apiyi.com y, después de realizar pruebas A/B en proyectos reales, elegir la más adecuada. Para los desarrolladores de Agentes, la versión customtools es casi siempre la mejor opción.

Referencias

1. 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: Incluye una descripción comparativa de las versiones estándar y customtools.

2. Registro de cambios de la API de Gemini: Actualizado el 19 de febrero de 2026

   • Enlace: ai.google.dev/gemini-api/docs/changelog
   • Descripción: Registro del lanzamiento inicial de la variante customtools.

3. Guía para desarrolladores de Gemini 3: Recomendaciones para la selección de herramientas en las FAQ

   • Enlace: ai.google.dev/gemini-api/docs/gemini-3
   • Descripción: Cuándo cambiar de la versión estándar a la customtools.

4. Documentación de Google AI: Guía de Function Calling

   • Enlace: ai.google.dev/gemini-api/docs/function-calling
   • Descripción: Detalles de la API de Function Calling para los modelos Gemini.

📝 Autor: Equipo de APIYI | 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, herramientas personalizadas, desarrollo de agentes, function calling, llamada a herramientas, llamada a API