Salta al contenuto principale

02 - Agent API di Perplexity: effort e citazioni

I sei livelli di effort dell'Agent API di Perplexity: come fissarne la versione, leggere le fonti, controllare le citazioni in locale e sommare il costo.

Cosa ne pensi di questo articolo?

02 - Agent API di Perplexity: effort e citazioni
Perplexityfedericocalo.dev

In Breve

I sei livelli di effort dell'Agent API di Perplexity: come fissarne la versione, leggere le fonti, controllare le citazioni in locale e sommare il costo.

Risposta diretta. L'Agent API di Perplexity si chiama con client.responses.create(effort=..., input=...) e restituisce un testo con fonti inline. Il parametro che decide costo, tempo e profondità è effort, con sei livelli (fast, low, medium, high, xhigh, ultra). Ogni livello è un pacchetto già pronto di modello, strumenti, tetto di passi e prompt di sistema, e ciò che passi accanto lo sovrascrive. Il costo da tenere d'occhio non è il livello in sé ma quanti strumenti il modello invoca dentro il tetto, perché ogni ricerca si paga a parte dai token.

I fatti sul prodotto vengono dalle pagine «Effort», «Web Search», «Agent API Models» e «Pricing» aperte il 13 novembre 2026; la documentazione dice che puoi chiamare un livello per nome (e ricevere gli aggiornamenti automatici) oppure fissarne la versione. Non ho una chiave e non ho chiamato il prodotto: i due script di questo articolo girano senza rete, su una risposta che ho costruito io nella forma documentata e che è dichiarata sintetica. Nel resto dell'articolo ciò che il modello «risponde» è sempre uno schema, mai un risultato.

I livelli, in una tabella

La pagina «Effort» riporta per ogni livello la configurazione corrente: modello, tetto di passi, ragionamento, strumenti. La versione attiva dei livelli, nella pagina letta oggi, è 2026-11-11.0.

LivelloModello dichiaratoStrumentiPassi maxRagionamentoUso indicato dalla pagina
fastopenai/gpt-6-luna (riserva openai/gpt-5.6-luna)ricerca web in modalità fast1noneFatti singoli, definizioni, riassunti brevi
lowopenai/gpt-6-lunaricerca fast, fetch_url (1 URL)5minimalDomande quotidiane con informazioni aggiornate e ricerca leggera
mediumopenai/gpt-6-lunacome low15mediumNavigazione a più salti, aggregazione su molte fonti
highopenai/gpt-6.1-terracome low40mediumRicerca profonda e ricca di fonti, senza esecuzione di codice
xhighanthropic/claude-opus-5-5 (riserva openai/gpt-6.1-sol)ricerca web, ricerca finanziaria, sandbox di codice300highLavoro aperto, con esecuzione di codice
ultraanthropic/claude-opus-5-5non dichiaratinon dichiaratinon dichiaratoRaccolta ampia, esecuzioni lunghe; si chiama per nome

Tre cose si leggono nella tabella e non si indovinano. Primo, il tetto di passi cresce in fretta (1, 5, 15, 40, 300): è il massimo, non la media, e dentro il tetto è il modello a decidere. Secondo, la ricerca è in modalità fast a tutti i livelli fino a xhigh, quindi 0,001 dollari a ricerca, non 0,0025. Terzo, ultra non ha una configurazione congelabile: la pagina dice che si chiama per nome e che può durare a lungo, per cui conviene la modalità background. Dalla versione 2026-11-11.0 i livelli non fissano un tetto totale di token in uscita: ogni generazione arriva fino a 128.000 token (nei limiti del modello) e puoi imporre un tetto complessivo con max_output_tokens.

Non copiare i nomi dei modelli nel tuo codice: il livello è il contratto, il modello è un dettaglio che Perplexity può cambiare. La stessa pagina dice che, quando aggiorna un livello, punta a restare nella stessa fascia di costo e di latenza e a migliorare la qualità; è un obiettivo dichiarato, non una garanzia misurata da me.

La prima chiamata e che cosa torna

Con una chiave, la chiamata ha questa forma. È uno schema da adattare, non eseguito qui: non ho una chiave e non rivendico nessuna risposta del prodotto. Le regole d'ingresso vengono dalla guida di migrazione: input accetta una stringa o un array di elementi del tipo {"type": "message", "role": "user", ...}; il prompt di sistema va nel campo instructions; per i dialoghi a più turni si passa previous_response_id oppure si rimandano i turni precedenti dentro input.

from perplexity import Perplexity

client = Perplexity()

risposta = client.responses.create(
    effort="low",
    instructions="Rispondi in italiano, in massimo 120 parole.",
    input="Che differenza c'è tra un crawler e un agente che legge una pagina per conto di un utente?",
)

print(risposta.output_text)
print(risposta.effort)  # la pagina «Effort» dice: livello e versione che hanno girato

L'ultima riga è quella che conta per il lavoro serio. La pagina «Effort» dice che la risposta include un campo effort con livello e versione effettivi (il suo esempio è fast@2026-10-16.0) e che rimandare quel valore come effort fissa la configurazione che hai usato. Registrarlo nei log ti permette di sapere, settimane dopo, con quale configurazione è stata prodotta una risposta; fissarlo ti protegge da un aggiornamento del livello, al prezzo di non ricevere i miglioramenti. Un nome sconosciuto, una versione sconosciuta o un valore malformato producono HTTP 400, e il validatore dell'articolo 1 li intercetta prima.

Le fonti: dove stanno e come si leggono

La risposta è un array tipizzato output che registra l'intera esecuzione. Le fonti arrivano in un elemento con type: "search_results", che porta le query eseguite e un elenco results; ogni risultato ha id, url, title, snippet, date, last_updated e source. Il testo della risposta è in un elemento message, dentro un contenuto di tipo output_text. I marcatori nel testo sono [1] a fast e della forma [web:1] da low in su, e il numero rimanda all'id del risultato.

Due avvertenze dalla pagina «Web Search». La prima: se il modello metta dei marcatori nel testo dipende dal prompt, quindi vanno chiesti; la guida di migrazione dice che i livelli fast, low, medium e high includono già le citazioni inline, e per xhigh e ultra non lo dice, quindi chiedile nelle istruzioni. La seconda: a prescindere dai marcatori, fonte di verità per le citazioni sono i campi id e url dell'elemento search_results. Lo script che segue lavora su una risposta sintetica costruita da me nella forma documentata (contenuto inventato) e controlla quattro cose: che ogni marcatore abbia una fonte con quell'id, che l'indirizzo sia https, che lo snippet non sia vuoto, che nessuna fonte sia raccolta e poi ignorata.

"""Mappa i marcatori [n] e [web:n] sulle fonti. Risposta SINTETICA, costruita da me."""
import re
from urllib.parse import urlparse

# Forma presa dalla pagina web_search della documentazione: elementi "search_results"
# e "message" dentro "output". Il contenuto e' inventato: non e' una risposta del prodotto.
RISPOSTA = {
    "effort": "low@2026-11-11.0",
    "output": [
        {"type": "search_results", "queries": ["robots.txt perplexitybot"], "results": [
            {"id": 1, "title": "Guida ai crawler", "url": "https://esempio.test/guida", "snippet": "...", "date": "2026-05-01"},
            {"id": 2, "title": "Note di rilascio", "url": "http://esempio.test/note", "snippet": "", "date": None},
            {"id": 3, "title": "Pagina mai citata", "url": "https://altro.test/x", "snippet": "...", "date": "2026-01-10"},
        ]},
        {"type": "message", "role": "assistant", "content": [{"type": "output_text", "text":
            "Il file si legge dalla radice del sito[web:1]. Un secondo crawler esiste[web:2][web:7]."}]},
    ],
}

MARCATORE = re.compile(r"\[(?:[a-z]+:)?(\d+)\]")


def testo_risposta(risposta):
    return "".join(
        parte["text"]
        for voce in risposta["output"] if voce["type"] == "message"
        for parte in voce["content"] if parte["type"] == "output_text"
    )


def fonti_per_id(risposta):
    return {
        r["id"]: r
        for voce in risposta["output"] if voce["type"] == "search_results"
        for r in voce["results"]
    }


def controlla(risposta):
    fonti = fonti_per_id(risposta)
    citati = [int(n) for n in MARCATORE.findall(testo_risposta(risposta))]
    problemi = []
    for n in sorted(set(citati)):
        f = fonti.get(n)
        if f is None:
            problemi.append(f"marcatore {n}: nessuna fonte con quell'id")
        elif urlparse(f["url"]).scheme != "https":
            problemi.append(f"marcatore {n}: url non https ({f['url']})")
        elif not (f.get("snippet") or "").strip():
            problemi.append(f"marcatore {n}: snippet vuoto, niente su cui verificare")
    for n in sorted(set(fonti) - set(citati)):
        problemi.append(f"fonte {n}: presente ma mai citata")
    return citati, problemi


citati, problemi = controlla(RISPOSTA)
print("effort registrato:", RISPOSTA["effort"])
print("marcatori trovati:", citati)
for p in problemi:
    print("-", p)

# Output:
# effort registrato: low@2026-11-11.0
# marcatori trovati: [1, 2, 7]
# - marcatore 2: url non https (http://esempio.test/note)
# - marcatore 7: nessuna fonte con quell'id
# - fonte 3: presente ma mai citata

L'uscita mostra tre problemi voluti. Il marcatore 2 cita una fonte con indirizzo non https (e con snippet vuoto: la catena di elif segnala solo il primo difetto per marcatore); il 7 non ha nessuna fonte, il caso più grave perché è una citazione a vuoto; la fonte 3 è stata raccolta e mai usata, il che non è un errore ma un segnale di quanto del lavoro (e del costo) non è arrivato nel testo. L'espressione \[(?:[a-z]+:)?(\d+)\] accetta sia [1] sia [web:1]; se il tuo front-end usa solo \[(\d+)\] non vedrà i marcatori dei livelli da low in su. Due test che vale la pena aggiungere: ogni indirizzo della mappa risponde, e la frase citata compare davvero nella pagina (l'articolo 3 mostra come fare il secondo senza rete). Un marcatore presente non dimostra che la pagina dica quella cosa.

Filtri e strumenti: cosa si sovrascrive e cosa si somma

Se passi effort insieme ad altri campi, i tuoi campi vincono. L'array tools fa eccezione: si fonde per strumento, quindi elencare web_search con i suoi filtri non rimuove fetch_url, che continua a girare. Per restringere la ricerca a una fonte e a una finestra di tempo si aggiunge lo strumento con le sue opzioni (schema da adattare, non eseguito):

risposta = client.responses.create(
    effort="low",
    input="Che cosa dice la documentazione ufficiale sui limiti di frequenza?",
    tools=[{
        "type": "web_search",
        "max_results": 8,
        "max_tokens_per_page": 2000,
        "filters": {
            "search_domain_filter": ["docs.perplexity.ai"],
            "search_recency_filter": "month",
        },
    }],
)

Il blocco restringe la ricerca a un solo dominio e alla finestra «ultimi 30 giorni», limita a otto i risultati raccolti e a 2.000 i token estratti da ciascuna pagina. I parametri documentati per web_search sono search_type ("web" o "fast"), max_results (da 1 a 50), max_tokens, max_tokens_per_page, user_location (accanto a filters, non dentro) e, in filters, search_domain_filter (fino a 20 domini o URL, con prefisso - per escludere), search_recency_filter (hour, day, week, month, year) e quattro filtri di data nel formato MM/DD/YYYY. L'errore da evitare è mescolare nello stesso elenco domini consentiti e negati: la pagina dice di usare una modalità sola.

Per sapere quali strumenti hanno girato davvero guarda l'oggetto usage della risposta: la pagina mostra usage.tool_calls_details.search_web.invocation, e dove presente usage.cost.total_cost riporta il costo calcolato della richiesta. Dal punto di vista di un revisore è la differenza fra «il modello ha cercato» e «il modello ha fatto N ricerche».

Streaming ed esecuzioni lunghe

L'Agent API emette eventi server-sent tipizzati. Per il testo si gestisce response.output_text.delta; le chiamate agli strumenti e il ragionamento arrivano come eventi response.output_item.* e response.reasoning.*, non come pezzi di testo, e un consumatore scritto per il vecchio formato a choices li ignorerebbe o ne sarebbe confuso. Con background: true la richiesta parte e si interroga per identificativo con GET /v1/agent/{id}: lo stato è non terminale finché vale queued o in_progress, e terminale con completed, failed, cancelled o incomplete.

Attenzione al conto delle richieste: la pagina dei limiti dice che anche i controlli di stato (GET /v1/agent/{id}) contano nel limite di richieste al secondo dell'organizzazione, e che con un limite di 1 richiesta al secondo (il livello 0) un controllo ogni secondo non lascia spazio a richieste nuove. Si interroga con ritardo crescente, non a intervalli fissi; l'articolo 6 ne fa codice. Se l'organizzazione esaurisce il limite di token mentre il lavoro gira, lo stato resta in_progress con un oggetto paused: si continua a interrogare, non si reinvia.

Il costo: due parti che si sommano

Una richiesta all'Agent API costa i token del modello più gli strumenti invocati. Le tariffe dei token sono pubblicate per modello nella pagina «Agent API Models», in dollari per milione di token; quelle degli strumenti stanno in «Pricing». Lo script somma le voci per una richiesta ipotetica a livello low, con un uso che ho scelto io (18.000 token in ingresso più 2.000 letti dalla cache, 1.500 in uscita, quattro ricerche fast e una fetch_url): non è una misura di una richiesta reale, è un modo per vedere da dove viene il totale.

"""Costo di una richiesta ipotetica a livello low, con le tariffe lette il 2026-11-13."""
from decimal import Decimal as D
from fractions import Fraction

MILIONE = D(1_000_000)
TARIFFE = {  # dollari per milione di token, openai/gpt-6-luna fino a 272k token
    "input": D("0.10"), "cache": D("0.01"), "output": D("0.50"),
}
STRUMENTI = {"web_search_fast": D("0.001"), "fetch_url": D("0.0005")}

# Uso IPOTETICO, scelto da me: non e' una misura.
uso = {"input": 18_000, "cache": 2_000, "output": 1_500}
chiamate = {"web_search_fast": 4, "fetch_url": 1}

voci = {k: D(uso[k]) * TARIFFE[k] / MILIONE for k in uso}
voci |= {k: STRUMENTI[k] * n for k, n in chiamate.items()}
totale = sum(voci.values())
for nome, valore in voci.items():
    print(f"{nome:16} {valore:.6f} $")
print(f"{'totale':16} {totale:.6f} $")

# Secondo calcolo, indipendente: frazioni esatte, centesimi di microdollaro.
f = sum(Fraction(uso[k]) * Fraction(str(TARIFFE[k])) / 1_000_000 for k in uso)
f += sum(Fraction(str(STRUMENTI[k])) * n for k, n in chiamate.items())
assert f == Fraction(str(totale)), (f, totale)
print("secondo calcolo (frazioni): concorda")

# Tetto dei soli strumenti a livello high: al massimo 40 chiamate, la piu' cara costa 0,001 $.
print(f"tetto strumenti high: {40 * STRUMENTI['web_search_fast']:.3f} $")

# Output:
# input            0.001800 $
# cache            0.000020 $
# output           0.000750 $
# web_search_fast  0.004000 $
# fetch_url        0.000500 $
# totale           0.007070 $
# secondo calcolo (frazioni): concorda
# tetto strumenti high: 0.040 $

La riga da guardare è la proporzione: in questo esempio gli strumenti (0,0045 dollari) pesano più dei token (0,00257), perché il modello scelto da low costa poco per milione di token e ogni ricerca ha un prezzo fisso. Con una richiesta più lunga o con un modello più caro l'equilibrio si inverte, ed è per questo che il costo va letto richiesta per richiesta nel campo usage.cost, quando c'è, e non stimato una volta per tutte. Il secondo calcolo, con frazioni esatte, concorda sul totale di 0,00707 dollari: ho verificato l'aritmetica, non l'uso. L'ultima riga dice che a livello high, dove la pagina dichiara al massimo 40 chiamate agli strumenti, i soli strumenti non superano 0,04 dollari finché la ricerca resta in modalità fast; i token di openai/gpt-6.1-terra sono fuori da quella cifra, perché nella tabella dei modelli letta oggi quel modello non ha una riga.

Scegliere il livello con un metodo, non con un'impressione

Salire di livello cambia tre cose insieme: il modello, il tetto di passi e gli strumenti disponibili, quindi non puoi isolare quale delle tre migliori la risposta. Perplexity pubblica benchmark interni nella pagina di migrazione, ma sono risultati dichiarati dal fornitore e non li riporto come prova. Il metodo che propongo è meno elegante e più affidabile:

  1. Metti insieme 30-50 domande vere del tuo prodotto, con la risposta attesa o almeno i fatti che devono comparire.
  2. Falle girare a fast, low e medium; registra il campo effort con versione, le chiamate agli strumenti, i token, il costo dove presente e il tempo.
  3. Scegli il livello più basso che passa il tuo criterio, e verifica a mano su un campione che le fonti sostengano le affermazioni.

L'ordine conta: senza il primo passo il secondo misura niente, e senza il terzo il livello più alto vince sempre, perché è il più completo e il più caro. Il criterio che consiglio è «ogni affermazione ha una fonte che la sostiene»: va controllato da una persona su un campione, perché nessun marcatore dimostra da solo che la pagina citata dica quella cosa.

Errori comuni

  • Pensare che reasoning.effort sia lo stesso di effort. La documentazione li distingue: effort sceglie il pacchetto, reasoning.effort controlla solo il ragionamento del modello scelto.
  • Passare insieme effort e profile. La pagina dice che una richiesta non può impostare entrambi.
  • Impostare temperature e aspettarsi determinismo. Per le famiglie GPT-5, o1 e o3 la guida di migrazione dice che temperature e top_p vengono ignorati, e che temperature: 0 non garantisce output identici nemmeno dove il parametro vale; per gli altri modelli la pagina non dà un elenco, quindi non darlo per scontato.
  • Trattare la risposta come testo. L'array output contiene l'audit dell'esecuzione: conservarne almeno gli identificativi delle fonti e le chiamate agli strumenti è ciò che ti permette di spiegare un errore tre settimane dopo.

I quattro errori hanno la stessa radice: trattare un pacchetto configurabile come se fosse un modello fisso. Il livello cambia con le versioni, i parametri di campionamento dipendono dal modello sottostante e la risposta è una traccia, non una stringa. Per i test ripetibili fissa la versione del livello e confronta fatti, non stringhe.

Uno scenario dichiarato: verificare un messaggio sul richiamo di un prodotto

Scenario ipotetico, con persone e ore inventate per dare un dominio all'esempio. Anna riceve nel gruppo di famiglia un messaggio su un presunto richiamo di un prodotto per bambini. Cercando a mano sui siti istituzionali impiega dieci minuti e spesso rinuncia. Un piccolo modulo suo manda la domanda a livello low con search_domain_filter limitato ai siti dell'autorità competente e chiede di rispondere solo se trova una fonte in quei domini. Il costo degli strumenti è quello dello script sopra, nell'ordine del centesimo.

Cosa va storto: la risposta può dire «confermato» citando una pagina che parla di un altro lotto o di un altro prodotto. Per questo il modulo mostra l'elenco dei link e la regola di Anna è una sola: prima di inoltrare, apre la pagina e legge il nome del prodotto. L'API serve a sapere dove guardare, non a sostituire la lettura. Per qualunque ambito in cui sbagliare costa (norme, contratti, salute) lo stesso schema regge: la risposta con fonti è un orientamento, ogni riferimento si controlla sulla fonte ufficiale prima di usarlo, e nessuna riga di un atto o di un parere nasce da un testo generato.

Che cosa sai fare adesso

Sai leggere i sei livelli di effort per ciò che dichiarano (modello, passi, strumenti, ragionamento) e sai perché non vanno copiati nel codice. Sai fissare la versione di un livello con il campo effort della risposta, estrarre le fonti dall'elemento search_results, controllare in locale che i marcatori abbiano una fonte e sommare token e strumenti per sapere da dove viene un costo. Hai un metodo per scegliere il livello più basso che regge il tuo criterio. Nell'articolo 3 trovi l'altra strada, la Search API, in cui il modello è il tuo.

← Articolo 1: la mappa delle API Articolo 3: la Search API per la tua RAG →

Domande frequenti

Quali livelli di effort ha l'Agent API di Perplexity?

fast, low, medium, high, xhigh e ultra. Ognuno è un pacchetto di modello, strumenti, tetto di passi (1, 5, 15, 40, 300 per i primi cinque) e prompt di sistema; i campi che passi insieme prevalgono sui valori predefiniti.

Come ottengo le URL delle fonti citate?

Nell'array output cerca l'elemento di tipo search_results: ogni risultato ha un id e un url, e il marcatore inline ([1] o [web:1]) rimanda a quell'id. Fonte di verità per le citazioni sono id e url, non i marcatori.

Posso fissare la versione di un livello?

Sì: la risposta include il campo effort con la versione (per esempio fast@2026-10-16.0) e quel valore può essere rimandato come effort per fissare la configurazione. Chiamando il livello per nome ricevi gli aggiornamenti automatici.

Quanto costa una richiesta all'Agent API?

I token del modello alle tariffe della pagina dei modelli più gli strumenti: 0,0025 dollari per ricerca standard, 0,001 in modalità fast, 0,0005 per fetch_url. Il numero di strumenti invocati varia entro il tetto di passi del livello.

Più avanti nella serie trovi anche l'articolo 5 sul server MCP in Claude Code e Cursor, l'articolo 7 su PerplexityBot e robots.txt e l'articolo 8 su che cosa è provato per farsi citare.

Fonti

Commenti

Caricamento commenti...

Accedi per commentare

Articoli e strumenti nuovi anche su Telegram

Il canale Telegram segnala gli articoli e gli strumenti nuovi del sito.

Ti è piaciuto questo articolo?

Esplora altri contenuti sul blog o scopri i miei progetti