{"title":"Best practices for designing an agent (preview)","url":"https://jonas-paprotka.de/docs/dev-itpro/ai/ai-development-toolkit-best-practices/","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-best-practices, 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-best-practices","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":"Explore how to design, test, and refine agents using the AI development toolkit. Follow these best practices to optimize your prototypes.","date":"2026-10-02","meta":{"topic":"concept-article"},"outline":[{"level":1,"title":"Best practices for designing an agent (preview)","slug":"best-practices-for-designing-an-agent-preview","at":0,"chars":9527},{"level":2,"title":"Instructions best practices","slug":"instructions-best-practices","at":900,"chars":286},{"level":3,"title":"Write clear and specific instructions","slug":"write-clear-and-specific-instructions","at":931,"chars":255},{"level":2,"title":"Tasks best practices","slug":"tasks-best-practices","at":1186,"chars":1202},{"level":3,"title":"Define specific, measurable tasks","slug":"define-specific-measurable-tasks","at":1210,"chars":259},{"level":3,"title":"Limit task complexity","slug":"limit-task-complexity","at":1469,"chars":228},{"level":3,"title":"UI design","slug":"ui-design","at":1697,"chars":430},{"level":3,"title":"Structure task workflows","slug":"structure-task-workflows","at":2127,"chars":261},{"level":2,"title":"Permissions best practices","slug":"permissions-best-practices","at":2388,"chars":626},{"level":3,"title":"Apply least privilege principle","slug":"apply-least-privilege-principle","at":2418,"chars":236},{"level":3,"title":"Use custom profiles","slug":"use-custom-profiles","at":2654,"chars":227},{"level":3,"title":"Test permission boundaries","slug":"test-permission-boundaries","at":2881,"chars":133},{"level":2,"title":"Security and privacy best practices","slug":"security-and-privacy-best-practices","at":3014,"chars":1608},{"level":3,"title":"Protect sensitive information","slug":"protect-sensitive-information","at":3053,"chars":310},{"level":3,"title":"Control agent access","slug":"control-agent-access","at":3363,"chars":199},{"level":3,"title":"Data isolation","slug":"data-isolation","at":3562,"chars":708},{"level":3,"title":"Document and audit","slug":"document-and-audit","at":4270,"chars":352},{"level":2,"title":"Testing and validation best practices","slug":"testing-and-validation-best-practices","at":4622,"chars":1899},{"level":3,"title":"Systematic testing approach","slug":"systematic-testing-approach","at":4935,"chars":263},{"level":3,"title":"Accuracy testing","slug":"accuracy-testing","at":5198,"chars":469},{"level":3,"title":"User acceptance testing","slug":"user-acceptance-testing","at":5667,"chars":232},{"level":3,"title":"Red teaming","slug":"red-teaming","at":5899,"chars":325},{"level":3,"title":"Performance considerations","slug":"performance-considerations","at":6224,"chars":297},{"level":2,"title":"Common pitfalls to avoid","slug":"common-pitfalls-to-avoid","at":6521,"chars":1365},{"level":3,"title":"Instruction problems","slug":"instruction-problems","at":6549,"chars":609},{"level":3,"title":"Permission issues","slug":"permission-issues","at":7158,"chars":367},{"level":3,"title":"UI design problems","slug":"ui-design-problems","at":7525,"chars":131},{"level":3,"title":"Testing","slug":"testing","at":7656,"chars":230},{"level":2,"title":"Measuring success","slug":"measuring-success","at":7886,"chars":577},{"level":3,"title":"Key metrics to track","slug":"key-metrics-to-track","at":7907,"chars":307},{"level":3,"title":"Success indicators","slug":"success-indicators","at":8214,"chars":249},{"level":2,"title":"Related information","slug":"related-information","at":8463,"chars":1064}],"text":"# Best practices for designing an agent (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.\nFollowing these best practices helps you create agents and get better results from your designing efforts.\nSee AI development toolkit overview (preview)<ai-development-toolkit-overview>.\n## Instructions best practices\n### Write clear and specific instructions\nEffective agent instructions are specific, actionable, and contextual. Instructions are key to guiding agent behavior. See Write effective instructions for an agent (preview)<ai-development-toolkit-instructions>.\n## Tasks best practices\n### Define specific, measurable tasks\nCreate tasks that have clear success criteria:\n Good: \"Generate a summary report of overdue invoices for customers with credit limits over $10,000\"\n Poor: \"Get the overdue invoices for customers with large credit limits\"\n### Limit task complexity\n Keep individual tasks focused on single objectives\n Break complex workflows into multiple tasks\n Consider the agent's UI access limitations - determined by their profile.\n Test each task independently\n### UI design\n The fewer elements that the agent needs to consider, the more accurate it is\n Ensure that tooltips on relevant actions are descriptive enough for human and agent users\n Hide unrelated elements that might confuse the agent during testing\n Consider navigation shortcuts for your agent like adding links to the relevant pages to its role center\n Fewer navigation steps lead to a more cost-effective and accurate agent\n### Structure task workflows\n Design tasks that can work together logically\n Consider task dependencies and sequencing\n Plan for error handling and fallback scenarios\nSee Write effective instructions for an agent (preview)<ai-development-toolkit-instructions>.\n## Permissions best practices\n### Apply least privilege principle\n Grant only the minimum permissions needed for the agent's tasks\n Regularly review and audit agent permissions\n Remove permissions that aren't actively used\n Document why each permission is necessary\n### Use custom profiles\nCreate agent-specific profiles that:\n Limit UI exposure to relevant pages only\n Remove unnecessary actions and views\n Simplify layouts to reduce complexity\n Use page customization properties effectively\n### Test permission boundaries\n Verify that the agent can't access restricted data\n Confirm that permission changes work as expected\n## Security and privacy best practices\n### Protect sensitive information\n Be cautious with sensitive data in agent instructions and configurations\n Ensure that the agent can access only data that's relevant to its task\n Consider data privacy implications when testing with customer data\n Document data handling practices for compliance requirements\n### Control agent access\n Limit which users can interact with the agent\n Monitor agent activity through task log entries\n Regularly review user access lists\n Deactivate agents when not in active use\n### Data isolation\nWhen an agent's output is used for external communication, it's necessary to test that the outputs don't expose unrelated data.\nFor example, if an agent answers to email queries about product prices, it's vital to test that it doesn't reveal internal details that would otherwise be\nunavailable to the external customer like the wholesale acquisition cost of the product.\n Ensure that the agent's profile covers only the necessary elements for its task\n Always perform a human review of the output messages of agents if they interact with external customers\n If necessary, design agent specific pages or AL event subscribers, which filter the data to what the agent is supposed to process\n### Document and audit\n Keep records of agent configurations and changes\n Document the business purpose for each agent. Ensure the description of the agent clearly describes its function.\n Track who has access and why\n Plan for agent cleanup and removal\nSee Set up agent permissions and profiles (preview)<ai-development-toolkit-permissions-profiles>.\n## Testing and validation best practices\nIt's highly recommended to define and complete your testing plan in a sandbox environment before deploying an agent to production. Because agents are non-deterministic, testing is the only reliable way to validate that they behave as intended across a range of scenarios.\n### Systematic testing approach\n Test with various input types and formats\n Include edge cases and error conditions, including typos and common human errors\n Validate responses for accuracy and completeness\n Check that the agent follows instructions consistently\n### Accuracy testing\n Create scenarios with easily verifiable acceptance criteria - for example, 'a new sales order with a single bicycle should be added'\n Generate many variations through real business cases or via LLM powered tools, ensure consistency of outputs\n Ensure the agent can recover from common error scenarios, like field validations during data entry\n Include scenarios where the agent failed during development as test cases to ensure it doesn't regress\n### User acceptance testing\n Have business users test realistic scenarios\n Gather feedback on response quality and usefulness\n Validate that the agent meets business requirements\n Test with users who weren't involved in development\n### Red teaming\n Try to ask your agent about pages/fields it shouldn't have access to\n Ask your agent to infer information about the business that it shouldn't have access to\n Request your agent to perform actions that shouldn't be valid for your scenario, for example, to set the price of a product to zero and then sell it\n### Performance considerations\n Monitor the number of steps and the total credit cost of your test tasks\n Test on realistic data volumes to ensure that your agent can handle the complexity of the task\n Optimize for the minimum number of steps as longer workflows can reduce the accuracy of agents\n## Common pitfalls to avoid\n### Instruction problems\n Overly vague instructions lead to inconsistent behavior\n Too many instructions can confuse the agent\n Contradictory requirements create unpredictable results\n Missing context results in poor decision-making\n Specific tool references can lead to regressions if they get renamed. Refer to what the agent should do, not which tool to use\n Ambiguous instructions can cause erratic behavior as they might be interpreted either way on every run\n Safety filters can be triggered if the instructions are treated as a jailbreak attempt. Refactor the instructions to avoid any false positives\n### Permission issues\n Unnecessary agent permissions can allow agents to modify data they shouldn't\n The intersection of the assigning user's permissions and the agent permissions should be enough to perform all of its functions\n Agents can't configure users or other agents by design\n Agents can't access sensitive pages like user cards or permission set assignment\n### UI design problems\n Limit the UI either via profiles or pages designed specifically for your agent to help it achieve its task\n### Testing\n Agents are non-deterministic so testing is the only way to validate they do what they're designed to do\n Testing only happy paths misses important edge cases\n Skipping documentation makes knowledge transfer difficult\n## Measuring success\n### Key metrics to track\n Task completion rate: How often the agent successfully completes requested tasks\n Response accuracy: Quality and correctness of agent responses\n User satisfaction: Feedback from test users about agent usefulness\n Error frequency: How often the agent encounters errors or confusion\n### Success indicators\n Users can accomplish their goals through agent interaction\n Agent responses are consistent and reliable\n Instructions and tasks work across different scenarios\n The prototype validates the business case for AI implementation\n## Related information\nOverview (preview)<https://learn.microsoft.com/dynamics365/business-central/dev-itpro/ai/ai-development-toolkit-landing-page>\nDesigning and coding agents (preview)<ai-development-toolkit-overview>\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>\nAttachment capabilities and limitations (preview)<ai-development-toolkit-attachments>\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>\nCreate a Sales Validation Agent (preview)<ai-development-toolkit-sales-validation>\nTransparency note: Business Central AI development toolkit (preview)<transparency-note-ai-development-toolkit>"}