Para converter em lote uma pasta com um agente de IA, aponte o servidor GroupDocs.Conversion.Mcp para a pasta e descreva o trabalho em uma frase. O agente percorre os arquivos, chama o motor de conversão uma vez por documento e relata o que produziu, tudo localmente no Claude, Cursor ou GitHub Copilot. É processamento em lote dirigido por uma frase:

Converta todos os DOCX da minha pasta de documentos para PDF, mantendo os originais

A versão passo a passo com configuração e solução de problemas está na documentação: Como converter em lote uma pasta de documentos com um agente de IA. Esta postagem percorre o mesmo trabalho como uma sessão curta, do primeiro prompt ao tratamento de falhas.

Por onde começar: a pasta de armazenamento ou o prompt?

Comece com a pasta de armazenamento. Um trabalho em lote tem sucesso ou falha na associação da pasta, e essa associação é definida uma única vez na entrada do servidor, não em cada prompt. Duas variáveis de ambiente controlam isso:

{
  "mcpServers": {
    "groupdocs-conversion": {
      "type": "stdio",
      "command": "dnx",
      "args": ["GroupDocs.Conversion.Mcp", "--yes"],
      "env": {
        "GROUPDOCS_MCP_STORAGE_PATH": "/path/to/invoices",
        "GROUPDOCS_MCP_OUTPUT_PATH": "/path/to/invoices/converted"
      }
    }
  }
}

GROUPDOCS_MCP_STORAGE_PATH é a pasta que o agente pode ler. GROUPDOCS_MCP_OUTPUT_PATH é onde os arquivos convertidos são gravados. Com ambas definidas, a pasta de origem permanece intacta e cada resultado vai para converted. Essa é a estrutura mais limpa para um lote. O comando dnx requer o SDK .NET 10; a imagem Docker ghcr.io/groupdocs-conversion/conversion-net-mcp:latest monta a pasta como /data. Reinicie o Claude Desktop, Claude Code, VS Code ou Cursor após registrar o servidor.

O que faz o primeiro prompt?

Forneça ao agente o caso simples primeiro:

Converta tudo nesta pasta de DOCX para PDF.

O agente enumera a pasta e chama a ferramenta convert para cada arquivo com format: "pdf". Cada chamada recebe um nome de arquivo do armazenamento e devolve o nome do arquivo salvo. Execute duas vezes e a segunda execução cria novos arquivos, com nomes distintos, ao lado dos primeiros.

Como adicionar um filtro ou uma regra?

O prompt é a camada de orquestração. Filtragem, sequenciamento e política de erro são expressos em linguagem natural:

Converta todos os PDFs para Markdown; ignore arquivos que já estejam convertidos.

Converta as faturas para PDF/A para arquivamento e liste qualquer arquivo que falhar.

Crie pré‑visualizações PNG de cada apresentação.

Para sequenciamento, o agente pode chamar get_document_info primeiro, que devolve o tipo de arquivo, número de páginas e propriedades básicas sem converter:

Verifique o número de páginas de cada PDF primeiro e converta apenas os que tiverem mais de 10 páginas.

A decisão “mais de 10 páginas” fica a cargo do agente. A conversão continua sendo responsabilidade do motor.

O que acontece quando um arquivo falha?

Quando o motor não consegue converter um arquivo — por exemplo, porque o formato de origem não é suportado ou a senha está incorreta — o texto de resposta para esse arquivo começa com a operação e o motivo. Um nome de arquivo inexistente devolve a lista de arquivos que o servidor consegue ver, permitindo que o agente se corrija. Para arquivos protegidos, convert aceita um parâmetro opcional password.

Por isso a política de falha deve estar no prompt: “liste qualquer arquivo que falhar” pede ao agente um relatório ao final da execução, de modo que uma falha não passe despercebida. Leia o relatório e reexecute apenas as falhas.

Sessão de exemplo

Esta é uma sessão abreviada e ilustrativa. Os nomes de arquivos são fictícios e a resposta foi construída a partir do comportamento documentado, não de uma captura de tela.

You:    Convert the invoices to PDF/A for archiving, and list any file that failed.
Agent:  [enumerates the invoice files]
Agent:  [calls convert for each file, one at a time]
Agent:  Converted 11 files to the output folder.
        Failed: invoice-0412.docx (password-protected, no password given).

Como acompanhar o progresso em uma pasta grande?

O agente normalmente processa os arquivos um após o outro, portanto o tempo de execução cresce com a quantidade e o tamanho dos arquivos. Para obter relatórios de progresso, solicite isso no prompt: “avise-me a cada dez arquivos” ou “resuma ao final”. Algumas centenas de documentos funcionam bem, e o relatório final informa o que aconteceu. Comece com uma cópia de um subconjunto pequeno, verifique duas ou três saídas manualmente e, então, execute a pasta completa.

E se o lote precisar ser executado sem supervisão?

Uma sessão de agente requer uma pessoa para iniciá‑la. Para pipelines agendados, o tutorial n8n mostra uma ferramenta de workflow que controla o mesmo servidor, e o motor também pode ser acionado por scripts usando a biblioteca GroupDocs.Conversion .NET. Use o chat para lotes ad‑hoc nos quais você deseja ler o relatório.

Quais são os limites?

  • O modo de avaliação limita um lote a 15 documentos. Sem licença, um processo de servidor pode abrir no máximo 15 documentos e a saída contém uma marca d’água de avaliação. Depois disso, chamadas adicionais falham até que o servidor seja reiniciado. Verifique o modo com get_license_status antes de iniciar um lote real, ou pergunte “qual é o status da licença do servidor de conversão?”.
  • Licenciamento por consumo requer acesso externo. Com chaves de consumo, o uso é reportado aos servidores GroupDocs, portanto uma máquina atrás de firewall deve usar um arquivo de licença. O conteúdo dos documentos nunca é enviado.
  • Digitalizações permanecem como imagens. OCR não faz parte do servidor, então um lote de PDFs apenas com imagens não ganhará camada de texto.

Perguntas frequentes

Como converto todos os arquivos DOCX de uma pasta para PDF com IA?
Defina a pasta de armazenamento e peça ao seu agente exatamente isso em uma frase. Ele converte os arquivos um a um através do servidor local e nada é enviado.

Um agente de IA pode processar uma pasta inteira localmente?
Sim. O agente e o servidor de conversão rodam na sua máquina, e os arquivos são lidos e gravados nas suas próprias pastas.

Qual a melhor forma de automatizar um pipeline de conversão de documentos?
Use o chat para lotes ad‑hoc que você deseja revisar. Para um pipeline que roda em horário programado, controle o mesmo servidor a partir de uma ferramenta de workflow como n8n, ou escreva scripts usando a biblioteca .NET.

Aprofunde‑se