API Responses e function_call_output
In questa pagina
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"sostituiscerole: "tool"call_idsostituiscetool_call_idoutputsostituiscecontent
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_outputinvece del ruolotool - I campi cambiano:
call_idinvece ditool_call_id,outputinvece dicontent previous_response_idti permette di concatenare le conversazioni senza reinviare la cronologiastore_messages=Trueabilita l’archiviazione lato server- L’API Responses è l’endpoint consigliato per i nuovi progetti xAI
- Chat Completions rimane disponibile per la retrocompatibilità con OpenAI