max_turns y herramientas de servidor/cliente
En esta página
Herramientas de servidor y herramientas de cliente
La plataforma xAI distingue dos tipos de herramientas que Grok puede utilizar en una conversación:
- Herramientas del lado del servidor: búsqueda web, ejecución de código, búsqueda en X. Estas herramientas se ejecutan automáticamente en los servidores de xAI. Grok las invoca, obtiene el resultado y continúa sin ninguna intervención por tu parte.
- Herramientas del lado del cliente: tus funciones personalizadas (llamada a funciones). Cuando Grok quiere llamar a una de tus funciones, la API te devuelve una llamada a función. Tu código la ejecuta y luego envía el resultado de vuelta a la API.
Esta distinción es clave para entender el comportamiento de max_turns.
El parámetro max_turns
max_turns controla el número de turnos de asistente/herramienta que Grok puede realizar en una única solicitud a la API. Cada uso de una herramienta de servidor consume un turno.
response = await client.chat.completions.create(
model="grok-4.5",
messages=[{"role": "user", "content": "Search for the latest news on Python 3.13"}],
tools=[...],
max_turns=5 # Grok puede usar hasta 5 herramientas de servidor
)
Si Grok necesita realizar una búsqueda web, luego ejecutar código para analizar los resultados y finalmente hacer una segunda búsqueda para concluir, eso consume 3 turnos. Con max_turns=5, le quedan 2 turnos disponibles.
Restablecimiento mediante herramientas de cliente
Comportamiento clave que debes recordar: las invocaciones de herramientas del lado del cliente restablecen el contador de max_turns. Cuando tu código gestiona una llamada a función y devuelve el resultado en una nueva solicitud a la API, Grok recupera su asignación completa de turnos.
# Primera solicitud: max_turns=3
response = await client.chat.completions.create(
model="grok-4.5",
messages=messages,
tools=my_tools,
max_turns=3
)
# Grok solicita una llamada a función del cliente
if response.choices[0].message.tool_calls:
# Ejecutas la función localmente
tool_result = execute_tool(response.choices[0].message.tool_calls[0])
# Segunda solicitud: max_turns se restablece a 3
messages.append(response.choices[0].message)
messages.append({"role": "tool", "content": tool_result, ...})
response = await client.chat.completions.create(
model="grok-4.5",
messages=messages,
tools=my_tools,
max_turns=3 # nuevo contador
)
Este restablecimiento tiene sentido: cada solicitud a la API es independiente. El contador max_turns solo se aplica a los turnos realizados dentro de la misma solicitud.
Flujos de trabajo híbridos
La combinación de herramientas de servidor y de cliente permite crear flujos de trabajo complejos. Por ejemplo, Grok puede:
- Realizar una búsqueda web (herramienta de servidor, 1 turno)
- Ejecutar código para analizar los resultados (herramienta de servidor, 1 turno)
- Solicitar a tu función personalizada que guarde los resultados (herramienta de cliente, restablecimiento)
- Realizar una nueva búsqueda basada en los resultados guardados (herramienta de servidor, 1 turno con nuevo contador)
async def hybrid_workflow(question: str) -> str:
messages = [{"role": "user", "content": question}]
while True:
response = await client.chat.completions.create(
model="grok-4.5",
messages=messages,
tools=server_and_client_tools,
max_turns=5
)
message = response.choices[0].message
# Si no hay llamada a herramienta del cliente, tenemos la respuesta final
if not message.tool_calls:
return message.content
# Procesar llamadas a herramientas del cliente
messages.append(message)
for tool_call in message.tool_calls:
result = await execute_local_tool(tool_call)
messages.append({
"role": "tool",
"tool_call_id": tool_call.id,
"content": result
})
Este patrón de bucle gestiona automáticamente el ida y vuelta entre Grok y tus funciones locales. El bucle continúa mientras Grok necesite llamar a tus herramientas. Se detiene cuando proporciona una respuesta de texto final.
Configuración de max_turns
- max_turns=1: Grok solo puede usar una herramienta de servidor. Suficiente para una búsqueda web sencilla.
- max_turns=3-5: buen equilibrio para la mayoría de los casos. Grok puede encadenar búsqueda + análisis + verificación.
- max_turns=10+: para tareas complejas que requieren muchas iteraciones. Vigila los costes de tokens.
Un valor de max_turns demasiado alto no tiene coste si no se utiliza, pero un valor de max_turns demasiado bajo puede truncar el razonamiento de Grok a mitad de la tarea.
Puntos clave
- Las herramientas de servidor (búsqueda web, ejecución de código) consumen turnos de
max_turns - Las herramientas de cliente (tus funciones) restablecen el contador con cada nueva solicitud
- El patrón de bucle
while Truegestiona el ida y vuelta hasta obtener la respuesta final - Comienza con
max_turns=5y ajústalo según la complejidad de tu tarea - Cada turno de servidor consume tokens adicionales (contexto acumulativo)