In enterprise HR scenarios, batch contract generation is one of the most common document processing needs — monthly new employee onboarding, contract renewals, labor agreement changes often involve processing dozens or even hundreds of contracts at once. Each contract needs personalized information such as employee name, position, salary, and contract term.

Comparison with Traditional SDK API Processing

This article introduces how to use Spire.Agent.Office Word AI capabilities to automatically write Excel employee data into Word templates and generate contracts in PDF format in batches, using both mail merge and placeholder replacement approaches. You are also free to save as DOCX, DOC, HTML, OFD, Markdown, XPS, and other formats to meet different archiving needs.

• Mail Merge Approach
• Placeholder Replacement Approach

For product installation and SpireToken configuration, please refer to Integrating Spire.Agent.Office in a .NET Project. The following examples assume Spire.Agent.Office is already installed and SpireToken is configured.

Mail Merge Approach

Mail merge is the standard solution for batch Word document generation and the most commonly used pattern in HR scenarios. The core idea is: a contract template Word document with merge fields and a data source, letting AI complete the data-to-template merge.

using Spire.Agent.Office.AI;
using Spire.Agent.Office.Extensions;
using Spire.Doc;

// Multiple document paths (data source files)
string[] attachmentPaths = new string[] { @"E:\data.xlsx" };

// Word template file path
string inputPath = @"E:\template-mailmerge.docx";  
// Result document path (null here — will use the output folder path set below)
string savePath = null;  
// Output directory
string OutDir = @"E:\output";  
// SpireToken Key
string key = "**************************";  
// Natural language instruction
string instruction =
      "Execute mail merge: populate employee data from the attachment 'data.xlsx' into the merge fields of the contract template row by row; " +
      "preserve the original document layout and styling after merging; " +
      "generate one independent contract document per employee and save the output in PDF format"; 

// Call the Word document processing function
AIResult result = ExecuteDemoWord(instruction, inputPath, savePath, key, OutDir, attachmentPaths);

// Record processing log
WriteLog(result, "word", @"E:\log\");


// Execute Word document AI processing
static AIResult ExecuteDemoWord(string instruction, string inputPath, string savePath, string key, string output, string[] attachmentPaths)
{
    // Create AIOptions configuration object
    AIOptions options = new AIOptions();
    // Set working directory to output directory
    options.WorkDir = output; 
    // Set SpireToken Key
    options.SpireToken = key;  

    // Use Document object to process Word document
    using (Document doc = new Document())
    {
        // Load Word template from file
        if (!string.IsNullOrEmpty(inputPath) && File.Exists(inputPath))
        {
            doc.LoadFromFile(inputPath);  
        }
        // Create AI document processor
        AIDocumentProcessor processor = doc.AI(options);
    
        // Execute AI instruction
        return processor.ExecuteInstruction(doc, instruction, savePath, attachmentPaths);
    }
}

Original Word template (with mail merge fields) and Excel data Output generated via mail merge

Each generated contract fully preserves the template's formatting, table styles, and font settings, with all merge fields replaced by the corresponding employee data. If 50 new employees are being onboarded, just one template + one Excel file + one instruction is all it takes to generate all contracts.

Placeholder Replacement Approach

The placeholder replacement approach does not require predefining mail merge fields in the template. Instead, it uses custom placeholder markers (such as {{Name}}, {{Salary}}) directly in the document, which the AI agent identifies and replaces.

// Multiple document paths (data source files)
string[] attachmentPaths = new string[] { @"E:\data.xlsx" };

// Contract template file path
string inputPath = @"E:\template.docx";  
// Save path (null here — will use the output folder path set below)
string savePath = null;  
// Output directory
string OutDir = @"E:\output"; 
// SpireToken Key
string key = "**************************";  

// Natural language instruction
string instruction =
    "Read employee data from 'data.xlsx' and replace the corresponding placeholders in the contract template row by row" +  
    "Highlight the replaced field content, preserve the original document layout, styling, and fonts after replacement," +  
    "Generate one independent contract document per employee and save the output in PDF format"; 

// Call the AI Word document processing method
AIResult result = ExecuteDemoWord1(instruction, inputPath, savePath, key, OutDir, attachmentPaths);

// Record processing log
WriteLog(result, "word", @"E:\log\");


// Execute Word document AI processing
static AIResult ExecuteDemoWord(string instruction, string inputPath, string savePath, string key, string output, string[] attachmentPaths)
{
    // Create AIOptions configuration object
    AIOptions options = new AIOptions();
    // Set working directory to output directory
    options.WorkDir = output;  
    // Set SpireToken Key
    options.SpireToken = key; 

    // Use Document object to process Word document
    using (Document doc = new Document())
    {
        // Load Word template from file
        if (!string.IsNullOrEmpty(inputPath) && File.Exists(inputPath))
        {
            doc.LoadFromFile(inputPath);  
        }
        // Create AI document processor
        AIDocumentProcessor processor = doc.AI(options);
    
        // Execute AI instruction
        return processor.ExecuteInstruction(doc, instruction, savePath, attachmentPaths);
    }
}

Original Word template (with {{}} placeholders) and Excel data Output generated via placeholder replacement

Two Approaches Compared

For creating Word templates with Spire.Agent.Office, please refer to the article "Creating Various Word Templates with Spire.Agent.Office".

Frequently Asked Questions

Generated document style changed

Cause: The AI model may modify or add content during processing.

Solution: Add a description like "preserve the original document layout, styling, and fonts" to the instruction.

Number of generated documents does not match the number of data rows after mail merge

Cause: Empty rows or merged cells in the data source Excel file, causing inaccurate row counting.

Solution: Ensure the first row of the data source contains column headers, with each subsequent row corresponding to one employee record and no empty rows in between. If the issue persists, add a sequence number column to the data source for validation.

Obtaining a SpireToken Key

• Contact sales@e-iceblue.com or visit https://www.e-iceblue.com/TemLicense.html to obtain a trial or commercial API key.

Configure it in code:

AIOptions options = new AIOptions();
options.SpireToken = key;

Traditional Spire.Office for .NET workflows often require developers to have in-depth API knowledge and write extensive boilerplate code for tasks like formatting, extraction, and conversion. Spire.Agent.Office introduces an AI layer that abstracts this complexity, enabling you to accomplish these tasks using plain natural language instructions.

This tutorial walks you through integrating Spire.Agent.Office into a .NET 10 project, enabling natural-language-powered document processing with minimal code.

• Why Choose Spire.Agent.Office
• Project Setup and Library Reference
• AI-Powered Document Processing
• Frequently Asked Questions
• Apply for SpireToken Key

Why Choose Spire.Agent.Office

Spire.Agent.Office is an AI agent built on top of the traditional Spire.Office for .NET document engine. The core differences are:

How It Works

Natural Language Instruction → Spire.Agent.Office AI Layer → Spire.Office Document Engine → Output File

Spire.Agent.Office parses your natural language instructions, converts them into internal calls to the Spire.Office document engine for processing, and ultimately generates the desired document. It supports processing and conversion of Word, Excel, PowerPoint, PDF, and other document formats.

Core Advantages

Typical Use Cases

• Automated internal report generation and formatting
• Batch contract processing and data extraction
• Intelligent multi-format document conversion and distribution
• Automated meeting slide layout and export

Project Setup and Library Reference

Creating a .NET 10 Project

Installing Spire.Agent.Office via NuGet

After installing Spire.Agent.Office via NuGet, dependencies are installed automatically.

Importing Spire.Agent.Office Assemblies Locally

Download Spire.Agent.Office from the website, extract it to a local directory, and import it into the project.

When adding via local DLLs, the following dependencies are also required for optimal performance:

AI-Powered Document Processing

Core Workflow

Document AI processing follows this pattern:

1. Create a document object (Workbook / Document / PdfDocument / Presentation)
2. Load a preset document (optional; can start with an empty document)
3. Configure AIOptions (set SpireToken)
4. Call .AI(options) to obtain an AIDocumentProcessor
5. Execute AI instructions and monitor execution status:
   • Processing existing documents: Call AIDocumentProcessor.ExecuteInstruction(), returns AIResult
   • Generating PPT documents: Call AIDocumentProcessor.GeneratePresentation(), returns GenerationResult

Core Code

using Spire.Agent.Office.AI;
using Spire.Agent.Office.Extensions;
using Spire.Pdf;
using Spire.Doc;
using Spire.Presentation;
using Spire.Xls;

// Excel Processing
static AIResult ExecuteDemoXls(string instruction, string inputPath, string savePath, string key, string[] attachmentPaths)
{
    AIOptions options = new AIOptions();
    options.SpireToken = key;

    using (Workbook workbook = new Workbook())
    {
        // Load the document if the input path exists and the file is accessible
        if (!string.IsNullOrEmpty(inputPath) && File.Exists(inputPath))
        {
            workbook.LoadFromFile(inputPath);
        }
        // Otherwise, use an empty Workbook
        AIDocumentProcessor processor = workbook.AI(options);
        return processor.ExecuteInstruction(workbook, instruction, savePath, attachmentPaths);
    }
}

// Word Processing
static AIResult ExecuteDemoWord(string instruction, string inputPath, string savePath, string key, string[] attachmentPaths)
{
    AIOptions options = new AIOptions();
    options.SpireToken = key;

    using (Document doc = new Document())
    {
        // Load the document if the input path exists and the file is accessible
        if (!string.IsNullOrEmpty(inputPath) && File.Exists(inputPath))
        {
            doc.LoadFromFile(inputPath);
        }
        // Otherwise, use an empty Document
        AIDocumentProcessor processor = doc.AI(options);
        return processor.ExecuteInstruction(doc, instruction, savePath, attachmentPaths);
    }
}

// PDF Processing
static AIResult ExecuteDemoPDF(string instruction, string inputPath, string savePath, string key, string[] attachmentPaths)
{
    AIOptions options = new AIOptions();
    options.SpireToken = key;

    using (PdfDocument pdf = new PdfDocument())
    {
        // Load the document if the input path exists and the file is accessible
        if (!string.IsNullOrEmpty(inputPath) && File.Exists(inputPath))
        {
            pdf.LoadFromFile(inputPath);
        }
        // Otherwise, use an empty PdfDocument
        AIDocumentProcessor processor = pdf.AI(options);
        return processor.ExecuteInstruction(pdf, instruction, savePath, attachmentPaths);
    }
}

// PPT Generation
static PPTGenerationResult GeneratPPT(string input, string instruction, string savePath, string key)
{
    AIOptions options = new AIOptions();
    options.SpireToken = key;

    using (Presentation ppt = new Presentation())
    {
        AIDocumentProcessor processor = ppt.AI(options);
        return processor.GeneratePresentation(input, instruction, savePath);
    }
}

// Based on existing PPT processing
static AIResult ExecuteDemoPPT(string inputPath, string instruction, string savePath, string key, string[] attachmentPaths)
{
    AIOptions options = new AIOptions();
    options.SpireToken = key;

    using (Presentation ppt = new Presentation())
    {
        // Load the document if the input path exists and the file is accessible
        if (!string.IsNullOrEmpty(inputPath) && File.Exists(inputPath))
        {
            ppt.LoadFromFile(inputPath);
        }
        // Otherwise, use an empty Presentation
        AIDocumentProcessor processor = ppt.AI(options);
        return processor.ExecuteInstruction(ppt, instruction, savePath, attachmentPaths);
    }
}

// Write execution log
static void WriteLog(dynamic? aiResult, string taskName, string basePath)
{
    string logFilePath = Path.Combine(basePath, $"{taskName}.txt");
    string? logDir = Path.GetDirectoryName(logFilePath);
    if (!string.IsNullOrEmpty(logDir) && !Directory.Exists(logDir))
        Directory.CreateDirectory(logDir);

    var logBuilder = new System.Text.StringBuilder();

    // Determine execution status: Success/Failure/Skipped
    string status = aiResult == null ? "SKIPPED" :
        aiResult.Success ? "SUCCESS" : $"FAILED: {aiResult.ErrorMessage}";

    logBuilder.AppendLine($"[{DateTime.Now:yyyy-MM-dd HH:mm:ss}] [{taskName}] {status}");

    if (aiResult != null)
    {
        // Log execution duration
        logBuilder.AppendLine($" | Duration: {aiResult.Duration.TotalSeconds:F2}s");

        // Log token usage statistics
        var tu = aiResult.TokenUsage;
        if (tu != null)
        {
            logBuilder.Append($" | In: {tu.InputTokens:N0}");           // Input tokens
            logBuilder.Append($" | Out: {tu.OutputTokens:N0}");         // Output tokens
            logBuilder.Append($" | CacheR: {tu.CacheReadTokens:N0}");   // Cache read tokens
            logBuilder.Append($" | CacheW: {tu.CacheWriteTokens:N0}");  // Cache write tokens
            logBuilder.Append($" | CacheT: {tu.TotalCacheTokens:N0}");  // Total cache tokens
            logBuilder.Append($" | Total: {tu.TotalTokens:N0}");        // Total tokens
        }
    }

    logBuilder.AppendLine();
    File.AppendAllText(logFilePath, logBuilder.ToString());
}

Calling AI Processing

The following examples demonstrate using natural language interaction to leverage the system's powerful document processing capabilities for various complex document tasks.

// Multiple document paths
string[] attachmentPaths = new string[] { };

// Word Processing
string inputPath = @"in.docx";
string savePath = @"out.pdf";
string key = "SpireToken key";
string instruction = "Find '****' and highlight it, save result to PDF";
AIResult result = ExecuteDemoWord(instruction, inputPath, savePath, key, attachmentPaths);
WriteLog(result, "word", @"log\");

// PPT Processing
string inputPath = @"in.pptx";
string savePath = @"out.pptx";
string key = "SpireToken key";
string instruction = "Add notes description to each slide";
AIResult result = ExecuteDemoPPT(instruction, inputPath, savePath, key, attachmentPaths);
WriteLog(result, "ppt", @"log\");

// PPT Generation
string inputPath = @"AI.md";
string savePath = @"out.pptx";
string key = "SpireToken key";
string instruction = "Generate a PPT based on AI.md";
PPTGenerationResult result = GeneratPPT(inputPath, instruction, savePath, key);
WriteLog(result, "ppt", @"log\");

// PDF Processing
string inputPath = @"in.pdf";
string savePath = @"out.md";
string key = "SpireToken key";
string instruction = "Extract table data and save as standard markdown format";
AIResult result = ExecuteDemoPDF(instruction, inputPath, savePath, key, attachmentPaths);
WriteLog(result, "pdf", @"log\");

// Excel Processing
string inputPath = @"in.xlsx";
string savePath = @"out.pdf";
string key = "SpireToken key";
string instruction = "Delete empty rows in the document";
AIResult result = ExecuteDemoXls(instruction, inputPath, savePath, key, attachmentPaths);
WriteLog(result, "xls", @"log\");

Frequently Asked Questions

SpireToken Key Not Configured Properly

If the SpireToken Key is not configured, is incorrect, or has expired, Spire.Agent.Office will throw an exception and the program will abort. Ensure the SpireToken Key is valid before proceeding.

AI Instruction Execution Failed

The AIResult returned by ExecuteInstruction may contain failure information. Check the Success property.

AIResult result = processor.ExecuteInstruction(doc, instruction, outputPath);

if (result == null || !result.Success)
{
    throw new InvalidOperationException(
        $"AI instruction failed: {result?.ErrorMessage ?? "Unknown error"}");
}

Incorrect Document Path

If processing an existing document, an incorrect file path will cause document loading to fail:

• Ensure the document path is correct
• For multi-document operations (e.g., document merging), additional documents can be defined in attachmentPaths

Apply for SpireToken Key

Spire.Agent.Office requires a valid SpireToken Key to experience full functionality:

• Contact sales@e-iceblue.com or visit https://www.e-iceblue.com/TemLicense.html to obtain a trial or commercial API key

Configure it in your code:

AIOptions options = new AIOptions();
options.SpireToken = key;