{"title":"Designing and coding agents (preview)","url":"https://jonas-paprotka.de/docs/dev-itpro/ai/ai-development-toolkit-overview/","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-overview, 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-overview","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":"Discover the AI Development Toolkit for testing AI capabilities in Business Central by building agents. Prototype, validate, and refine AI-powered solutions.","date":"2026-11-17","meta":{"topic":"concept-article"},"outline":[{"level":1,"title":"Designing and coding agents (preview)","slug":"designing-and-coding-agents-preview","at":0,"chars":8143},{"level":2,"title":"Purpose and audience","slug":"purpose-and-audience","at":882,"chars":883},{"level":2,"title":"When to use and when not to use","slug":"when-to-use-and-when-not-to-use","at":1765,"chars":781},{"level":3,"title":"When to use the AI development toolkit","slug":"when-to-use-the-ai-development-toolkit","at":1800,"chars":454},{"level":3,"title":"When not to use the AI development toolkit","slug":"when-not-to-use-the-ai-development-toolkit","at":2254,"chars":292},{"level":2,"title":"Agent lifecycle summary","slug":"agent-lifecycle-summary","at":2546,"chars":542},{"level":2,"title":"High-level concepts","slug":"high-level-concepts","at":3088,"chars":104},{"level":2,"title":"Prerequisites","slug":"prerequisites","at":3192,"chars":2535},{"level":3,"title":"Instructions and tasks","slug":"instructions-and-tasks","at":4019,"chars":705},{"level":3,"title":"Supported languages","slug":"supported-languages","at":4724,"chars":301},{"level":3,"title":"Permissions and profiles","slug":"permissions-and-profiles","at":5025,"chars":702},{"level":2,"title":"Limitations (preview)","slug":"limitations-preview","at":5727,"chars":921},{"level":3,"title":"Environment restrictions","slug":"environment-restrictions","at":5836,"chars":301},{"level":3,"title":"Operational constraints","slug":"operational-constraints","at":6137,"chars":511},{"level":2,"title":"Getting started","slug":"getting-started","at":6648,"chars":244},{"level":2,"title":"Related information","slug":"related-information","at":6892,"chars":1251}],"text":"# Designing and coding agents (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.\nThe Business Central AI development toolkit provides an environment that allows developers and partners to experiment with AI capabilities in Business Central by building agents.\n## Purpose and audience\nBuilding proof-of-concept agents is primarily designed for teams who want to prototype AI-powered capabilities by configuring agents. The ability to design agents is part of the AI development toolkit, which is intended for:\n Product owners who want to prototype AI-powered features before building them in AL extensions\n Domain experts evaluating AI integration possibilities for their Business Central solutions\n Consultants exploring automation scenarios with AI assistance for client solutions\n Developers validating AI use cases and gathering requirements for custom implementations\nBuilding and designing agents helps you understand how AI can interact with the Business Central user interface and data, which allows you to test various AI functionalities such as automating tasks, answering questions, and integrating AI into workflows through agents.\n## When to use and when not to use\n### When to use the AI development toolkit\nUse the AI development toolkit when you want to:\n Prototype AI features before investing in AL development\n Test AI interactions with Business Central UI and data\n Validate use cases and gather requirements for AI-powered solutions\n Experiment with prompts and AI behavior in a controlled environment\n Demonstrate AI capabilities to stakeholders or customers\n Learn AI integration patterns for Business Central\n### When not to use the AI development toolkit\nDon't use the AI development toolkit when:\n Compliance or security evaluation is the primary goal\n Final implementation is ready (graduate to AL extension instead)\n End-user training is the main objective (use production-ready Copilot features)\n## Agent lifecycle summary\nA typical agent follows this lifecycle:\n1. Create - Set up the agent with basic identity and profile\n1. Configure - Define instructions and permissions\n1. Activate - Enable the agent for testing, add tasks\n1. Iterate - Test, refine instructions, and adjust permissions\n1. Graduate - Export learnings to build production solutions using AL extensions\n1. Clean up - Deactivate and remove the prototype agent\nEach phase has specific requirements and limitations that guide your development process.\n![Agent lifecycle]\n## High-level concepts\nUnderstanding the following key concepts helps you work effectively with agents.\n## Prerequisites\nBefore you can design agents in Business Central, ensure that you have the following prerequisites in place:\n Enable the Custom Agent capability in Business Central. See Configure Copilot and agent capabilities</enable-ai>.\n Appropriate permissions to access and use the design capabilities in Business Central.\n   \"AGENT - ADMIN\" gives you permission to design agents.\n   \"AGENT - DIAGNOSTICS\" gives you access to see the execution cost and the serialized page in the agent task log entries.\n A sandbox environment for testing and experimentation from version 27.2 (can include customer data such as sandbox copies of production data).\n Billing setup for agent capabilities in your tenant. See Manage consumption billing for agents (preview)<../administration/tenant-admin-center-manage-consumption-billing>.\n### Instructions and tasks\nInstructions are natural language descriptions that define your agent's purpose and behavior. Think of them as detailed prompts that guide how the agent interprets requests and interacts with the Business Central interface. Well-written instructions include context, clear expectations, and specific guidance about the agent's role. See Write effective instructions for an agent (preview)<ai-development-toolkit-instructions>.\nTasks are a way to trigger the agent. Tasks can only be added when the agent is active, and they help structure how the agent responds to different types of requests. Learn more about tasks in Run an agent (preview)<ai-development-toolkit-run-agent>.\n### Supported languages\nThis feature currently supports only English as language. While this feature can be used in other languages, it might not function as intended. Language quality might vary based on the user's interaction or system settings, which might affect accuracy and the user experience.\n### Permissions and profiles\nThe agent operates with explicit permission sets that control what data and actions it can access. This follows the principle of least privilege; grant only the permissions necessary for the agent's intended functionality. The agent is assigned to a profile (role) that determines which UI elements it can see and interact with. To reduce contextual noise and increase accuracy, it's highly recommended to create custom profiles specifically for agents, using page customization properties to control visibility of actions, layouts, views, and operations like insert/delete.\nSee Set up agent permissions and profiles (preview)<ai-development-toolkit-permissions-profiles>.\n## Limitations (preview)\nAs a preview feature, the AI development toolkit has several important limitations:\n### Environment restrictions\n Sandbox only: Available exclusively in sandbox environments; never in production\n Sandbox data: Can be used with customer data in sandbox environments (including sandbox copies of production data)\n Preview functionality: Features and behavior might change without notice\n### Operational constraints\n Permission inheritance: Agents can't have more permissions than their creating user\n UI interaction limits: Agents see only what their assigned profile allows\n Single list per page: Agents can only interact with one list on any given page. If a page has multiple sublists (for example, sales lines and notes in a factbox), the agent can only access one of them\n No Tell me: Agents can't use Tell me to find specific information. Navigation is limited to available actions and links\n## Getting started\nReady to try to design an agent? The process involves enabling the feature, creating your agent, and configuring it for your specific use case. See Create and activate an agent (preview)<ai-development-toolkit-agent-create>.\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>\nAgent models (preview)<ai-agent-models>\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>\nBest practices for designing an agent (preview)<ai-development-toolkit-best-practices>\nCreate a Sales Validation Agent (preview)<ai-development-toolkit-sales-validation>\nEvaluate agents with Evaluation<../developer/ai-test-copilot-testtool>\nWrite agent tests<../developer/ai-test-copilot-agent-tests>\nTransparency note: Business Central AI development toolkit (preview)<transparency-note-ai-development-toolkit>"}