Risposta diretta. Migrare da Sonar all'Agent API di Perplexity non è una sostituzione del nome del modello: cambiano endpoint (POST /v1/agent), forma della richiesta (input al posto di messages), forma della risposta (un array tipizzato output al posto di choices) e il posto in cui stanno le citazioni. La documentazione indica come punto di partenza sonar e sonar-pro verso fast, sonar-reasoning-pro verso low, sonar-deep-research verso high, e lo dice come punto di partenza, non come equivalenza. Il rischio maggiore non è il codice che non compila: è il comportamento che cambia senza che tu tocchi nulla, perché le richieste sincrone e in streaming vengono riformulate da Perplexity con un'introduzione graduale, modello per modello.
Ciò che segue viene dalle pagine «Migrate from Sonar to the Agent API», «How to migrate from Sonar» e «Web Search» aperte il 13 novembre 2026, e dal forum degli sviluppatori. Non ho una chiave e non ho chiamato il prodotto, e non ho letto la pagina dei benchmark: le tabelle di miglioramento che la guida pubblica sono dichiarate dal fornitore, con benchmark interni, e non le riporto come prova. Gli script girano senza rete, su richieste e risposte che ho costruito io nella forma documentata.
Che cosa dice la documentazione, parola per parola
La pagina di panoramica della migrazione afferma, nella versione letta oggi: «Sonar Chat Completions support ended on September 27, 2026». Subito dopo precisa che le richieste sincrone e in streaming continuano a funzionare perché vengono riformulate come richieste Agent API, con un'introduzione graduale per modello, mentre le richieste asincrone non vengono riformulate e non sono più supportate: vanno spostate sulla modalità background. Nel forum degli sviluppatori, il 10 settembre 2026, un membro dello staff ha risposto a chi chiedeva se il vecchio endpoint sarebbe rimasto dopo il 27 settembre che l'endpoint delle chat completions Sonar sarebbe stato ritirato quel giorno e che bisognava passare all'endpoint delle risposte dell'Agent API. La guida consiglia di migrare l'uso esistente e di usare l'Agent API per ogni progetto nuovo.
La conseguenza pratica è doppia. Chi ha richieste sincrone non vede un errore: vede, forse, risposte con una forma o un tono diversi, e non sa da quando. Chi ha richieste asincrone ha già un guasto, non un rischio. Per entrambi vale lo stesso metodo: inventario, prova su domande tue, passaggio controllato, come nei paragrafi che seguono.
Prima e dopo: la richiesta
Nel quickstart della migrazione, la chiamata cambia da client.chat.completions.create(model="sonar", messages=[...]) a client.responses.create(effort="fast", input=...), e il testo della risposta si legge da risposta.output_text invece che da choices[0].message.content. Lo schema che segue mette le due forme una accanto all'altra; è da adattare, non eseguito, perché richiede una chiave e un progetto che usa davvero Sonar.
# PRIMA (chat completions, Sonar)
risposta = client.chat.completions.create(
model="sonar-pro",
messages=[
{"role": "system", "content": "Sei un assistente conciso."},
{"role": "user", "content": domanda},
],
max_tokens=800,
)
testo = risposta.choices[0].message.content
# DOPO (Agent API)
risposta = client.responses.create(
effort="fast", # punto di partenza indicato per sonar-pro
instructions="Sei un assistente conciso.",
input=domanda,
max_output_tokens=800,
)
testo = risposta.output_text
Le tre differenze visibili sono il prompt di sistema, che passa in instructions invece di stare nell'array dei messaggi, il nome del tetto di token e il campo da cui si legge il testo. Il resto è sotto la superficie: ciò che il livello fast fa in più (cerca sul web per impostazione predefinita) e in meno (non c'è più un campo citations) lo vedi solo leggendo la risposta intera. Il punto di partenza per sonar-pro è fast: la guida lo dice, e dice anche che il livello giusto si decide provando.
Le regole di traduzione, dalla guida ufficiale:
- il prompt di sistema passa nel campo
instructions;messagesdiventainput, una stringa oppure un array di elementi contype: "message",roleecontent; max_tokensdiventamax_output_tokens;reasoning_effortdiventareasoning.effort;response_formatconjson_schemamantiene la stessa forma; il tiporegexnon ha equivalente e va riprogettato su uno schema JSON;- i filtri (
search_domain_filter,search_recency_filter, i filtri di data) passano con gli stessi nomi dentrofiltersdello strumentoweb_search;num_search_resultsdiventamax_resultsdello strumento, un tetto sul totale;user_locationsta sullo strumento, non dentrofilters; - il livello
fastabilita la ricerca web per impostazione predefinita; se scegli direttamente un modello devi aggiungere lo strumentoweb_search; - in streaming, il testo arriva negli eventi
response.output_text.deltae non più indelta.content; chiamate agli strumenti e ragionamento hanno eventi propri; - per i dialoghi:
previous_response_id, oppure rimandi i turni precedenti, assistente compreso, dentroinput.
Sono regole di traslocazione: gli stessi concetti cambiano indirizzo, e quasi tutte le righe si applicano con una ricerca nel codice. Le tre da trattare con attenzione sono quella sul regex (non si traduce, si riprogetta), quella sul livello fast contro la scelta diretta di un modello (la ricerca scompare se dimentichi lo strumento) e quella sullo streaming, perché un consumatore che cerca delta.content smette di mostrare testo senza segnalare errori. Lo script che segue applica queste regole a un corpo di richiesta Sonar e dice ad alta voce ciò che non sa tradurre.
"""Traduce il CORPO di una richiesta Sonar in un corpo Agent API, secondo la guida di migrazione."""
import json
LIVELLO_DI_PARTENZA = {"sonar": "fast", "sonar-pro": "fast", "sonar-reasoning-pro": "low", "sonar-deep-research": "high"}
FILTRI = {"search_domain_filter", "search_recency_filter", "search_after_date_filter", "search_before_date_filter",
"last_updated_after_filter", "last_updated_before_filter"}
DA_TOGLIERE = {"search_language_filter", "stream_mode", "return_videos", "num_videos", "media_response"}
def sonar_a_agent(sonar: dict):
agent, note = {}, []
modello = sonar.get("model")
if modello in LIVELLO_DI_PARTENZA:
agent["effort"] = LIVELLO_DI_PARTENZA[modello]
note.append(f"{modello} -> effort {agent['effort']}: punto di partenza, da provare")
else:
note.append(f"modello {modello!r}: nessuna mappatura, scegli tu")
sistema = [m["content"] for m in sonar.get("messages", []) if m["role"] == "system"]
if sistema:
agent["instructions"] = "\n".join(sistema)
agent["input"] = [{"type": "message", "role": m["role"], "content": m["content"]}
for m in sonar.get("messages", []) if m["role"] != "system"]
if "max_tokens" in sonar:
agent["max_output_tokens"] = sonar["max_tokens"]
if "reasoning_effort" in sonar:
agent["reasoning"] = {"effort": sonar["reasoning_effort"]}
for campo in ("stream", "temperature", "top_p"):
if campo in sonar:
agent[campo] = sonar[campo]
if "temperature" in sonar or "top_p" in sonar:
note.append("temperature/top_p: ignorati dalle famiglie GPT-5, o1, o3 (guida di migrazione)")
strumento = {"type": "web_search"}
filtri = {k: v for k, v in sonar.items() if k in FILTRI}
if filtri:
strumento["filters"] = filtri
if "num_search_results" in sonar:
strumento["max_results"] = sonar["num_search_results"]
posizione = sonar.get("web_search_options", {}).get("user_location")
if posizione:
strumento["user_location"] = posizione
if not sonar.get("disable_search"):
agent["tools"] = [strumento]
else:
note.append("disable_search: nessuno strumento da aggiungere, ma i livelli portano i loro; vedi la guida")
formato = sonar.get("response_format")
if formato and formato.get("type") == "regex":
note.append("response_format regex: NESSUN equivalente, da riprogettare su json_schema")
elif formato:
agent["response_format"] = formato
if sonar.get("return_images"):
note.append("return_images: aggiungi lo strumento image_search")
if sonar.get("return_related_questions"):
note.append("return_related_questions: chiedile nel prompt o con un output strutturato")
if sonar.get("search_mode") == "academic":
note.append("search_mode academic: nessun equivalente diretto")
for campo in sorted(DA_TOGLIERE & sonar.keys()):
note.append(f"{campo}: nessun equivalente, si toglie")
return agent, note
PROVE = [
{"model": "sonar-pro", "max_tokens": 800,
"messages": [{"role": "system", "content": "Sei conciso."}, {"role": "user", "content": "Novita' sui crawler?"}],
"search_domain_filter": ["docs.perplexity.ai"], "search_recency_filter": "month", "num_search_results": 8},
{"model": "sonar-deep-research", "messages": [{"role": "user", "content": "Rapporto"}],
"search_language_filter": ["it"], "stream_mode": "full", "response_format": {"type": "regex", "regex": {"regex": "^a+$"}}},
{"model": "sonar-reasoning", "messages": [{"role": "user", "content": "x"}], "return_images": True, "temperature": 0.2},
]
for sonar in PROVE:
agent, note = sonar_a_agent(sonar)
print(json.dumps(agent, ensure_ascii=False))
for n in note:
print(" *", n)
# Output:
# {"effort": "fast", "instructions": "Sei conciso.", "input": [{"type": "message", "role": "user", "content": "Novita' sui crawler?"}], "max_output_tokens": 800, "tools": [{"type": "web_search", "filters": {"search_domain_filter": ["docs.perplexity.ai"], "search_recency_filter": "month"}, "max_results": 8}]}
# * sonar-pro -> effort fast: punto di partenza, da provare
# {"effort": "high", "input": [{"type": "message", "role": "user", "content": "Rapporto"}], "tools": [{"type": "web_search"}]}
# * sonar-deep-research -> effort high: punto di partenza, da provare
# * response_format regex: NESSUN equivalente, da riprogettare su json_schema
# * search_language_filter: nessun equivalente, si toglie
# * stream_mode: nessun equivalente, si toglie
# {"input": [{"type": "message", "role": "user", "content": "x"}], "temperature": 0.2, "tools": [{"type": "web_search"}]}
# * modello 'sonar-reasoning': nessuna mappatura, scegli tu
# * temperature/top_p: ignorati dalle famiglie GPT-5, o1, o3 (guida di migrazione)
# * return_images: aggiungi lo strumento image_search
Il codice è stato eseguito due volte con uscita identica (Python 3.14, libreria standard). Le tre richieste di prova sono scelte per mostrare tre esiti. La prima si traduce per intero: il prompt di sistema va in instructions, i filtri finiscono dentro lo strumento e num_search_results diventa max_results. La seconda perde due campi senza equivalente e un response_format di tipo regex, e lo script lo scrive invece di tacerlo. La terza usa un nome di modello che la guida non mappa (sonar-reasoning, senza -pro): lo script non inventa un livello e chiede a te di scegliere. È un traduttore del corpo, scritto da me sulle regole della guida: non sostituisce una prova sul tuo traffico e non conosce ciò che la guida non dice.
Cosa non ha un equivalente, e che cosa fare
La guida elenca i parametri senza equivalente: search_language_filter, stream_mode, un'opzione di rilevanza delle immagini e i risultati video. Altri hanno un modello diverso: search_mode: "academic" non ha un corrispondente diretto (si usano web_search con filtri di dominio e le istruzioni), return_images diventa lo strumento image_search, return_related_questions diventa una richiesta nel prompt o un output strutturato, e enable_search_classifier diventa la semplice presenza dello strumento web_search. Un caso merita di essere letto per intero: per disable_search la guida dice che si omette lo strumento, ma che con un livello di effort gli strumenti del livello restano abilitati, che tools: [] non li azzera e che max_tool_calls: 0 è una soluzione brusca per disattivare tutte le chiamate agli strumenti.
Per le famiglie GPT-5, o1 e o3 la guida avverte che temperature e top_p sono ignorati in silenzio: non migrare logica che dipende dal loro effetto. Per i parametri di cui la guida non parla non ho una fonte che dica cosa succede, e non la invento: elencali nel tuo inventario e provali uno per uno. C'è infine una conseguenza di progetto: il filtro per lingua che l'Agent API non ha esiste invece nella Search API (articolo 3). Se per il tuo prodotto è essenziale, la strada può essere recuperare con la Search API e far rispondere il tuo modello.
Le citazioni cambiano casa
Nel vecchio formato i riferimenti stavano accanto al testo, nei campi citations e search_results della risposta a choices. Nel nuovo stanno in un elemento search_results dell'array output, con i risultati identificati da un id, mentre i marcatori nel testo sono [1] a fast e [web:1] da low in su: la guida dice che il numero rimanda al risultato con quell'id. La stessa guida dice che il testo non ha un campo separato di annotazioni: la mappa tra marcatori e fonti la costruisci tu (l'articolo 2 ha un controllo che gestisce entrambi i formati).
Il guasto tipico è nel front-end: se trasforma [n] in un link con un'espressione regolare scritta per Sonar, non riconosce [web:1]. Lo script che segue fa due cose su un progetto di prova creato al volo in una cartella temporanea (tre file che ho scritto io, uno dei quali senza codice): cerca i punti da migrare con espressioni regolari e mostra che cosa fa la vecchia espressione sul nuovo marcatore.
"""Inventario dei punti da migrare in un progetto di PROVA creato qui, e prova del marcatore."""
import re
import tempfile
from pathlib import Path
SCHEMI = {
"chiamata Sonar": r"chat\.completions\.create",
"lettura di choices": r"\.choices\[|\[\"choices\"\]",
"lettura di citations": r"\.citations\b|\[\"citations\"\]",
"campi che spariscono": r"related_questions|\.images\b|return_images|stream_mode|search_language_filter",
"modello Sonar": r"model\s*=\s*[\"']sonar[\w-]*[\"']",
"regex del marcatore [n]": r"\\\[\(\\d\+\)\\\]",
}
FILE_DI_PROVA = {
"bot.py": 'r = client.chat.completions.create(model="sonar-pro", messages=m)\ntesto = r.choices[0].message.content\nfonti = r.citations\n',
"web/app.js": 'const link = testo.replace(/\\[(\\d+)\\]/g, "<a>$1</a>");\nconst q = r.related_questions;\n',
"note.md": "Questo file non contiene codice.\n",
}
with tempfile.TemporaryDirectory() as d:
radice = Path(d)
for nome, contenuto in FILE_DI_PROVA.items():
(radice / nome).parent.mkdir(parents=True, exist_ok=True)
(radice / nome).write_text(contenuto, encoding="utf-8")
for file in sorted(radice.rglob("*")):
if not file.is_file():
continue
for numero, riga in enumerate(file.read_text(encoding="utf-8").splitlines(), start=1):
for nome, schema in SCHEMI.items():
if re.search(schema, riga):
print(f"{file.relative_to(radice)}:{numero}: {nome}")
vecchio = re.compile(r"\[(\d+)\]")
nuovo = re.compile(r"\[(?:[a-z]+:)?(\d+)\]")
testo = "Primo[1] e secondo[web:2]."
print("regex vecchia:", vecchio.findall(testo))
print("regex nuova :", nuovo.findall(testo))
# Output:
# bot.py:1: chiamata Sonar
# bot.py:1: modello Sonar
# bot.py:2: lettura di choices
# bot.py:3: lettura di citations
# web/app.js:1: regex del marcatore [n]
# web/app.js:2: campi che spariscono
# regex vecchia: ['1']
# regex nuova : ['1', '2']
L'uscita elenca, per file e numero di riga, ogni punto da toccare: la chiamata e il nome del modello, la lettura di choices e di citations, la regex del marcatore e i campi che spariscono. L'ultima coppia di righe è la prova: la vecchia espressione trova solo 1, la nuova trova 1 e 2. Su un progetto vero l'inventario è un punto di partenza, non un giudizio: una ricerca per espressione regolare perde i nomi costruiti dinamicamente e i campi letti con un nome in una variabile, quindi va completata con una rilettura dei punti dove il codice usa la risposta.
Il test che ti serve: un insieme di domande «d'oro»
Non confronto i prezzi per token (i prezzi dei modelli sono pubblicati pagina per pagina e dipendono dal livello che scegli) né mi fido dei benchmark del fornitore: l'unica evidenza che vale è quella sul tuo traffico. Servono 30-50 domande vere, ciascuna con i fatti che devono comparire e, se ha senso, un dominio da cui ci si aspetta una fonte. Il ciclo che produce le risposte è una chiamata per domanda, con il tempo misurato attorno; lo schema è questo e non è eseguito, perché richiede una chiave:
import time
for d in DOMANDE:
t0 = time.time()
r = client.responses.create(effort="fast", input=d["testo"])
durata = round(time.time() - t0, 2)
# r.effort contiene livello e versione; r.output contiene fonti e testo
# ...passa r (convertita in dict) alla funzione di valutazione qui sotto
Il ciclo è volutamente povero: registra la durata e consegna la risposta intera alla funzione che valuta, perché tutto ciò che si può controllare meccanicamente sta nella risposta. Quella funzione la posso eseguire, su due risposte sintetiche che ho costruito io, una per fast e una per low.
"""Confronto di due livelli su un insieme di domande: la parte che non richiede la rete."""
import re
from urllib.parse import urlparse
# Insieme "d'oro" di PROVA: una domanda, i fatti che devono comparire, il dominio atteso.
DOMANDE = [{"id": "q1", "fatti": [r"radice", r"robots\.txt"], "dominio": "esempio.test"}]
# Due risposte SINTETICHE nella forma documentata (search_results + message): contenuto inventato.
def risposta(testo, url):
return {"output": [
{"type": "search_results", "results": [{"id": i + 1, "url": u} for i, u in enumerate(url)]},
{"type": "message", "content": [{"type": "output_text", "text": testo}]},
]}
RISPOSTE = {
"fast": {"q1": risposta("Il file robots.txt sta nella radice[1].", ["https://esempio.test/guida"])},
"low": {"q1": risposta("Un file di testo per i crawler[web:1].", ["https://altro.test/a", "https://altro.test/b"])},
}
def valuta(domanda, r):
testo = "".join(p["text"] for v in r["output"] if v["type"] == "message" for p in v["content"])
url = [x["url"] for v in r["output"] if v["type"] == "search_results" for x in v["results"]]
domini = {urlparse(u).netloc for u in url}
return {
"n_fonti": len(url),
"dominio_atteso": domanda["dominio"] in domini,
"fatti_presenti": all(re.search(f, testo, re.I) for f in domanda["fatti"]),
}
for livello, per_domanda in RISPOSTE.items():
for d in DOMANDE:
print(livello, d["id"], valuta(d, per_domanda[d["id"]]))
# Output:
# fast q1 {'n_fonti': 1, 'dominio_atteso': True, 'fatti_presenti': True}
# low q1 {'n_fonti': 2, 'dominio_atteso': False, 'fatti_presenti': False}
Il codice misura tre cose verificabili meccanicamente: quante fonti, se compare il dominio atteso, se i fatti attesi sono nel testo. Nell'esempio, costruito da me, low «peggiora» su tutte e tre le misure: non è un risultato sul prodotto, è la forma del confronto, e mostra perché la scelta del livello non si fa a occhio. Non misura se i fatti siano sostenuti dalle fonti: per quello serve un campione letto da una persona. Esegui l'insieme una volta ora e salva i risultati, insieme al campo effort con la versione: sono la base per accorgerti di una deriva quando Perplexity cambia il modello sotto un livello.
Piano di migrazione in cinque passi
- Inventario: trova tutte le chiamate Sonar (sincrone, in streaming, asincrone) e tutto il codice che legge
choices,citations,images,related_questions. - Insieme d'oro: 30-50 domande vere, con i fatti attesi.
- Prova a
faste alow: con la funzione di valutazione; scegli il livello più basso che passa. - Modalità ombra: per una settimana invia una copia del traffico reale al nuovo percorso senza mostrarne l'esito, e confronta.
- Passaggio con tetto di spesa: un contatore giornaliero nel tuo servizio (articolo 6) trasforma una deriva dei costi in un errore.
L'ordine è essenziale: l'inventario dice cosa cambia, l'insieme d'oro dice cosa non deve peggiorare, la prova sceglie il livello, la modalità ombra intercetta ciò che le domande d'oro non coprono, il tetto di spesa protegge il passaggio. Saltare il secondo passo trasforma la migrazione in un atto di fede. Il lavoro asincrono si sposta a parte, con background: true e controllo per identificativo, e va incluso nell'inventario per primo, perché è già fermo.
Uno scenario dichiarato: il widget che cambia senza che tu tocchi niente
Scenario ipotetico. Un'agenzia di viaggi di due persone ha sul sito un widget che risponde a «ci sono scioperi o eventi nella destinazione nei giorni del viaggio?», appoggiato a una chiamata sincrona a Sonar. Il giorno in cui Perplexity riformula quella richiesta come richiesta Agent API, il widget non cambia una riga ma può cambiare risposta: più lunga, con le fonti in un ordine diverso, o con marcatori che il front-end non riconosce. Un cliente riceve così una risposta rassicurante con una fonte che non parla della sua data.
In un settore dove l'informazione orienta una spesa già pagata, le misure sono tre, e costano poco: mostrare sempre fonte e data accanto alla risposta; una frase fissa («verifica sul sito ufficiale prima di partire»); un campione settimanale di domande registrate da rileggere. Se l'agenzia ha promesso ai propri clienti che i loro dati non vengono conservati, vale anche quanto detto nell'articolo 1: con l'Agent API la conservazione lato server dello stato delle risposte esiste, e store: false non la disattiva. La promessa va ricontrollata prima di migrare, non dopo.
Che cosa sai fare adesso
Sai dire che cosa è cambiato nella forma di una richiesta, di una risposta e di una citazione, e sai tradurre un corpo Sonar nel corpo equivalente per l'Agent API sapendo dove la traduzione si ferma. Sai cercare nel tuo codice i punti da toccare, riconoscere la regola che fa sparire i marcatori nuovi dal front-end e confrontare due livelli su domande tue con un criterio che puoi ripetere dopo ogni aggiornamento. Resta fuori ciò che il prodotto risponde davvero: quello lo vedrai solo con la tua chiave. L'articolo 5 sposta l'attenzione sugli strumenti di sviluppo, con il server MCP ufficiale.
Domande frequenti
Sonar è ancora disponibile?
La pagina di migrazione letta il 13 novembre 2026 dice che il supporto alle chat completions Sonar è terminato il 27 settembre 2026, che le richieste sincrone e in streaming vengono riformulate come richieste Agent API e che quelle asincrone non sono più supportate.
A quale livello di effort corrisponde sonar-pro?
La documentazione indica fast come punto di partenza, non come equivalenza. Per decidere il livello giusto serve un insieme di domande tue, provato su più livelli.
Come cambiano le citazioni?
Le fonti stanno in un elemento search_results dell'array output, e i marcatori nel testo sono [1] a fast e [web:1] da low in su. Il codice che cercava citations nella risposta a choices va riscritto.
Che fine fanno le richieste asincrone?
Non vengono riformulate e non sono più supportate: vanno spostate sulla modalità background dell'Agent API, inviando con background true e controllando lo stato della risposta per identificativo.
Più avanti nella serie trovi anche l'articolo 7 su PerplexityBot e robots.txt e l'articolo 8 su che cosa è provato per farsi citare.
Fonti
- Perplexity, Migrate from Sonar to the Agent API - fine del supporto il 27 settembre 2026, sorte delle richieste sincrone, in streaming e asincrone, mappatura di partenza dei modelli; consultata il 2026-11-13
- Perplexity, How to migrate from Sonar - regole di traduzione campo per campo, parametri senza equivalente, citazioni inline, streaming; consultata il 2026-11-13
- Perplexity, strumento web_search - filtri,
max_results, forma disearch_resultsnella risposta; consultata il 2026-11-13 - Perplexity, Background mode - sostituto delle richieste asincrone, stati della risposta; consultata il 2026-11-13
- Perplexity, Conversation state - conservazione lato server dello stato e comportamento di
store: false; consultata il 2026-11-13 - Community Perplexity, Sonar moving to Agents API - risposta dello staff del 10 settembre 2026 sul ritiro dell'endpoint; letta il 2026-11-13
Commenti
Caricamento commenti...
Accedi per commentare