Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Combinare strumenti server e client

Lezione 12 di 16 Aggiornata il 30 luglio 2026 Sviluppatore
In questa pagina
  1. Flussi di lavoro ibridi
  2. Combinare strumenti server e funzioni
  3. Il flusso di esecuzione ibrido
  4. Pattern di combinazione comuni
  5. max_turns e strumenti ibridi
  6. Contesto multi-turno con archiviazione
  7. Punti chiave

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:

  1. Attiva automaticamente web_search (lato server) per trovare i risultati
  2. Incorpora i dati in un riepilogo
  3. 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_turns limita 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_turns si resetta dopo ogni andata e ritorno client
  • Pattern comuni: ricerca + azione, calcolo + notifica, aggregazione da più fonti
  • Usa store: true e previous_response_id per flussi di lavoro multi-turno