Combinação de Ferramentas do Servidor e do Cliente
Nesta página
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:
- Aciona automaticamente o
web_search(lado do servidor) para encontrar os resultados - Incorpora os dados num resumo
- 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_turnslimita 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_turnsreinicia 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: trueeprevious_response_idpara fluxos de trabalho multi-volta