Un connettore Zendesk per cognee fa dimenticare i ticket cancellati

Dopo una cancellazione su Zendesk, cognee smette di citarne il contenuto e il dataset scende di una voce: da 4 a 3 elementi nel test descritto. Il ticket sul doppio addebito di ottobre sparisce dalle risposte, restano il 500 dopo il reset password e, dagli articoli dell’Help Center, la policy resi. L’esperimento usa un trial Zendesk, pochi ticket, articoli di esempio e OpenAI come LLM¹.

È stato costruito un connettore Zendesk per cognee. Un agente può rispondere a partire dai ticket e dagli articoli del team. Il codice arriva con una pull request su topoteretes/cognee-community#356, legata all’issue topoteretes/cognee#4754¹.

L’uso è lineare: si importa cognee e la sorgente Zendesk, si chiama remember con dataset_name, primary_key e write_disposition impostato su merge, poi si interroga con recall. L’esempio nel post mostra questi passaggi, con dataset “zendesk” e chiave “id”¹.

Il connettore accetta due credenziali: email più API token, oppure un access token OAuth. La seconda strada conta: Zendesk ritira gli API token. Gli account creati dopo il 28 luglio 2026 non possono generarli, la creazione si ferma il 27 ottobre 2026, i token esistenti smettono il 30 aprile 2027¹.

Ogni ticket diventa un documento unico con l’intero thread dei commenti. Domanda e risposta restano vicine. Le note interne e gli indirizzi email restano fuori per impostazione predefinita, così un agente non cita un contenuto non rivolto al cliente¹.

La sincronizzazione usa l’export incrementale dei ticket basato su cursore. Il cursore vive nello stato dlt e si salva solo dopo un caricamento riuscito. Un ticket cancellato riappare nell’export con status="deleted": diventa un tombstone _deleted e la pulizia degli orfani di cognee lo rimuove¹.

Gli articoli non hanno un feed di cancellazione. Ogni run li elenca tutti con paginazione a cursore. Se un articolo scompare da un elenco completo, o torna bozza, viene dimenticato. Per evitare rimozioni accidentali dovute a elenchi brevi o instabili, il connettore confronta l’elenco con il conteggio che Zendesk riporta¹.

Un ticket con commenti illeggibili viene messo da parte e ritentato nei run successivi, mentre il resto della pagina prosegue. Ticket e articoli falliscono in modo indipendente, quindi un Help Center rotto non blocca i ticket. Tre 5xx consecutivi chiudono il run in modo pulito. Se Retry-After supera 30 secondi, non resta in attesa. Nel backfill dei grandi account, il progresso si salva ogni 1.000 ticket, così un OAuth in scadenza non azzera il lavoro¹.

Nei run live: primo sync con 3 ticket e 1 tombstone pregresso, poi 3 articoli pubblicati, poi un reply su ticket 3 e una modifica a un articolo che ri-sincronizza solo quei due. Segue l’eliminazione del ticket 4 e l’archiviazione di un articolo, con 1 deleted e 1 removed. Infine, un’annotazione interna su ticket 2 che resta fuori dal documento anche dopo la re-sync¹.

Due bug sono emersi e corretti. Primo: un assegnatario senza reply appariva come user <id>. Ora il connettore lo risolve con users/show_many e ogni ticket lo nomina. Secondo: un ticket cancellato e poi ripristinato tra due sync restava dimenticato, perché l’export restituiva entrambe le versioni e vinceva la delete. Ora vince la versione più recente¹.

La copertura di test sale a 101 casi. Molti nascono dalle domande della review sul “cosa succede se…”. Ogni fix ha un test che fallisce senza la correzione¹.

Le istruzioni di setup sono nel README del pull request, e lo script usato per il post è in examples/example.py, utile per replicare il percorso end-to-end¹.