Coding agents in AL

Path: Integration with AI > Designing and coding agents (preview) > Coding agents in AL · tier official · system development · narrative reviewed (checked by Opus)

Overview

This section is for developers who want to write an agent in AL instead of only using the design experience. It explains the core interfaces (IAgentFactory, IAgentMetadata, IAgentTaskExecution), how to register an agent through the Agent Metadata Provider enum and the Copilot capability, and how to give it a setup experience.

The pages fit together as a build sequence. Start with the overview page, which has a quick-start template. Then define and register the agent, create the setup page with the ConfigurationDialog page type and Agent Setup Part, and configure instances with the Agent codeunit (instructions, display name, profile, localization, archiving). Managing agent tasks covers creating tasks from page actions, business events and email triggers, plus attachments and lifecycle.

If you already prototyped an agent in the design experience, use the convert page to export its settings and package them in an AL app. The AI models page explains model selection and resolution for agents created either way. All pages are marked preview.

Key points

• Custom agents are built by extending the Agent Metadata Provider enum and implementing IAgentFactory, IAgentMetadata and IAgentTaskExecution, and by registering the Copilot capability.
• The overview page includes a quick-start template and guidance on setup pages, task lifecycle, attachments and cross-agent operations. It mentions versions 27.4 and 28.1.
• Setup pages use the ConfigurationDialog page type, a modal dialog with OK and Cancel system actions, a Content area, temporary data sources and AgentSetupPart.
• Setup pages should make changes reversible, track changes, and persist custom configuration fields.
• The Agent codeunit configures instances programmatically: Archive, IsArchived, SetInstructions, SetDisplayName, SetProfile and UpdateLocalizationSettings.
• Agent tasks can be created from page actions, business events and email triggers, with attachments, message tracking and external ID tracking. The tasks page mentions version 28.1.
• Converting a prototyped agent to AL means exporting its settings, then implementing instructions, permission sets, default profile, agent user settings, localization settings and triggering logic.
• The AI models page covers auto model selection, model lifecycle, and the resolution order between agent-level and task-level models.

Learn pages

• AI Models for Agents (preview): Learn about AI model availability, lifecycle, and how to select models for agents in Dynamics 365 Business Central.
• Coding agents in AL (preview): Learn about the development tools for building AI agents in Dynamics 365 Business Central.
• Configure agents programmatically (preview): Learn how to configure agent instances, manage lifecycle settings, and update agent instructions programmatically in Dynamics 365 Business Central.
• Convert an agent to AL code (preview): Learn how to convert an agent created in Business Central to an agent defined in AL code for distribution in an AL application.
• Create agent setup pages (preview): Learn how to create setup pages for agents in Dynamics 365 Business Central using the ConfigurationDialog page type.
• Define and register an agent programmatically (preview): Learn how to define and register AI agents programmatically in Dynamics 365 Business Central using the AI development toolkit.
• Managing agent tasks programmatically (preview): Learn how to create and manage agent tasks, work with agent sessions, and handle cross-agent operations in Dynamics 365 Business Central.
• The ConfigurationDialog Page Type (preview): Learn how to use the ConfigurationDialog page type to create focused configuration dialogs for managing agent settings in Dynamics 365 Business Central.

Videos, posts and code changes

Linked by a Haiku matcher with a grounding quote from the item’s summary (link/topics.ts); machine-generated.

• #10007 [SOA] Ignore item availability when disabled (code change): “The Sales Order Agent now ignores item availability signals when availability checking is disabled”
• #10008 [MCP] Add codeunit APIs as MCP tools in MCP configuration (code change): “Add codeunit APIs as MCP tools in MCP configuration”
• #10017 [Master] - Bug 644751 Moving an expense report line to another report wrongly reports a duplicate (code change): “Moving an expense report line to another report wrongly reports a duplicate”
• #10020 [Master] - Bug 641894: [Expense Agent] [Rules] Mileage expense should not validate require receipt number rule (code change): “Mileage expenses in Expense Agent no longer incorrectly trigger the receipt number mandatory validation”
• #10022 Known senders table should only be inserted to when the task is coming from an email (code change): “The Known Senders table now only gets populated when tasks arrive from email”
• #10031 Add AI-assisted policy evaluation backend to Expense Agent (code change): “Add AI-assisted policy evaluation backend to Expense Agent”
• #10036 [SOA]: Bugbash for releases 28.x - Contact unable to find due to Qasim map to Megan, different names (code change): “Fixes Sales Order Agent contact lookup and reply routing when a sender’s email is mapped”
• #10084 Let the agent update invoice due dates on user instructions (code change): “Let the agent update invoice due dates on user instructions”
• #10101 [Master] [Expense Agent] Bug 641393 [AT] Recognize International Standard Code 1A as mileage UOM (code change): “Recognize International Standard Code 1A as mileage UOM”
• #10155 Slice 641293: [Expense Agent] Expense Locations and Per-diem rules in configurationAdded more locations (code change): “Expense Agent now includes comprehensive expense locations for all country/regions”
• #10232 Block unauthorized Sales Order Agent setup access (code change): “The SOA Setup page now validates user permissions before allowing access to Sales Order Agent configuration”
• #10238 Remove consumed credits from Payables Agent setup (code change): “Remove consumed credits from Payables Agent setup”
• #10253 Avoid starting a write transaction under ShowCanCreateAgent (code change): “Payables Agent Setup no longer starts a write transaction”
• #10287 Move SOA item search and attachment extraction to GPT-5.5 deployments (code change): “Sales Order Agent AI operations move to GPT-5.5 chat deployments”
• #10294 [SOA] Fix missing Agent Task Message read permission in contact search (code change): “Sales Order Agent to complete contact-mapping flows without permission intervention”
• #10308 Uptake agent archiving in Sales Order Agent (AB#644549) (code change): “Uptake agent archiving in Sales Order Agent”
• #10312 Update expense VAT specification source (code change): “Expense Agent now sets the Source of VAT specification records”
• #10346 Fix activity log indirect permissions (code change): “The Expense Agent and Expense Management permission sets now grant indirect permissions”
• #10411 [SOA] Allow changing or clearing manually selected contacts (code change): “Users can now select, change, or clear manually chosen contacts in the Sales Order Agent”
• #10418 [SOA] Ignore extended-text lines when editing sales quotes (code change): “Sales Order Agent now filters out extended-text lines from the sales quote view”
• #10432 [MCP] Change System Tool factbox caption to ‘Active System Tools’ (code change): “The caption of the MCP System Tool List factbox page has been updated”
• #10515 [Payables Agent] Fix stale Payables Agent setup save (code change): “Payables Agent Setup now persists instruction updates in a single final modification”
• #10519 SOA - Try it out : agent activation after closing the page (code change): “Sales Order Agent now activates only after a task is submitted”
• #10542 [Master] - Slice 638097: [Expense Agent] Enable simple interim approval scenario (code change): “Expense reports now support a two-stage approval flow with interim and final approvers”
• #10564 Bug 641415: [Expense Agent] Incorrect Payment Method Assignment for Card-Based Expenses (code change): “Payment method descriptions in the Expense Agent setup are now more descriptive”
• #10567 SOA : Create Task from TaskPane respects review configuration for known senders (code change): “Tasks created manually in the SOA Create Task pane now respect the review configuration”
• #10568 Send sample invoices from the demo guide directly (code change): “Payables Agent demo guide now sends sample invoices immediately when selecting”
• #10603 [Expense Agent] Grant policy builder execute permission (code change): “Expense Management roles now have execute permission on the policy builder codeunit”
• #10825 [Master]-Bug 645041: Expense Agent - Rename Enable approval workflow caption and tooltip (code change): “Expense Agent Setup page renamed the approval workflow toggle”
• #10829 [29.x][Expense Agent] Backport approval conversation from #10570 (code change): “Expense Agent now supports approval conversations, allowing submitters to add comments”
• #10842 [SOA] Clarify Email 2 contact mapping action (code change): “Sales Order Agent now explicitly clarifies that the sender’s email is stored”
• #10890 [Master] Bug 645040: Expense Agent: BC Approval Workflow - Improve error message when Approval User Setup is missing (code change): “Expense approval workflow now shows a clear, actionable error”
• #10914 [Expense Agent] Fix setup API language permission (code change): “Expense Agent permission set now grants indirect read access to the Agent table”
• #10956 [ExpenseAgent] Refactor agent setup for policies (code change): “Expense Agent administrators can now disallow users from running policy checks”
• #10965 Fix Expense Agent VAT tests (code change): “Fixes the Expense Agent VAT tests”
• #10986 [29x] Fix Expense Agent VAT tests (code change): “Fixed VAT test failures in the Expense Agent API”
• #10990 Add-Expense-VAT-settings-to-Contoso-demo-tool (code change): “Expense Agent Contoso demo data now includes expense VAT settings”
• #11004 Fix Expense Report Reimbursement Currency Code (code change): “reimbursement currency code handling in the Create Expense Report codeunit”
• #11007 Add Travel Request API lifecycle to Expense Agent (code change): “Travel Request API lifecycle management is integrated into the Expense Agent”
• #11021 Expense Agent: align legacy submit cleanup with 29.0 (code change): “Expense Agent’s legacy submit action cleanup lifecycle”
• #11027 [Master]-Bug 648538: Add mileage setup to Expense Agent wizard (code change): “Expense Agent setup wizard now includes mileage configuration”
• #11068 SOA: Clear previous search filter (code change): “Fixes search behavior in Sales Order Agent”
• #11207 [Master]-Bug 648672: [Expense Agent][Translation] Agent name is not localized across setup wizard, avatar, and Agent Card (code change): “The Expense Agent name is now localized across the setup wizard”
• #11213 Fix sample invoice email when the agent setup is not saved yet (code change): “The payables agent demo guide now receives the setup configuration”
• #11290 [Bug 640454] Scope Expense Agent Entra permissions by company (code change): “Expense Agent now manages Microsoft Entra permissions scoped to individual companies”
• #11333 Align travel request APIs with employee travelers and expense report lifecycle (code change): “Expense Agent APIs now align travel request and expense report workflows”
• #11375 Obsolete GPT-5.5 chat and add GPT-5.6 Ceres deployments (code change): “Sales Order Agent attachment extraction and item search now use them”
• #11381 Slice 641293: [Expense Agent] Expense Locations and Per-diem rules in configuration - added check for existing country (code change): “Expense Agent setup now skips creating expense locations for country and currency codes that do not exist”
• #11383 [SOA] Fix “The Order Promising Setup does not exist.” crash when setting quote quantity (code change): “The Sales Order Agent now handles missing Order Promising Setup gracefully”
• #11420 [Master] - [Expense Management] Hide Enable Agent on Expense Agent Setup Page (code change): “Hide Enable Agent on Expense Agent Setup Page”
• #11425 Bug 650137: [29.x] Expense Locations and Per-diem rules in configuration - Backport (code change): “adds more expense locations and per-diem rules to the Expense Agent’s default and demo data”
• #11431 [Master] - [Expense Management] Move missing Employee Posting Group validation to rule violation (code change): “The Expense Agent now validates Employee Posting Group through rule violations”
• #11441 Fixes AB#640874: Clarify Expense Agent scheduling permission error (code change): “The Expense Agent scheduler authorization error message is now clearer”
• #11481 [Master] - Bug 648681: [Expense Agent] Fix Expense Agent KPI report-line drill-down filter (code change): “Expense Agent KPI drill-down filter now correctly shows”
• #11541 Clarify Expense Agent and expense management setup (code change): “Clarify Expense Agent and expense management setup”
• #11593 [29.x] - Bug 650481[Expense Agent] Closed travel requests are editable and are missing approver info. (code change): “Travel requests can no longer be edited once closed automatic”
• #11595 [Master] Bug 650348: [Expense Agent] Closed travel requests are editable and are missing approver info. (code change): “Closed travel requests become read-only to prevent accidental modifications”
• #11628 Expense Agent: capture submission policy evaluation history (code change): “Expense Agent now captures policy evaluation history at the report level”
• #11639 [Master] - Slice 640938: [Expense Agent][VENDOR] Adding approval limits (November ’26) (code change): “The Expense Agent gains approval limits. New fields on User Setup and Expense User”
• #11770 [Master] - Bug 650783: [Expense Agent][Demo Data] Posted demo expenses remain Submitted with a dangling Expense Report No. (code change): “Fixes posted Expense Agent demo expenses that stayed in Submitted status”
• #11813 Bug 633676: Expense Agent - Setup wizard - Cannot clear default approver once saved from assist edit (code change): “The Expense Agent Setup Wizard now allows users to clear the default approver”
• #11832 [Master] - Bug 651133: [Expense Agent][BugBash] Mileage setup (code change): “Fixes a bug-bash issue with mileage setup in the Expense Agent”
• #11889 [Master] - Bug 651129: Expense Agent - Distance UOM in Configuration (code change): “Expense Agent setup now includes distance unit of measure configuration”
• #11970 Allow Azure OpenAI privacy notice in evaluation (code change): “Azure OpenAI privacy notice assumed approved in evaluation”
• #12074 Expense Agent: travel request expense location, per-traveler reports, activity log and submitter comment (code change): “Expense Agent travel request feature now supports expense location selection using per diem rules”
• #7546 [Payables Agent] Agent-driven line matching (code change): “Adds agent-driven line matching to the Payables Agent”
• #8875 [master] SOA: Bugbash for releases 28.x - Select an existing contact, or create a new one - Use another contact always (code change): “Sales Order Agent by adding a commit before opening the contact selection”
• #9310 SOA: Open Item Availability from Agent panel (code change): “The Sales Order Agent can now open the multi-item availability page”
• #9364 Slice 622414: [SOA] [Pioneer] Enhancing Sales Order Agent with Item Variant : availability and prices (code change): “The Sales Order Agent now resolves customer requests to a specific item variant”
• #9365 [SOA] Prevent translated username token and remove dead GetAgent helpers (code change): “Sales Order Agent usernames are now prevented from being translated by marking the label as locked”
• #9541 [SOA] Bound outbound reply retries (code change): “Outbound replies in the Sales Order Agent now limit retry attempts to five per message”
• #9606 [SOA] Disable available-items-only search by default (code change): “The Sales Order Agent now initializes the Search Only Available Items setting”
• #9635 Obsolete MLLM Payables Agent rollout scaffold (code change): “MLLM processing is now the permanent behavior for the Payables Agent feature”
• #9693 Rename email review option ‘Only untrusted senders’ to ‘Manage per sender’ (code change): “Caption of enum option OnlyIfUntrusted changed to ’Manage per sender”
• #9708 Enable manual task creation for Sales Order Agent (code change): “The Sales Order Agent now allows users to manually create tasks directly”
• #9805 Update Email Folder tooltip to reference renamed ‘Manage per sender’ review option (code change): “Payables Agent strings are updated to reference the renamed email review option”
• #9859 [Master] - Move Expense Agent (Preview) app into BCApps (code change): “The Expense Agent (Preview) app source is moved into BCApps as a W1 app”
• #9904 Let the agent see and set vendor posting groups and CIF or NIF (code change): “The payables agent can now see and set vendor posting groups”
• #9988 [Expense Agent] Fix Employee subscriber permissions (code change): “Expense Agent Employee event subscribers so they can sync and delete”
• #9989 [SOA] Skip Item Selector for exact items without variants (code change): “The Sales Order Agent no longer calls the Item Selector”
• #137 Add community guidance and review support for Business Central agents (code change): “Each rule includes documentation and contrasting AL code examples”
• #174 Make BCQuality documentation easier for partners to get started (code change): “Community Agents review extended with folder-path support”
• #176 Complete partner contribution and knowledge consumption guides (code change): “consuming skills in custom agents, with clarifications on metadata, integration”
• #182 Add machine-readable review orchestration contract (code change): “Enables BC-ALAgents to consume a stable, mechanically-owned orchestration contract”
• Step-by-Step Guide: Create Agents in AL Code (community post): “Building agents in Business Central AL involves creating setup tables, pages, codeunits”
• Agents in Business Central – part 5 – Creating agent from code (community post): “create, configure, and register agents programmatically in Business Central using AL code”
• Dynamics 365 Business Central: debugging agent sessions. (community post): “AL Language extension runtime 17.0 introduces debugging support for agent sessions in Business Central”
• What’s New: Coding Business Central Agents with AI Development Toolkit (video): “Coding Business Central Agents with AI Development Toolkit; Agent Type Definition; Agent Factory Interface”
• Microsoft presents: Building and shipping agents in Business Central (video): “Building and shipping agents in Business Central; agent configuration; permissions”

Source: Microsoft Learn (CC BY 4.0). Descriptions are Learn’s own.