Листи привітання для сорока нових клієнтів, сертифікат для кожного учасника, рахунок‑фактура за кожне замовлення: той самий документ, інший запис кожного разу. За допомогою GroupDocs.Assembly.Mcp, що працює локально (dnx GroupDocs.Assembly.Mcp --yes), Claude Desktop, Cursor або Copilot роблять це одним викликом інструмента assemble_per_record, який заповнює ваш шаблон Word один раз для кожного елементу масиву JSON, зберігає кожен результат у власний PDF, названий полем, яке ви обираєте, і повідомляє про записи, які не вдалося обробити, замість зупинки на першому.

Створіть PDF листа привітання для кожного клієнта у файлі customers.json, використовуючи welcome-letter.docx, і назвіть кожен файл за іменем клієнта.

Покрокова версія з налаштуваннями та усуненням проблем знаходиться в документації: Як згенерувати один документ на запис (злиття листів) за допомогою AI‑агента.

Чому не дозволити агенту виконувати цикл?

Він може, і для п’яти записів це нормально. Але цикл із сорока викликів інструмента — це сорок шансів, що агент втратить підрахунок, пропустить запис, коли контекст стає довгим, або «дружньо» перефразує один лист. Інструмент по запису переносить цикл на сервер: один виклик, один шаблон, один прохід по масиву і звіт, який точно вказує, скільки файлів було записано і які записи не пройшли. Робота агента — вибрати шаблон, файл даних і поле іменування, а потім прочитати звіт.

Що агент перевіряє спочатку?

Дві речі: як виглядають дані і що читає шаблон. У нашому тесті — п’ять клієнтів у customers.json і односторінковий лист привітання:

-> 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" ] }

Шаблон називає один запис customer; сервер визначає це сам, тому агенту не потрібно передавати dataSourceName.

Один виклик, п’ять записів, одна помилка

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

Запис 4, Wingtip Travel, не мав дати першого рахунку у даних. Інші чотири листи були записані, кожен названий за іменем клієнта, а помилка повернула номер запису та відсутнє поле. Агент повідомляє це так: «чотири листи готові; у Wingtip Travel немає дати першого рахунку, залишити рядок порожнім чи чекати дату?». Це саме та розмова, яку ви хочете, а не сорок файлів без уявлення, який з них неправильний.

Як працює розподіл

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

Три параметри виконують роботу. fileNameField називає кожен вихідний файл за полем запису, customer.Name або номером рахунку; без нього файли отримують порядковий номер. recordsPath вказує на масив, коли JSON є об’єктом, що містить його, наприклад "customers" або "batch.items". А maxDocuments — це гальмо.

Що зупиняє неконтрольований пакет?

maxDocuments, який за замовчуванням дорівнює 100 і може сягати 1000. Перед записом сервер підраховує записи; якщо їх більше за ліміт, він відмовляє. Ми встановили його в 3 проти наших п’яти клієнтів:

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

Нічого не було записано. Для розсилки, що йде реальним людям, це правильне налаштування за замовчуванням: запит, який випадково вказує на весь експорт CRM, отримує питання, а не десять тисяч PDF.

Мої дані — електронна таблиця, а не JSON

Генерація по запису читає лише JSON: масив об’єктів або об’єкт, що його містить. Коли список знаходиться у CSV або електронній таблиці, агент спочатку конвертує рядки у JSON, що агенти роблять добре, і записує файл у папку сховища. Якщо вам потрібен один документ, який перераховує кожен рядок, прайс‑лист або реєстр, це assemble_document з <<foreach>> у шаблоні, і він читає CSV і електронні таблиці безпосередньо.

Чесні обмеження

  • Збірка по запису читає лише JSON; дані CSV та електронних таблиць потрібно спочатку конвертувати.
  • Режим оцінки: кожен згенерований файл починається з “Evaluation Only. Created with GroupDocs.Assembly 26.7…”, а шаблони електронних листів зберігають лише їхній простий текстовий вміст. Ліцензуйте сервер перед реальним розсиланням.
  • Відсутнє поле призводить до помилки цього запису. allowMissingMembers: true записує його з порожнім рядком; вирішіть, що вам потрібно.
  • Дати: записуйте їх у форматі 2026-12-01T00:00:00 і форматируйте у шаблоні, як наш лист робить з <<[customer.FirstInvoice]:"d MMMM yyyy">>. У нашому тесті рядок дати без часу зміщувався на один день на машині UTC+2.
  • Сервер записує файли; він їх не надсилає. Доставка — окремий крок.

FAQ

Чи можу я виконати злиття листів за допомогою Claude без завантаження списку клієнтів?
Так. Сервер працює локально і читає customers.json з вашої папки сховища; згенеровані PDF також записуються туди.

Як називаються вихідні файли?
За полем запису, яке ви передаєте як fileNameField, у цьому випадку ім’я клієнта, тому Contoso Pharma.pdf. Без нього — порядковий номер.

Чи може кожен документ бути електронною поштою замість PDF?
Так: використайте шаблон EML або MSG, або передайте format: "eml". У режимі оцінки HTML‑тіло листа замінюється рядком оцінки, тому тестуйте вихід електронної пошти з ліцензією.

Поглибити