Ir al contenido principal
Español— Elegir un idioma
Menú

max_turns y herramientas de servidor/cliente

Lección 8 de 12 Actualizado el 30 de julio de 2026 Avanzado
En esta página
  1. Herramientas de servidor y herramientas de cliente
  2. El parámetro max_turns
  3. Restablecimiento mediante herramientas de cliente
  4. Flujos de trabajo híbridos
  5. Configuración de max_turns
  6. Puntos clave

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:

  1. Realizar una búsqueda web (herramienta de servidor, 1 turno)
  2. Ejecutar código para analizar los resultados (herramienta de servidor, 1 turno)
  3. Solicitar a tu función personalizada que guarde los resultados (herramienta de cliente, restablecimiento)
  4. 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 True gestiona el ida y vuelta hasta obtener la respuesta final
  • Comienza con max_turns=5 y ajústalo según la complejidad de tu tarea
  • Cada turno de servidor consume tokens adicionales (contexto acumulativo)