Lettere di benvenuto per quaranta nuovi clienti, un certificato per ogni partecipante, una fattura per ogni ordine: lo stesso documento, un record diverso ogni volta. Con GroupDocs.Assembly.Mcp in esecuzione locale (dnx GroupDocs.Assembly.Mcp --yes), Claude Desktop, Cursor o Copilot lo fanno con una singola chiamata allo strumento, assemble_per_record, che riempie il tuo modello Word una volta per ogni elemento di un array JSON, salva ogni risultato come PDF separato denominato con un campo che scegli, e segnala i record che hanno fallito invece di fermarsi al primo:
Crea un PDF di lettera di benvenuto per ogni cliente in customers.json usando welcome-letter.docx, e nomina ogni file con il nome del cliente.
The step-by-step version with config and troubleshooting is in the documentation: Come generare un documento per record (mail merge) con un agente IA.
Perché non lasciare che l’agente esegua il ciclo?
Può farlo, e per cinque record va bene. Ma un ciclo di quaranta chiamate allo strumento è quaranta opportunità perché l’agente perda il conto, salti un record quando il contesto diventa lungo, o “gentilmente” riformuli una lettera. Uno strumento per record sposta il ciclo sul server: una chiamata, un modello, un passaggio sull’array e un report che indica esattamente quanti file sono stati scritti e quali record non sono stati elaborati. Il compito dell’agente è scegliere il modello, il file dati e il campo per la denominazione, e poi leggere il report per te.
Cosa verifica prima l’agente?
Due cose: l’aspetto dei dati e ciò che legge il modello. Nel nostro test, cinque clienti in customers.json e una lettera di benvenuto di una pagina:
-> get_document_info {"file":{"filePath":"customers.json"}}
<- { "dataKind": "json",
"data": { "root": "array", "length": 5, "keys": null } }
-> get_template_fields {"template":{"filePath":"welcome-letter.docx"}}
<- { "dataSourceNames": [ "customer" ],
"fields": [ "customer.Contact", "customer.Plan", "customer.Name",
"customer.Manager", "customer.FirstInvoice" ] }
Il modello chiama un record customer; il server lo determina da solo, quindi l’agente non deve passare dataSourceName.
Una chiamata, cinque record, un fallimento
-> assemble_per_record {"template":{"filePath":"welcome-letter.docx"},
"data":{"filePath":"customers.json"},"fileNameField":"Name",
"format":"pdf"}
<- Assembled 4 of 5 document(s) from 'welcome-letter.docx' with
'customers.json', one per record (each record as 'customer'), as PDF.
Saved to:
.../Contoso Pharma.pdf
.../Fabrikam Logistics.pdf
.../Tailspin Toys.pdf
.../Litware Labs.pdf
1 record(s) failed:
record 4: InvalidOperationException: ... Can not get the value of
member 'FirstInvoice' on type 'System.Data.DataRow'. The template
reads 'FirstInvoice', which the data does not have. ...
Il record 4, Wingtip Travel, non aveva una data di prima fattura nei dati. Le altre quattro lettere sono state generate, ciascuna denominata con il nome del cliente, e il fallimento è stato restituito con il numero del record e il campo mancante. Un agente riporta ciò come “quattro lettere completate; Wingtip Travel non ha una data di prima fattura, vuoi che lasci la riga vuota o attendere la data?”. Questa è la conversazione che desideri, anziché quaranta file senza sapere quale sia errato.
Come funziona la distribuzione a ventaglio
customers.json [ {Name:"Contoso Pharma",...}, {Name:"Fabrikam ..."},
... 5 records ]
|
assemble_per_record {"template":{"filePath":"welcome-letter.docx"},
"data":{"filePath":"customers.json"},
"fileNameField":"Name","format":"pdf"}
|
+--> Contoso Pharma.pdf
+--> Fabrikam Logistics.pdf ... 2 more
'--> "4 of 5 ... 1 record(s) failed: record 4 ..."
Tre parametri fanno il lavoro. fileNameField denomina ogni output con un campo del record stesso: Name qui, o un percorso puntato come order.Number quando ogni record contiene un oggetto. Con questi record piatti customer.Name fallisce per tutti (“il record non ha il campo ‘customer.Name’ per nominare il suo file”). Senza il parametro, i file ricevono un numero progressivo, e un nome già esistente non viene mai sovrascritto: il nuovo file ottiene (1). recordsPath punta all’array quando il JSON è un oggetto che ne contiene uno, come "customers" o "batch.items". E maxDocuments è il freno.
Cosa ferma un batch incontrollato?
maxDocuments, che di default è 100 e può arrivare a 1000. Prima di scrivere qualsiasi cosa, il server conta i record; se ce ne sono più del limite, rifiuta l’operazione. Lo abbiamo impostato a 3 rispetto ai nostri cinque clienti:
-> assemble_per_record {..., "maxDocuments":3}
<- Per-record assembly failed for 'welcome-letter.docx': there are 5
records, more than maxDocuments=3. Raise 'maxDocuments' (up to 1000)
or pass fewer records.
Non è stato scritto nulla. Per una campagna di mailing che va a persone reali, questo è il valore predefinito corretto: un prompt che accidentalmente punta all’intera esportazione del CRM riceve una domanda, non diecimila PDF.
I miei dati sono un foglio di calcolo, non JSON
La generazione per record legge solo JSON: un array di oggetti o un oggetto che ne contiene uno. Quando l’elenco è in un CSV o in un foglio di calcolo, l’agente converte prima le righe in JSON, cosa che gli agenti fanno bene, e scrive il file nella cartella di archiviazione. Se quello che desideri è un unico documento che elenchi ogni riga, un listino prezzi o un registro, utilizza assemble_document con un <<foreach>> nel modello, e legge direttamente CSV e fogli di calcolo.
Limiti trasparenti
- L’assemblaggio per record legge solo JSON; i dati CSV e dei fogli di calcolo devono essere convertiti prima.
- Modalità di valutazione: ogni file generato inizia con “Evaluation Only. Created with GroupDocs.Assembly 26.7…”, e i modelli di e‑mail conservano solo il corpo in testo semplice. Licenzia il server prima di un mailing reale.
- Un campo mancante fa fallire quel record.
allowMissingMembers: truelo scrive con la riga vuota; decidi quale opzione preferisci. - Date: scrivile come
2026-12-01T00:00:00e formattale nel modello, come fa la nostra lettera con<<[customer.FirstInvoice]:"d MMMM yyyy">>. Una stringa di sola data spostata di un giorno su una macchina UTC+2 nel nostro test. - Il server scrive i file; non li invia. La consegna è un passaggio separato.
Domande frequenti
Posso fare il mail merge con Claude senza caricare l’elenco dei clienti?
Sì. Il server gira localmente e legge customers.json dalla tua cartella di archiviazione; i PDF generati vengono scritti lì.
Come vengono nominati i file di output?
Dal campo del record che passi come fileNameField, qui il nome del cliente, quindi Contoso Pharma.pdf. Senza di esso, viene assegnato un numero progressivo.
Può ogni documento essere un’e‑mail invece di un PDF?
Sì, se il modello è un’e‑mail: un modello EML o MSG viene salvato come eml, emlx o msg, un messaggio per record. Un modello Word come questa lettera non può essere salvato come e‑mail; il server risponde “a WordProcessing template cannot be saved as ’eml’”. In modalità di valutazione il corpo HTML di un’e‑mail è sostituito dalla riga di valutazione, quindi testa l’output e‑mail con una licenza.
Approfondisci
- Documentazione, guida canonica: Come generare un documento per record (mail merge) con un agente IA
- Hub della documentazione: GroupDocs.Assembly MCP Server
- Pagina prodotto GroupDocs.Assembly MCP — installazione con un click per VS Code e Cursor, configurazioni per tutti gli altri client
- Inizia qui: Lascia che il modello riempia i dati, non scriva il documento
- Correlato: Di cosa ha bisogno questo modello? Chiedilo.
- Correlato: Il grafico proviene dal modello, i numeri provengono dai dati
- Correlato: Il tuo repository ha già i dati; lascia che l’agente crei il PDF
- On-premise e modello di sicurezza: 3 architetture per l’elaborazione di documenti IA, e quella che mantiene i file all’interno della tua rete
- Domande: Forum GroupDocs Assembly
- Fonte: GroupDocs.Assembly.Mcp su GitHub