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

Combinação de Ferramentas do Servidor e do Cliente

Aula 12 de 16 Atualizada a 30 de julho de 2026 Programador
Nesta página
  1. Fluxos de Trabalho Híbridos
  2. Combinação de Ferramentas do Servidor e Funções
  3. O Fluxo de Execução Híbrida
  4. Padrões Comuns de Combinação
  5. max_turns e Ferramentas Híbridas
  6. Contexto Multi-volta com Armazenamento
  7. Pontos-chave

Fluxos de Trabalho Híbridos

O verdadeiro poder da API de Respostas surge quando combina ferramentas do servidor (executadas automaticamente pela xAI) e ferramentas do cliente (as suas funções personalizadas) num único pedido. O modelo orquestra estas ferramentas de forma autónoma, criando fluxos de trabalho complexos em apenas algumas linhas de código.

Combinação de Ferramentas do Servidor e Funções

response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="Search for the latest Ligue 1 soccer results and send a summary to my team.",
    tools=[
        {"type": "web_search"},
        {
            "type": "function",
            "name": "send_team_message",
            "description": "Sends a message to the team via Slack",
            "parameters": {
                "type": "object",
                "properties": {
                    "channel": {"type": "string"},
                    "message": {"type": "string"}
                },
                "required": ["channel", "message"]
            }
        }
    ]
)

Neste cenário, o modelo:

  1. Aciona automaticamente o web_search (lado do servidor) para encontrar os resultados
  2. Incorpora os dados num resumo
  3. Chama a função send_team_message (lado do cliente) para que o seu código envie a mensagem no Slack

O Fluxo de Execução Híbrida

O fluxo difere consoante o tipo de ferramenta:

Apenas Ferramentas do Servidor

Request → [model → web_search → result → model] → Final response

Tudo ocorre no lado da xAI. Recebe a resposta final diretamente com os resultados integrados.

Apenas Ferramentas do Cliente

Request → [model → function_call] → PAUSE
Your code executes the function
Result → [model] → Final response

O modelo faz uma pausa, o seu código executa a função e, em seguida, envia o resultado de volta.

Fluxo Híbrido

Request → [model → web_search → result → model → function_call] → PAUSE
Your code executes the function
Result → [model] → Final response

O modelo utiliza primeiro as ferramentas do servidor (automaticamente) e, só depois, chama a sua função quando necessita da sua infraestrutura.

Padrões Comuns de Combinação

Pesquisa + Ação

Combine web_search ou x_search com uma função de ação:

tools = [
    {"type": "web_search"},
    {"type": "x_search"},
    {
        "type": "function",
        "name": "create_report",
        "description": "Creates a report in the CRM",
        "parameters": {
            "type": "object",
            "properties": {
                "title": {"type": "string"},
                "content": {"type": "string"},
                "tags": {"type": "array", "items": {"type": "string"}}
            },
            "required": ["title", "content"]
        }
    }
]

Cálculo + Notificação

Combine code_interpreter com uma função de notificação:

tools = [
    {"type": "code_interpreter"},
    {
        "type": "function",
        "name": "send_alert",
        "description": "Sends an alert if a threshold is exceeded",
        "parameters": {
            "type": "object",
            "properties": {
                "metric": {"type": "string"},
                "value": {"type": "number"},
                "threshold": {"type": "number"}
            },
            "required": ["metric", "value"]
        }
    }
]

max_turns e Ferramentas Híbridas

O comportamento de max_turns é crucial num contexto híbrido:

  • max_turns limita as voltas no lado do servidor dentro de um único pedido
  • Quando o modelo chama uma função do cliente e o seu código devolve o resultado, inicia-se uma nova alocação de max_turns

Na prática, isto significa que as chamadas ao cliente não esgotam o seu orçamento de voltas do servidor. O modelo pode realizar 3 pesquisas na web, chamar a sua função e, após receber o resultado, efetuar mais 3 pesquisas adicionais.

Contexto Multi-volta com Armazenamento

Para fluxos de trabalho complexos que abrangem múltiplas interações, combine armazenamento e encadeamento:

# Turn 1: initial search
r1 = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="Analyze AI market trends.",
    tools=[{"type": "web_search"}, {"type": "code_interpreter"}],
    store=True,
    max_turns=5
)

# Turn 2: deepen with your internal data
r2 = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="Compare with our internal data.",
    tools=[{
        "type": "function",
        "name": "query_internal_db",
        "description": "Queries the internal database",
        "parameters": {"type": "object", "properties": {"query": {"type": "string"}}}
    }],
    previous_response_id=r1.id,
    store=True
)

Pontos-chave

  • Combine ferramentas do servidor e funções do cliente num único pedido para criar fluxos de trabalho híbridos
  • As ferramentas do servidor executam-se automaticamente; as funções do cliente pausam a geração
  • max_turns reinicia após cada ida e volta ao cliente
  • Padrões comuns: pesquisa + ação, cálculo + notificação, agregação de múltiplas fontes
  • Utilize store: true e previous_response_id para fluxos de trabalho multi-volta