Vai al contenuto principale
Italiano— Scegli una lingua
Menu

API Responses e function_call_output

Lezione 10 di 14 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. L’API Responses: il nuovo endpoint
  2. Differenze rispetto a Chat Completions
  3. Utilizzo dell’API Responses con l’SDK OpenAI
  4. Gestione della risposta
  5. Il campo previous_response_id
  6. Archiviazione dei messaggi lato server
  7. Quando utilizzare l’API Responses?
  8. Punti chiave

L’API Responses: il nuovo endpoint

L’API Responses è il nuovo endpoint principale di xAI, distinto dall’endpoint Chat Completions compatibile con OpenAI. Introduce un formato diverso per le chiamate di funzione, utilizzando il tipo function_call_output per restituire i risultati degli strumenti.

Differenze rispetto a Chat Completions

L’endpoint Chat Completions (compatibile con OpenAI) utilizza messaggi con ruolo tool per restituire i risultati. L’API Responses usa un formato differente, strutturato attorno ai tipi di evento.

Chat Completions (formato legacy)

# Restituisci il risultato tramite un messaggio con ruolo "tool"
messages.append({
    "role": "tool",
    "tool_call_id": "call_abc123",
    "content": {temp: 22, city: Paris}
})

API Responses (nuovo formato)

# Restituisci il risultato tramite un oggetto function_call_output
{
    "type": "function_call_output",
    "call_id": "call_abc123",
    "output": {temp: 22, city: Paris}
}

Differenze chiave:

  • type: "function_call_output" sostituisce role: "tool"
  • call_id sostituisce tool_call_id
  • output sostituisce content

Utilizzo dell’API Responses con l’SDK OpenAI

Puoi usare l’SDK OpenAI per chiamare l’API Responses di xAI:

from openai import OpenAI

client = OpenAI(
    api_key="votre-cle-api",
    base_url="https://api.x.ai/v1"
)

# Crea una risposta con strumenti
response = client.responses.create(
    model="grok-4.5",
    input="What's the weather like in Paris?",
    tools=[{
        "type": "function",
        "name": "get_weather",
        "description": "Get the weather for a city",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string"}
            },
            "required": ["city"]
        }
    }]
)

Nota che l’API Responses utilizza input invece di messages e la struttura degli strumenti è leggermente diversa (nessun oggetto function annidato).

Gestione della risposta

La risposta dell’API Responses contiene un array output con gli eventi:

for item in response.output:
    if item.type == "function_call":
        print(f"Function: {item.name}")
        print(f"Arguments: {item.arguments}")
        print(f"Call ID: {item.call_id}")

        # Esegui la funzione
        result = get_weather(city="Paris")

        # Prosegui la conversazione con il risultato
        follow_up = client.responses.create(
            model="grok-4.5",
            input=[
                {"type": "function_call_output",
                 "call_id": item.call_id,
                 "output": json.dumps(result)}
            ],
            tools=tools,
            previous_response_id=response.id
        )

Il campo previous_response_id

L’API Responses introduce un meccanismo di concatenamento delle conversazioni tramite previous_response_id. Invece di reinviare l’intera cronologia dei messaggi, fai semplicemente riferimento alla risposta precedente:

# Prima richiesta
response1 = client.responses.create(
    model="grok-4.5",
    input="Look up the weather in Paris"
)

# Seconda richiesta (concatenata)
response2 = client.responses.create(
    model="grok-4.5",
    input=[{
        "type": "function_call_output",
        "call_id": response1.output[0].call_id,
        "output": {temp: 22}
    }],
    previous_response_id=response1.id
)

Questo semplifica la gestione del contesto e riduce la dimensione delle richieste.

Archiviazione dei messaggi lato server

Con store_messages=True, xAI archivia i messaggi sui propri server:

response = client.responses.create(
    model="grok-4.5",
    input="User question",
    tools=tools,
    store_messages=True
)

Combinato con previous_response_id, questo ti permette di mantenere conversazioni lunghe senza dover reinviare l’intera cronologia a ogni richiesta.

Quando utilizzare l’API Responses?

Per un nuovo progetto costruito specificamente su xAI, l’API Responses è la scelta predefinita, per diverse ragioni cumulative. Le innovazioni arrivano qui per prime: le nuove funzionalità vengono aggiunte all’API Responses prima che altrove, a volte in esclusiva. Alcuni strumenti server integrati sono disponibili solo attraverso questo canale. Inoltre, per le conversazioni lunghe, il concatenamento tramite previous_response_id è strutturalmente più efficiente rispetto al reinvio dell’intera cronologia a ogni turno: meno token trasferiti e meno codice di gestione dello stato dal tuo lato.

Chat Completions mantiene due casi d’uso forti: il codice esistente scritto per l’API OpenAI, che funziona così com’è cambiando solo l’URL di base, e i progetti multi-fornitore dove la portabilità ha la priorità; in queste situazioni, la compatibilità supera le funzionalità esclusive.

Punti chiave

  • L’API Responses usa function_call_output invece del ruolo tool
  • I campi cambiano: call_id invece di tool_call_id, output invece di content
  • previous_response_id ti permette di concatenare le conversazioni senza reinviare la cronologia
  • store_messages=True abilita l’archiviazione lato server
  • L’API Responses è l’endpoint consigliato per i nuovi progetti xAI
  • Chat Completions rimane disponibile per la retrocompatibilità con OpenAI