Combinare strumenti server e client
In questa pagina
Flussi di lavoro ibridi
La vera potenza delle API Responses emerge quando combini strumenti server (eseguiti automaticamente da xAI) e strumenti client (le tue funzioni personalizzate) in un’unica richiesta. Il modello orchestra questi strumenti in modo autonomo, creando flussi di lavoro complessi in poche righe di codice.
Combinare strumenti server e funzioni
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"]
}
}
]
)
In questo scenario, il modello:
- Attiva automaticamente
web_search(lato server) per trovare i risultati - Incorpora i dati in un riepilogo
- Chiama
send_team_message(lato client) affinché il tuo codice invii il messaggio su Slack
Il flusso di esecuzione ibrido
Il flusso varia a seconda del tipo di strumento:
Solo strumenti server
Request → [model → web_search → result → model] → Final response
Tutto avviene lato xAI. Ricevi direttamente la risposta finale con i risultati integrati.
Solo strumenti client
Request → [model → function_call] → PAUSE
Your code executes the function
Result → [model] → Final response
Il modello si mette in pausa, il tuo codice esegue la funzione, quindi invii il risultato indietro.
Flusso ibrido
Request → [model → web_search → result → model → function_call] → PAUSE
Your code executes the function
Result → [model] → Final response
Il modello utilizza prima gli strumenti server (automaticamente), quindi chiama la tua funzione quando ha bisogno della tua infrastruttura.
Pattern di combinazione comuni
Ricerca + Azione
Combina web_search o x_search con una funzione di azione:
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"]
}
}
]
Calcolo + Notifica
Combina code_interpreter con una funzione di notifica:
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 strumenti ibridi
Il comportamento di max_turns è cruciale in un contesto ibrido:
max_turnslimita i turni lato server all’interno di una singola richiesta- Quando il modello chiama una funzione client e il tuo codice restituisce il risultato, inizia una nuova allocazione di
max_turns
In pratica, ciò significa che le chiamate client non esauriscono il tuo budget di turni server. Il modello può eseguire 3 ricerche web, chiamare la tua funzione, quindi eseguire altre 3 ricerche dopo aver ricevuto il risultato.
Contesto multi-turno con archiviazione
Per flussi di lavoro complessi che si estendono su più interazioni, combina archiviazione e concatenamento:
# 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
)
Punti chiave
- Combina strumenti server e funzioni client in un’unica richiesta per flussi di lavoro ibridi
- Gli strumenti server vengono eseguiti automaticamente; le funzioni client mettono in pausa la generazione
max_turnssi resetta dopo ogni andata e ritorno client- Pattern comuni: ricerca + azione, calcolo + notifica, aggregazione da più fonti
- Usa
store: trueeprevious_response_idper flussi di lavoro multi-turno