Crea un agente AI che genera flipbook

E se “pubblica il report di questo mese come flipbook” fosse qualcosa che il computer fa da solo — senza dashboard, senza upload, senza copiare e incollare un link di condivisione in una email? È questa la promessa di un agente AI per i documenti: descrivi il risultato che vuoi e l'agente chiama gli strumenti giusti, nell'ordine giusto, per realizzarlo.

Questo tutorial mostra come crearne uno con il server MCP di FlipLink e Claude. L'agente prenderà un report PDF appena generato, ne creerà un flipbook, lo pubblicherà e restituirà un link di condivisione — il genere di cosa che puoi mettere in calendario e dimenticare. Saremo anche onesti su dove un agente completamente autonomo incontra dei limiti reali, e su quando un semplice script (la CLI) è lo strumento migliore.

Lo scenario: un report mensile pubblicato in automatico

Immagina un'attività ricorrente. Il primo di ogni mese una pipeline produce report.pdf — numeri di vendita, una newsletter, una presentazione per il consiglio. Oggi una persona lo carica nella dashboard, lo pubblica, copia il link e lo incolla da qualche parte. Vogliamo automatizzare tutto questo con un agente capace di ragionare sui vari passaggi, invece di programmarli a mano uno per uno.

L'agente deve essere in grado di: creare un flipbook dal file, pubblicarlo e recuperare il link di condivisione. Con il server MCP di FlipLink collegato, queste azioni corrispondono a strumenti reali che il modello può chiamare direttamente.

Passo 1 — Collega il server MCP

Il Model Context Protocol è il modo in cui un client AI (Claude, Cursor e altri) scopre e chiama strumenti esterni. Il server MCP di FlipLink espone l'API di FlipLink come un insieme di strumenti che il modello può usare in una conversazione.

Per la guida completa, vedi Collega FlipLink a Claude con il server MCP. In breve — non c'è niente da installare a mano, il tuo client lo avvia con npx:

claude mcp add fliplink -e FLIPLINK_API_KEY=YOUR_API_KEY -- npx -y fliplink-mcp

Oppure, come blocco di configurazione mcpServers (Claude Desktop, Cursor, Codex):

{
  "mcpServers": {
    "fliplink": {
      "command": "npx",
      "args": ["-y", "fliplink-mcp"],
      "env": { "FLIPLINK_API_KEY": "YOUR_API_KEY", "FLIPLINK_MCP_MODE": "safe" }
    }
  }
}

Gli strumenti vengono generati dalla specifica di FlipLink e nominati <noun>_<verb> — quindi l'agente vedrà flipbook_create_by_file, flipbook_publish, flipbook_get_share_link e un controllo di stato whoami a livello principale, tra gli altri. Ottieni la tua chiave accedendo a go.fliplink.me.

Passo 2 — Scrivi il prompt dell'agente

Un agente in fondo non è altro che un modello più un ciclo: legge l'obiettivo, decide quale strumento chiamare, legge il risultato e decide cosa fare dopo, finché l'obiettivo non è raggiunto. La qualità di quel ciclo dipende quasi interamente da un prompt chiaro che indica gli strumenti, l'ordine e la condizione di successo.

Ecco un prompt realistico di sistema/attività per l'agente del report mensile:

SYSTEM:
You are a publishing agent for FlipLink. Your job is to turn a PDF report
into a published flipbook and return its share link. You have FlipLink MCP
tools available (names follow the pattern noun_verb).

Operating rules:
1. Start by calling `whoami` to confirm the API key works and check the
   remaining flipbook quota. If `whoami` fails, STOP and report the error.
2. Create the flipbook from the file with `flipbook_create_by_file`
   (field File = the PDF path; set Name and Title from the task).
3. Read the result. Every FlipLink response has a top-level `Result` field
   that is "OK" or "ERROR". If `Result` is "ERROR", STOP and report the
   `Message` — do NOT retry blindly or proceed.
4. On success, capture the returned flipbook ID.
5. Publish it with `flipbook_publish` using that ID. Check `Result` again.
6. Fetch the share link with `flipbook_get_share_link`.
7. Report back: the flipbook ID, the published share URL, and the quota left.

Never invent tool names or IDs. If a step has no clear next action,
stop and explain rather than guessing.

TASK:
Publish this month's report. File: ./reports/2026-06-report.pdf
Title: "June 2026 Report". Name: "june-2026-report".

Due cose rendono efficace questo prompt. Primo, dice all'agente di ramificare in base al campo Result — FlipLink restituisce gli errori applicativi come HTTP 200 con Result: "ERROR", quindi un controllo ingenuo del tipo “la chiamata ha restituito 200?” tratterebbe in silenzio i fallimenti come successi. Secondo, dà una condizione di arresto esplicita per ogni percorso di errore, e questo evita che un'esecuzione non presidiata sprofondi in una serie di tentativi.

Passo 3 — Protezioni per le esecuzioni non presidiate

È qui che bisogna avere le idee chiare. La modalità MCP predefinita è safe (79 strumenti): letture più scritture reversibili, senza eliminazioni e senza strumenti commerciali. Il nostro agente del report mensile si limita a creare, pubblicare e leggere — tutte azioni che rientrano nella modalità safe — quindi per questo compito puoi lasciare l'impostazione predefinita e l'agente gira dall'inizio alla fine senza attriti.

Le azioni distruttive sono un'altra storia. Se il tuo agente dovesse mai eliminare un flipbook o toccare prezzi/vendite, deve girare in modalità full (87 strumenti). In modalità full, gli strumenti di eliminazione e quelli legati al denaro non vengono mai eseguiti alla prima chiamata: il server restituisce un'anteprima di una riga più un confirm_token a vita breve (legato agli argomenti esatti, scade dopo 5 minuti), e l'assistente deve richiamarlo con quel token. Quel controllo risiede nel server — l'API di FlipLink in sé rimane invariata.

Sii onesto su cosa significa tutto questo per la “piena autonomia”:

• Un agente che legge, crea e pubblica in modalità safe può girare in autonomia senza problemi. Niente di ciò che fa è soggetto a controlli.
• Un agente che elimina elementi non può essere allo stesso tempo privo di attriti e non presidiato. Il controllo del confirm-token è lì apposta. O una persona approva il passaggio distruttivo, oppure la tua infrastruttura gira in modalità full e gestisce esplicitamente nel codice la sequenza anteprima → confirm-token → seconda chiamata. Non progettare una pipeline che dia per scontato che un flipbook si elimini in silenzio da solo senza alcuna conferma — non lo farà, ed è proprio questo il punto.

Per l'analisi completa delle modalità e del flusso del confirm-token, vedi Sicurezza e protezioni del server MCP. Gli strumenti includono anche delle annotazioni MCP (readOnlyHint, destructiveHint, idempotentHint), così un'infrastruttura attenta può valutare il rischio prima di chiamare qualsiasi cosa.

🚀

Prova FlipLink Gratis

Converti il tuo PDF in pochi secondi. Senza registrazione, senza carta di credito — basta caricare il file.

Drop your PDF here or click to browse

Max 40MB

I piani a pagamento da $39 portano questo limite a 150 MB.

Passo 4 — Mettilo in calendario

Una volta che l'agente gira in modo affidabile a mano, mettilo su un timer. Come farlo dipende dal tuo client — un cron job che invoca Claude in modalità headless con il prompt dell'attività, un workflow pianificato, oppure la tua orchestrazione personale. La meccanica esula da questa guida; la parte importante è che a rendere sicura un'esecuzione pianificata sono il prompt e la modalità, non lo scheduler in sé. Tieni l'agente in modalità safe per i lavori di creazione/pubblicazione e l'esecuzione resta non presidiata senza sbattere contro un muro di conferme.

Passo 5 — Verifica il risultato

Non fidarti del “l'agente ha detto che ha funzionato”. Verifica l'artefatto reale:

• Il report finale dell'agente dovrebbe includere un ID del flipbook e un URL di condivisione. Apri l'URL — dovrebbe caricare il flipbook pubblicato.
• Controlla la quota di whoami prima e dopo, così sai che la creazione ha davvero consumato uno slot invece di fallire in silenzio.
• Poiché ogni risultato di uno strumento porta con sé un campo Result, un agente ben costruito mostra il Message esatto in caso di fallimento. Se l'esecuzione riporta Result: "ERROR", leggi il messaggio invece di rilanciarla — un limite di quota o un file troppo grande non si sistemano da soli al prossimo tentativo.

Quando la CLI è lo strumento migliore

Ecco l'onesto contrappunto a tutto quanto sopra: per un lavoro headless e deterministico in CI, di solito non ti serve affatto un agente LLM.

Un agente AI dà il meglio quando il compito richiede giudizio — decidere che titolo dare a qualcosa, reagire a input ambigui o concatenare passaggi che non hai definito del tutto. Ma “prendi questo file preciso, crea un flipbook, pubblicalo, stampa il link” non ha alcuna ambiguità. Far girare un LLM per questo aggiunge costi, latenza e non determinismo senza alcun vantaggio, e devi comunque gestire la stessa ramificazione su Result.

Per questo, affidati alla CLI di FlipLink. È generata dalla stessa specifica del server MCP e dell'API, quindi non può divergere, e restituisce exit code puliti (0 successo, 1 errore di richiesta, 2 errore applicativo) su cui la CI può ramificare senza alcun parsing:

fliplink config set-key "$FLIPLINK_API_KEY"
ID=$(fliplink flipbook create ./reports/2026-06-report.pdf \
  --title "June 2026 Report" --name june-2026-report --json | jq -r '.ID')
fliplink flipbook publish "$ID"
fliplink flipbook share-link "$ID"

Ecco l'intero lavoro mensile, senza alcun modello. Per una pipeline completa — compreso come eseguirla all'interno della continuous integration — vedi Automatizza la pubblicazione dei flipbook in CI/CD.

Regola pratica: usa un agente AI quando il compito richiede giudizio; usa la CLI quando deve essere sempre identico. Molti team usano entrambi — l'agente per le richieste estemporanee del tipo “pubblica questo per me”, la CLI per le esecuzioni pianificate e meccaniche.

Inizia a creare

Un agente AI per i documenti elimina la parte manuale, quella centrale, della pubblicazione: tu enunci il risultato, lui chiama gli strumenti. Con FlipLink MCP in modalità safe, un agente che crea e pubblica gira dall'inizio alla fine senza attriti — e dove entrano in gioco le azioni distruttive, il controllo del confirm-token mantiene le esecuzioni non presidiate oneste anziché pericolose.

Pronto? Collega il server MCP, punta un agente verso un report e guardalo pubblicare. Per il percorso deterministico in CI, ci pensa la documentazione della CLI. L'intero catalogo degli endpoint si trova nella referenza API.

Letture correlate

• Collega FlipLink a Claude con il server MCP
• Sicurezza e protezioni del server MCP
• Automazione dei flipbook in linguaggio naturale
• Automatizza la pubblicazione dei flipbook in CI/CD
• La documentazione della CLI di FlipLink
• La referenza API di FlipLink