{"title":"Attachment capabilities and limitations (preview)","url":"https://jonas-paprotka.de/docs/dev-itpro/ai/ai-development-toolkit-attachments/","by":"JOP-AL","license":"Copyright (c) Microsoft Corporation. CC BY 4.0, https://creativecommons.org/licenses/by/4.0/; code samples MIT. From https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/ai/ai-development-toolkit-attachments, MicrosoftDocs/dynamics365smb-devitpro-pb at 828b6ee (2026-11-19). Changed: includes filled in, links to this site, and for agents shortened without dropping a fact.","credit":"Microsoft Corporation, CC BY 4.0","origin":"https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/ai/ai-development-toolkit-attachments","source":{"name":"Business Central developer and IT pro docs","repo":"https://github.com/MicrosoftDocs/dynamics365smb-devitpro-pb","commit":"828b6ee72fcd75755627cd6011f3d20899217ab2","date":"2026-11-19"},"checked":"2026-11-19","description":"Learn about the capabilities and limitations when working with attachments in agent tasks within the AI development toolkit in Business Central. Understand supported file types, size limits, and best practices for document processing.","date":"2026-10-02","meta":{"topic":"concept-article"},"outline":[{"level":1,"title":"Attachment capabilities and limitations (preview)","slug":"attachment-capabilities-and-limitations-preview","at":0,"chars":9401},{"level":2,"title":"Supported file types","slug":"supported-file-types","at":817,"chars":348},{"level":2,"title":"File size limits","slug":"file-size-limits","at":1165,"chars":352},{"level":2,"title":"PDF page limits","slug":"pdf-page-limits","at":1517,"chars":6890},{"level":3,"title":"Considerations for multi-page PDFs","slug":"considerations-for-multi-page-pdfs","at":1685,"chars":607},{"level":3,"title":"Process attachments with custom logic","slug":"process-attachments-with-custom-logic","at":2292,"chars":3729},{"level":4,"title":"Use custom document analyzers","slug":"use-custom-document-analyzers","at":2555,"chars":1921},{"level":4,"title":"Example: Custom invoice processing","slug":"example-custom-invoice-processing","at":4476,"chars":1545},{"level":3,"title":"Best practices for document processing","slug":"best-practices-for-document-processing","at":6021,"chars":2386},{"level":4,"title":"Choose the right approach","slug":"choose-the-right-approach","at":6132,"chars":332},{"level":4,"title":"Optimize documents for processing","slug":"optimize-documents-for-processing","at":6464,"chars":418},{"level":4,"title":"Handle errors gracefully","slug":"handle-errors-gracefully","at":6882,"chars":831},{"level":4,"title":"Provide context in instructions","slug":"provide-context-in-instructions","at":7713,"chars":694},{"level":2,"title":"Related information","slug":"related-information","at":8407,"chars":994}],"text":"# Attachment capabilities and limitations (preview)\n[This article is prerelease documentation and is subject to change.]\n> IMPORTANT\n > This is a preview feature. Preview features might have restricted functionality and are subject to supplemental terms of use<https://www.microsoft.com/en-us/business-applications/legal/supp-powerplatform-preview/>.\n > The AI development toolkit is available in sandbox environments only. The Agent SDK for AL is available in sandbox environments and, starting from version 28.1, also in production environments.\n > This article is primarily intended for product owners, domain experts, consultants, and developers who want to experiment with AI capabilities in Business Central.\nWhen working with attachments in agent tasks, be aware of the following capabilities and constraints.\n## Supported file types\nagents can process attachments with the following file types:\n PDF documents (.pdf) - Invoices, purchase orders, contracts, and reports\n Image files (.png, .jpg, .jpeg) - Scanned documents, receipts, and product images\n> NOTE\n> Be aware that agents only process text out of images and PDFs and not of the images themselves.\n## File size limits\nAttachments are subject to the standard file size limits in Business Central.\nIf you need to process large files:\n Consider splitting multi-page documents into smaller files\n Optimize PDF files by reducing image quality or removing embedded fonts\n Compress images before attaching\n Test with realistic file sizes during prototyping\n## PDF page limits\nWhen processing PDF documents, agents can handle up to 10 pages per document. This limit applies to document extraction and processing capabilities.\n### Considerations for multi-page PDFs\n Documents exceeding 10 pages might not be fully processed\n If you have documents with more than 10 pages, consider:\n   Splitting the document into smaller files (for example, by invoice or section)\n   Extracting only relevant pages before attaching\n   Processing the document in multiple tasks\n Test your document processing scenarios with typical document sizes during prototyping\n> NOTE\n> The 10-page limit addresses known limitations with multi-page PDF processing. Always test with representative documents to ensure your scenarios work within these constraints.\n### Process attachments with custom logic\nBy default, when you attach a file to an agent task, the agent processes it using built-in capabilities. However, you can implement custom document processing logic to extract specific fields or use specialized services.\n#### Use custom document analyzers\nIf you need to use a custom Azure AI Document Intelligence analyzer or other content understanding services, you can implement your own processing logic in AL to extract specific fields and pass only the relevant data to the agent:\n```al\nlocal procedure CreateTaskWithCustomProcessing()\nvar\n    AgentTaskBuilder: Codeunit \"Agent Task Builder\";\n    AgentTaskMessageBuilder: Codeunit \"Agent Task Message Builder\";\n    DocumentAnalyzer: Codeunit \"My Document Analyzer\"; // Your custom analyzer\n    TempBlob: Codeunit \"Temp Blob\";\n    InStr: InStream;\n    ExtractedData: Text;\nbegin\n    // Load your document\n    TempBlob.CreateInStream(InStr);\n\n    // Process with your custom analyzer to extract specific fields\n    ExtractedData := DocumentAnalyzer.ExtractInvoiceFields(InStr);\n\n    // Create task with only the extracted data - no need to attach the original file\n    // since the relevant information has already been extracted\n    AgentTaskMessageBuilder\n        .Initialize('Document Processing',\n            'Process invoice with the following extracted data: ' + ExtractedData);\n\n    AgentTaskBuilder\n        .Initialize(AgentUserSecurityId, 'Process Invoice')\n        .AddTaskMessage(AgentTaskMessageBuilder)\n        .Create();\nend;\n```\n> NOTE\n> When you extract data using custom document analyzers, you typically don't need to also attach the original file, as this would duplicate the information. Only attach the original document if you need it for reference, audit purposes, or if the agent needs to access additional context beyond the extracted fields.\nThis approach allows you to:\n Use Azure AI Document Intelligence with custom-trained models\n Extract only the specific fields relevant to your scenario\n Apply business logic before passing data to the agent\n Integrate with third-party document processing services\n Pre-validate document content before agent processing\n#### Example: Custom invoice processing\n```al\nlocal procedure ProcessVendorInvoiceWithCustomAnalyzer(InvoicePDF: InStream)\nvar\n    AgentTaskBuilder: Codeunit \"Agent Task Builder\";\n    AgentTaskMessageBuilder: Codeunit \"Agent Task Message Builder\";\n    AIDocIntelligence: Codeunit \"Azure AI Doc Intelligence\";\n    InvoiceData: JsonObject;\n    VendorName: Text;\n    InvoiceNumber: Text;\n    TotalAmount: Decimal;\n    TaskMessage: Text;\nbegin\n    // Use your custom Content Understanding connection\n    InvoiceData := AIDocIntelligence.AnalyzeInvoice(InvoicePDF, 'CustomInvoiceModel');\n\n    // Extract specific fields\n    VendorName := GetJsonValue(InvoiceData, 'VendorName');\n    InvoiceNumber := GetJsonValue(InvoiceData, 'InvoiceNumber');\n    TotalAmount := GetJsonDecimal(InvoiceData, 'TotalAmount');\n\n    // Create structured message for agent with extracted data\n    TaskMessage := StrSubstNo(\n        'Process vendor invoice:\\n' +\n        'Vendor: %1\\n' +\n        'Invoice No: %2\\n' +\n        'Amount: %3\\n' +\n        'Please validate and create purchase invoice.',\n        VendorName, InvoiceNumber, TotalAmount);\n\n    // Pass only the extracted data to the agent - no need for the original PDF\n    // since we've already extracted all relevant fields\n    AgentTaskMessageBuilder.Initialize('System', TaskMessage);\n\n    AgentTaskBuilder\n        .Initialize(AgentUserSecurityId, 'Vendor Invoice - ' + InvoiceNumber)\n        .SetExternalId('VINV-' + InvoiceNumber)\n        .AddTaskMessage(AgentTaskMessageBuilder)\n        .Create();\nend;\n```\n### Best practices for document processing\nFollow these best practices when working with document attachments:\n#### Choose the right approach\n Use attachments when you need the agent to understand document structure and context\n Use extracted data when you only need specific fields and want to control what the agent sees\n Combine both approaches by attaching the original document for reference while providing extracted data in the message\n#### Optimize documents for processing\n Keep PDFs within the 10-page limit - Split larger documents or extract relevant pages\n Use clear, high-quality scans - Ensure text is readable if using image-based PDFs\n Remove unnecessary pages - Cover pages, blank pages, or marketing materials can be excluded\n Test with real documents - Use actual invoices, purchase orders, or receipts from your business during prototyping\n#### Handle errors gracefully\n```al\nlocal procedure CreateTaskWithErrorHandling(DocumentStream: InStream; FileName: Text)\nvar\n    AgentTaskBuilder: Codeunit \"Agent Task Builder\";\n    AgentTaskMessageBuilder: Codeunit \"Agent Task Message Builder\";\nbegin\n    if not ValidateDocumentSize(DocumentStream) then\n        Error('Document exceeds maximum file size');\n\n    if not ValidateDocumentType(FileName) then\n        Error('Unsupported file type. Please use PDF, PNG, or JPG files');\n\n    // Proceed with task creation\n    AgentTaskMessageBuilder\n        .Initialize('User', 'Process this document')\n        .AddAttachment(FileName, GetMimeType(FileName), DocumentStream);\n\n    AgentTaskBuilder\n        .Initialize(AgentUserSecurityId, 'Process Document')\n        .AddTaskMessage(AgentTaskMessageBuilder)\n        .Create();\nend;\n```\n#### Provide context in instructions\nWhen agents process documents, include guidance in your agent instructions:\n Specify which fields to extract or validate\n Define how to handle missing or unclear information\n Explain business rules for document validation\n Indicate when to request human review\nExample instruction excerpt:\n```text\nWhen processing invoice attachments:\n1. Extract: Vendor name, invoice number, date, line items, and total amount\n2. Validate that the vendor exists in the system\n3. Check that line items match expected formats\n4. If any required field is missing or unclear, mark the task for manual review\n5. For invoices over $10,000, always request supervisor approval\n```\n## Related information\nOverview (preview)<https://learn.microsoft.com/dynamics365/business-central/dev-itpro/ai/ai-development-toolkit-landing-page>\nCreate and activate (preview)<ai-development-toolkit-agent-create>\nWrite effective instructions (preview)<ai-development-toolkit-instructions>\nInstruction keywords (preview)<ai-development-toolkit-instruction-keywords>\nIntegrate with the Tasks AL API (preview)<ai-development-toolkit-tasks-api>\nSet up permissions and profiles (preview)<ai-development-toolkit-permissions-profiles>\nRun an agent (preview)<ai-development-toolkit-run-agent>\nIterate and manage (preview)<ai-development-toolkit-iterate>\nFrequently asked questions (preview)<ai-development-toolkit-faq>\nBest practices for designing an agent (preview)<ai-development-toolkit-best-practices>\nCreate a Sales Validation Agent (preview)<ai-development-toolkit-sales-validation>\nTransparency note: Business Central AI development toolkit (preview)<transparency-note-ai-development-toolkit>"}