tool_choice y control de herramientas
En esta página
Dirige al modelo hacia las herramientas adecuadas
Por defecto, el modelo decide libremente qué herramientas utilizar (o si utiliza alguna). El parámetro tool_choice te ofrece un control más fino sobre este comportamiento.
Modos de tool_choice
auto (predeterminado)
El modelo decide libremente. Puede usar una herramienta, varias o ninguna:
{
"model": "grok-4.20-0309-reasoning",
"input": "What is the capital of France?",
"tools": [{"type": "web_search"}],
"tool_choice": "auto"
}
Para esta pregunta factual sencilla, es probable que el modelo responda sin realizar una búsqueda web. Para una pregunta sobre actualidad, iniciará una búsqueda.
required
Obliga al modelo a utilizar al menos una herramienta:
{
"model": "grok-4.20-0309-reasoning",
"input": "Give me today's stock market prices.",
"tools": [{"type": "web_search"}],
"tool_choice": "required"
}
Útil cuando sabes que la respuesta requiere datos actualizados y el modelo no debe responder basándose en su memoria.
none
Prohíbe el uso de herramientas, incluso si están declaradas:
{
"model": "grok-4.20-0309-reasoning",
"input": "Explain the concept of recursion.",
"tools": [{"type": "web_search"}, {"type": "code_interpreter"}],
"tool_choice": "none"
}
Práctico para forzar una respuesta puramente textual en un contexto donde las herramientas suelen estar disponibles.
Función específica
Fuerza el uso de una función concreta:
{
"model": "grok-4.20-0309-reasoning",
"input": "Paris",
"tools": [{
"type": "function",
"name": "get_weather",
"description": "Retrieves the weather",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string"}
},
"required": ["city"]
}
}],
"tool_choice": {"type": "function", "name": "get_weather"}
}
El modelo queda restringido a llamar a get_weather con los argumentos apropiados.
parallel_tool_calls
Por defecto, parallel_tool_calls está establecido en true. El modelo puede lanzar múltiples herramientas en paralelo dentro de un mismo turno:
{
"model": "grok-4.20-0309-reasoning",
"input": "Compare the weather in Paris and London.",
"tools": [{
"type": "function",
"name": "get_weather",
"description": "Retrieves the weather for a city",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string"}
},
"required": ["city"]
}
}],
"parallel_tool_calls": true
}
El modelo podría llamar a get_weather("Paris") y get_weather("Londres") simultáneamente, lo que acelera el procesamiento.
Para desactivar este comportamiento:
{
"parallel_tool_calls": false
}
Desactiva las llamadas paralelas si tus funciones tienen efectos secundarios o dependen unas de otras (por ejemplo, si la segunda función depende del resultado de la primera).
max_turns
El parámetro max_turns limita el número de turnos de interacción entre el modelo y las herramientas en el lado del servidor:
{
"model": "grok-4.20-0309-reasoning",
"input": "Perform an in-depth analysis of the AI market in 2026.",
"tools": [{"type": "web_search"}, {"type": "code_interpreter"}],
"max_turns": 5
}
Un “turno” corresponde a un ciclo completo: el modelo llama a una herramienta, recibe el resultado y decide si necesita realizar otra llamada. Con max_turns: 5, el modelo puede ejecutar hasta 5 ciclos de llamadas a herramientas en el servidor antes de generar su respuesta final.
Comportamiento con herramientas del cliente
max_turns solo se aplica a las herramientas del servidor. Cuando el modelo llama a una función del cliente, el contador se reinicia en la siguiente solicitud. Esto significa que cada ida y vuelta entre cliente y servidor crea una nueva asignación de turnos.
Estrategias de control
| Escenario | tool_choice | parallel | max_turns |
|---|---|---|---|
| Búsqueda de noticias | required | true | 3 |
| Cálculo preciso | {"type": "function", "name": "calc"} | false | 1 |
| Conversación libre | auto | true | 5 |
| Respuesta sin herramienta | none | - | - |
Puntos clave
tool_choicecontrola si el modelo usa herramientas y cuáles:auto,required,noneo una función específicaparallel_tool_calls(predeterminadotrue) habilita llamadas simultáneas a herramientasmax_turnslimita los ciclos de herramientas en el servidor; las llamadas del cliente reinician el contador- Usa
requiredcuando los datos actualizados son esenciales - Desactiva el paralelismo si tus funciones tienen dependencias entre sí