Ir para o conteúdo principal
Português— Escolher um idioma
Menu

max_turns e Ferramentas de Servidor/Cliente

Aula 8 de 12 Atualizada a 30 de julho de 2026 Avancado
Nesta página
  1. Ferramentas de Servidor e Ferramentas de Cliente
  2. O Parâmetro max_turns
  3. Reposição através de Ferramentas de Cliente
  4. Fluxos de Trabalho Híbridos
  5. Definição de max_turns
  6. Pontos-chave

Ferramentas de Servidor e Ferramentas de Cliente

A plataforma xAI distingue dois tipos de ferramentas que o Grok pode utilizar numa conversa:

  • Ferramentas do lado do servidor: pesquisa na web, execução de código, pesquisa no X. Estas ferramentas são executadas automaticamente nos servidores da xAI. O Grok invoca-as, obtém o resultado e continua sem qualquer intervenção da sua parte.
  • Ferramentas do lado do cliente: as suas funções personalizadas (chamada de funções). Quando o Grok pretende chamar uma das suas funções, a API devolve-lhe uma chamada de função. O seu código executa-a e envia o resultado de volta à API.

Esta distinção é fundamental para compreender o comportamento do parâmetro max_turns.

O Parâmetro max_turns

O parâmetro max_turns controla o número de turnos assistente/ferramenta que o Grok pode realizar num único pedido à API. Cada utilização de uma ferramenta de servidor consome um 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 can use up to 5 server tools
)

Se o Grok precisar de efetuar uma pesquisa na web, depois executar código para analisar os resultados e, finalmente, realizar uma segunda pesquisa para concluir, isso consome 3 turnos. Com max_turns=5, restam-lhe 2 turnos.

Reposição através de Ferramentas de Cliente

Comportamento chave a reter: as invocações de ferramentas do lado do cliente reinicam o contador max_turns. Quando o seu código gere uma chamada de função e devolve o resultado num novo pedido à API, o Grok recupera a sua alocação total de turnos.

# First request: max_turns=3
response = await client.chat.completions.create(
    model="grok-4.5",
    messages=messages,
    tools=my_tools,
    max_turns=3
)

# Grok requests a client function call
if response.choices[0].message.tool_calls:
    # You execute the function locally
    tool_result = execute_tool(response.choices[0].message.tool_calls[0])

    # Second request: max_turns resets to 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  # new counter
    )

Esta reposição faz sentido: cada pedido à API é independente. O contador max_turns aplica-se apenas aos turnos realizados dentro do mesmo pedido.

Fluxos de Trabalho Híbridos

A combinação de ferramentas de servidor e de cliente permite criar fluxos de trabalho complexos. Por exemplo, o Grok pode:

  1. Efetuar uma pesquisa na web (ferramenta de servidor, 1 turno)
  2. Executar código para analisar os resultados (ferramenta de servidor, 1 turno)
  3. Solicitar à sua função personalizada que guarde os resultados (ferramenta de cliente, reposição)
  4. Realizar uma nova pesquisa com base nos resultados guardados (ferramenta de servidor, 1 turno com novo 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

        # If no client tool call, we have the final answer
        if not message.tool_calls:
            return message.content

        # Process client tool calls
        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 padrão de ciclo gere automaticamente a interação entre o Grok e as suas funções locais. O ciclo continua enquanto o Grok precisar de chamar as suas ferramentas. Interrompe-se quando este fornece uma resposta de texto final.

Definição de max_turns

  • max_turns=1: o Grok só pode utilizar uma ferramenta de servidor. Suficiente para uma pesquisa simples na web.
  • max_turns=3-5: bom equilíbrio para a maioria dos casos. O Grok pode encadear pesquisa + análise + verificação.
  • max_turns=10+: para tarefas complexas que exigem muitas iterações. Atenção aos custos de tokens.

Um valor de max_turns demasiado elevado não tem custos se não for utilizado, mas um valor demasiado baixo pode truncar o raciocínio do Grok a meio da tarefa.

Pontos-chave

  • As ferramentas de servidor (pesquisa na web, execução de código) consomem turnos max_turns
  • As ferramentas de cliente (as suas funções) reiniciam o contador a cada novo pedido
  • O padrão de ciclo while True gere a interação até à resposta final
  • Comece com max_turns=5 e ajuste conforme a complexidade da sua tarefa
  • Cada turno de servidor consome tokens adicionais (contexto cumulativo)