Crie um agente de IA que gera flipbooks

E se “publicar o relatório deste mês como um flipbook” fosse algo que o seu computador fizesse sozinho — sem painel, sem upload, sem copiar e colar um link de compartilhamento em um e-mail? Essa é a promessa de um agente de IA para documentos: você descreve o resultado e o agente chama as ferramentas certas, na ordem certa, para que ele aconteça.

Este tutorial mostra como criar um com o servidor MCP da FlipLink e o Claude. O agente vai pegar um relatório em PDF recém-gerado, criar um flipbook a partir dele, publicá-lo e devolver um link de compartilhamento — o tipo de coisa que você pode rodar de forma agendada e esquecer. Também vamos ser honestos sobre onde um agente totalmente autônomo esbarra em limites reais, e quando um script simples (a CLI) é a ferramenta melhor.

O cenário: um relatório mensal publicado automaticamente

Imagine um trabalho recorrente. No primeiro dia de cada mês, algum pipeline gera o report.pdf — números de vendas, uma newsletter, uma apresentação para o conselho. Hoje uma pessoa faz o upload no painel, publica, copia o link e cola em algum lugar. Queremos automatizar isso com um agente que consiga raciocinar sobre as etapas em vez de codificarmos cada uma manualmente.

O agente precisa conseguir: criar um flipbook a partir do arquivo, publicá-lo e buscar o link de compartilhamento. Com o servidor MCP da FlipLink conectado, isso corresponde a ferramentas reais que o modelo pode chamar diretamente.

Etapa 1 — Conecte o servidor MCP

O Model Context Protocol é como um cliente de IA (Claude, Cursor e outros) descobre e chama ferramentas externas. O servidor MCP da FlipLink expõe a API da FlipLink como um conjunto de ferramentas que o modelo pode usar em uma conversa.

Para o passo a passo completo, veja Conecte a FlipLink ao Claude com o servidor MCP. A versão curta — nada para instalar manualmente, o seu cliente o inicia com o npx:

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

Ou, como um bloco de configuração mcpServers (Claude Desktop, Cursor, Codex):

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

As ferramentas são geradas a partir da especificação da FlipLink e nomeadas no padrão <noun>_<verb> — então o agente vai ver flipbook_create_by_file, flipbook_publish, flipbook_get_share_link e uma verificação de saúde whoami de nível superior, entre outras. Pegue a sua chave fazendo login em go.fliplink.me.

Etapa 2 — Escreva o prompt do agente

Um agente é, na verdade, só um modelo somado a um loop: ele lê o objetivo, decide qual ferramenta chamar, lê o resultado e decide o que fazer em seguida, até o objetivo ser cumprido. A qualidade desse loop vem quase inteiramente de um prompt claro que nomeia as ferramentas, a ordem e a condição de sucesso.

Aqui está um prompt realista de sistema/tarefa para o agente do relatório mensal:

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".

Duas coisas fazem esse prompt funcionar. Primeiro, ele diz ao agente para ramificar com base no campo Result — a FlipLink retorna erros de aplicação como HTTP 200 com Result: "ERROR", então uma verificação ingênua do tipo “a chamada retornou 200?” trataria as falhas como sucessos sem que ninguém percebesse. Segundo, ele dá uma condição de parada explícita para cada caminho de falha, o que impede que uma execução autônoma entre em uma espiral de novas tentativas.

Etapa 3 — Proteções para execuções autônomas

É aqui que você precisa ter os olhos abertos. O modo MCP padrão é o safe (79 ferramentas): leituras mais gravações reversíveis, com nenhuma exclusão e nenhuma ferramenta de comércio. Nosso agente do relatório mensal só cria, publica e lê — tudo isso cabe dentro do modo safe — então, para este trabalho, você pode manter o padrão e o agente roda de ponta a ponta sem atrito.

Ações destrutivas são outra história. Se o seu agente algum dia precisar excluir um flipbook ou mexer em preços/vendas, ele tem que rodar no modo full (87 ferramentas). No modo full, as ferramentas de exclusão e de dinheiro nunca rodam na primeira chamada: o servidor retorna uma prévia de uma linha mais um confirm_token de curta duração (vinculado aos argumentos exatos, expira em 5 minutos), e o assistente tem que chamar de novo com esse token. Esse controle fica no servidor — a própria API da FlipLink não muda.

Seja honesto sobre o que isso significa para o “totalmente autônomo”:

• Um agente que lê, cria e publica no modo safe pode rodar de forma autônoma e limpa. Nada do que ele faz passa por controle.
• Um agente que exclui coisas não pode ser ao mesmo tempo sem atrito e autônomo. O controle de confirm-token está ali de propósito. Ou uma pessoa aprova a etapa destrutiva, ou o seu harness roda no modo full e lida explicitamente, no código, com o handshake prévia → confirm-token → segunda chamada. Não projete um pipeline que pressuponha que um flipbook vai se excluir silenciosamente sem nenhuma confirmação — ele não vai, e esse é justamente o ponto.

Para o detalhamento completo dos modos e do fluxo de confirm-token, veja Segurança e proteções do servidor MCP. As ferramentas também carregam anotações MCP (readOnlyHint, destructiveHint, idempotentHint), então um harness cuidadoso consegue raciocinar sobre o risco antes de chamar qualquer coisa.

🚀

Experimente o FlipLink Grátis

Converta seu PDF em segundos. Sem cadastro, sem cartão de crédito — basta enviar o arquivo.

Drop your PDF here or click to browse

Máx 40MB

Os planos pagos a partir de $39 aumentam esse limite para 150 MB.

Etapa 4 — Agende a execução

Quando o agente rodar de forma confiável manualmente, coloque-o em um cronômetro. Como você faz isso depende do seu cliente — um cron job que invoca o Claude de forma headless com o prompt da tarefa, um workflow agendado ou a sua própria orquestração. A mecânica está fora do escopo aqui; a parte importante é que o prompt e o modo são o que tornam uma execução agendada segura, não o agendador em si. Mantenha o agente no modo safe para trabalhos de criação/publicação, e a execução permanece autônoma sem esbarrar em uma parede de confirmação.

Etapa 5 — Verifique a saída

Não confie em “o agente disse que funcionou”. Verifique o artefato real:

• O relatório final do agente deve incluir um ID de flipbook e uma URL de compartilhamento. Abra a URL — ela deve carregar o flipbook publicado.
• Confira o quota do whoami antes e depois, para você saber que a criação realmente consumiu um slot em vez de falhar silenciosamente.
• Como todo resultado de ferramenta carrega um campo Result, um agente bem construído mostra a Message exata em caso de falha. Se a execução reportar Result: "ERROR", leia a mensagem em vez de rodar de novo — um limite de quota ou um arquivo grande demais não vai se resolver sozinho em uma nova tentativa.

Quando a CLI é a ferramenta melhor

Aqui está o contraponto honesto a tudo o que foi dito acima: para um trabalho headless e determinístico em CI, normalmente você não quer um agente de LLM, ponto.

Um agente de IA brilha quando a tarefa envolve julgamento — decidir como intitular algo, reagir a uma entrada ambígua ou encadear etapas que você não detalhou por completo. Mas “pegue exatamente este arquivo, crie um flipbook, publique e imprima o link” tem zero ambiguidade. Rodar uma LLM para isso adiciona custo, latência e não-determinismo sem benefício algum, e você ainda tem que lidar com a mesma ramificação do Result.

Para isso, recorra à CLI da FlipLink. Ela é gerada a partir da mesma especificação que o servidor MCP e a API, então não pode divergir, e retorna códigos de saída limpos (0 sucesso, 1 erro de requisição, 2 erro de aplicação) que o CI pode usar para ramificar sem nenhuma análise:

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"

Esse é o trabalho mensal inteiro, sem modelo nenhum. Para um pipeline completo — incluindo rodá-lo dentro da integração contínua — veja Automatize a publicação de flipbooks em CI/CD.

Regra geral: use um agente de IA quando a tarefa precisa de julgamento; use a CLI quando ela precisa ser a mesma todas as vezes. Muitas equipes usam os dois — o agente para pedidos pontuais do tipo “publica isso pra mim”, a CLI para as execuções agendadas e mecânicas.

Comece a construir

Um agente de IA para documentos remove o meio manual da publicação: você declara o resultado, ele chama as ferramentas. Com a FlipLink MCP no modo safe, um agente que cria e publica roda de ponta a ponta sem atrito — e onde ações destrutivas entram em cena, o controle de confirm-token mantém as execuções autônomas honestas em vez de perigosas.

Pronto? Conecte o servidor MCP, aponte um agente para um relatório e veja-o publicar. Para o caminho determinístico de CI, a documentação da CLI cobre tudo. O catálogo completo de endpoints fica na referência da API.

Leitura relacionada

• Conecte a FlipLink ao Claude com o servidor MCP
• Segurança e proteções do servidor MCP
• Automação de flipbooks em linguagem natural
• Automatize a publicação de flipbooks em CI/CD
• A documentação da CLI da FlipLink
• A referência da API da FlipLink