{"title":"Create agent setup pages (preview)","url":"https://jonas-paprotka.de/docs/dev-itpro/ai/ai-agent-sdk-setup-page/","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-agent-sdk-setup-page, 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-agent-sdk-setup-page","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 how to create setup pages for agents in Dynamics 365 Business Central using the ConfigurationDialog page type.","date":"2026-10-02","meta":{"topic":"how-to"},"outline":[{"level":1,"title":"Create agent setup pages (preview)","slug":"create-agent-setup-pages-preview","at":0,"chars":13604},{"level":2,"title":"Creating a setup page","slug":"creating-a-setup-page","at":1003,"chars":4296},{"level":2,"title":"Enabling reversible changes","slug":"enabling-reversible-changes","at":5299,"chars":1416},{"level":3,"title":"How it works","slug":"how-it-works","at":5559,"chars":1156},{"level":2,"title":"Modifying Agent Setup Part properties","slug":"modifying-agent-setup-part-properties","at":6715,"chars":1538},{"level":2,"title":"Implement the setup logic","slug":"implement-the-setup-logic","at":8253,"chars":3276},{"level":3,"title":"Initializing the setup record","slug":"initializing-the-setup-record","at":8599,"chars":1391},{"level":3,"title":"Saving the setup record","slug":"saving-the-setup-record","at":9990,"chars":904},{"level":3,"title":"Saving custom properties","slug":"saving-custom-properties","at":10894,"chars":635},{"level":2,"title":"Using the Agent Setup codeunit","slug":"using-the-agent-setup-codeunit","at":11529,"chars":1054},{"level":3,"title":"Key methods","slug":"key-methods","at":11822,"chars":355},{"level":3,"title":"UI helpers for configuration pages","slug":"ui-helpers-for-configuration-pages","at":12177,"chars":406},{"level":2,"title":"Setup page design considerations","slug":"setup-page-design-considerations","at":12583,"chars":624},{"level":2,"title":"Related information","slug":"related-information","at":13207,"chars":397}],"text":"# Create agent setup pages (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.\nThis article explains how to create setup pages for your agents using the ConfigurationDialog page type. Setup pages provide a user interface for configuring agent instances, allowing users to customize agent-specific settings while using the built-in `Agent Setup Part` for common agent configuration.\n## Creating a setup page\nTo provide a user interface for configuring agent instances, create a setup page using the ConfigurationDialog page type. This page allows users to configure agent-specific settings while using the built-in `Agent Setup Part` for common agent configuration.\nThe setup page typically includes:\n Agent Setup Part: A standard part that handles common agent configuration including name, display name, state, and access control settings.\n Custom configuration fields: Agent-specific settings stored in a dedicated setup table\n System actions: An Update button to save changes and a Cancel button to discard them\n Initialization logic: Code to initialize the setup record and handle saving on close\n```al\npage 50100 \"My Agent Setup\"\n{\n    PageType = ConfigurationDialog;\n    Caption = 'Set up my agent';\n    SourceTable = \"My Agent Setup\";\n    SourceTableTemporary = true;\n\n    layout\n    {\n        area(Content)\n        {\n            // Standard agent configuration UI\n            part(AgentSetupPart; \"Agent Setup Part\")\n            {\n                ApplicationArea = All;\n                UpdatePropagation = Both;\n            }\n\n            // Custom agent-specific settings\n            group(AdditionalConfiguration)\n            {\n                Caption = 'Additional Configuration';\n\n                field(CustomProperty; Rec.\"Custom Property\")\n                {\n                    ApplicationArea = All;\n                    ToolTip = 'Specifies a custom property for agent-specific configuration.';\n\n                    trigger OnValidate()\n                    begin\n                        IsUpdated := true;\n                    end;\n                }\n            }\n        }\n    }\n\n    actions\n    {\n        area(SystemActions)\n        {\n            systemaction(OK)\n            {\n                Caption = 'Update';\n                Enabled = IsUpdated;\n                ToolTip = 'Apply the changes to the agent setup.';\n            }\n            systemaction(Cancel)\n            {\n                Caption = 'Cancel';\n                ToolTip = 'Discards the changes and closes the setup page.';\n            }\n        }\n    }\n\n    trigger OnOpenPage()\n    begin\n        InitializePage();\n    end;\n\n    trigger OnAfterGetRecord()\n    begin\n        InitializePage();\n    end;\n\n    trigger OnQueryClosePage(CloseAction: Action): Boolean\n    begin\n        if CloseAction = CloseAction::Cancel then\n            exit(true);\n\n        // Get the updated buffer from the setup part\n        CurrPage.AgentSetupPart.Page.GetAgentSetupBuffer(AgentSetupBuffer);\n\n        // Save the agent configuration and custom properties\n        SaveSetupRecord(Rec, AgentSetupBuffer);\n        SaveCustomProperties(Rec);\n\n        exit(true);\n    end;\n\n    local procedure InitializePage()\n    begin\n        // Get the current buffer from the setup part\n        CurrPage.AgentSetupPart.Page.GetAgentSetupBuffer(AgentSetupBuffer);\n\n        // Initialize the setup record and buffer\n        InitializeSetupRecord(Rec, AgentSetupBuffer);\n\n        // Pass the initialized buffer back to the setup part\n        CurrPage.AgentSetupPart.Page.SetAgentSetupBuffer(AgentSetupBuffer);\n\n        // Sync the update state\n        IsUpdated := CurrPage.AgentSetupPart.Page.GetChangesMade();\n    end;\n\n    // See the 'Implement the setup logic' section for the implementation\n    // of InitializeSetupRecord, SaveSetupRecord, and SaveCustomProperties procedures.\n\n    var\n        AgentSetupBuffer: Record \"Agent Setup Buffer\";\n        IsUpdated: Boolean;\n}\n```\nCreate a corresponding table to store agent-specific configuration. The table uses the agent's User Security ID as the primary key to link configuration to each agent instance:\n```al\ntable 50100 \"My Agent Setup\"\n{\n    DataClassification = CustomerContent;\n\n    fields\n    {\n        field(1; \"User Security ID\"; Guid)\n        {\n            Caption = 'User Security ID';\n        }\n        field(10; \"Custom Property\"; Text[100])\n        {\n            Caption = 'Custom Property';\n        }\n    }\n    keys\n    {\n        key(Key1; \"User Security ID\")\n        {\n            Clustered = true;\n        }\n    }\n}\n```\nLearn more about configuration dialogs in The ConfigurationDialog page type (preview)<../developer/devenv-page-type-configuration-dialog>.\n## Enabling reversible changes\nThe setup page is designed to allow users to make changes and preview them without committing to the database. This provides a safe editing experience where users can cancel at any time without persisting unwanted modifications.\n### How it works\n1. Draft-like editing: The page uses a temporary source table (`SourceTableTemporary = true`), meaning all edits are made to an in-memory record that isn't automatically saved to the database.\n2. Change tracking with IsUpdated: A boolean variable IsUpdated tracks whether any modifications have been made. This variable:\n  Enables the Update button only when changes exist\n  Gets set to true when fields are modified\n  Signals that the user has made edits that need to be confirmed or discarded\n3. Explicit commit on Update: When the user selects Update:\n  The OnQueryClosePage trigger saves the changes to the actual database\n  Agent configuration is persisted through the `Agent Setup` codeunit\n  Custom properties are written to your setup table\n4. Automatic revert on Cancel: When the user selects Cancel:\n  All changes are automatically discarded\n  No database writes occur\n  The user's session ends without any modifications being saved\nCustom setup pages should be designed with this pattern in mind. It's important to ensure that errors in the setup page don't commit partial data as that would circumvent the users' expectations.\n## Modifying Agent Setup Part properties\nYou can programmatically update properties in the Agent Setup Part from your custom fields or logic. This is useful when you want to synchronize custom fields with standard agent properties like display name or state.\nTo update properties in the Agent Setup Part:\n1. Get the current buffer from the part\n2. Modify the buffer fields\n3. Set the updated buffer back to the part\n4. Mark that changes have been made\nThe following example shows how to update the display name when a custom field changes:\n```al\nfield(DisplayName; AgentDisplayName)\n{\n    Caption = 'Display Name';\n    ApplicationArea = All;\n    ToolTip = 'Specifies the display name of the agent.';\n\n    trigger OnValidate()\n    begin\n        // Get the current buffer from the setup part\n        CurrPage.AgentSetupPart.Page.GetAgentSetupBuffer(AgentSetupBuffer);\n\n        // Update the display name in the buffer\n        AgentSetupBuffer.\"Display Name\" := AgentDisplayName;\n        AgentSetupBuffer.Modify(true);\n\n        // Pass the updated buffer back to the setup part\n        CurrPage.AgentSetupPart.Page.SetAgentSetupBuffer(AgentSetupBuffer);\n        CurrPage.AgentSetupPart.Page.Update(false);\n\n        // Mark that changes have been made to enable the Update button\n        IsUpdated := true;\n    end;\n}\n```\nYou can update other properties in the `Agent Setup Buffer` such as:\n State: Set AgentSetupBuffer.State to activate or deactivate the agent\n Display Name: Set `AgentSetupBuffer.\"Display Name\"` to change the visible name\n## Implement the setup logic\nThe setup page shown above calls helper procedures to manage initialization and saving. These procedures work with the `Agent Setup` codeunit from the system to manage agent configuration.\nThese procedures should ideally be implemented in a separate codeunit, but they're shown inline here for ease of understanding.\n### Initializing the setup record\nInitialize the setup record to prepare the page for display. For new agents, set default values. For existing agents, load the current configuration from the database.\n```al\nlocal procedure InitializeSetupRecord(var TempMyAgentSetup: Record \"My Agent Setup\" temporary; var AgentSetupBuffer: Record \"Agent Setup Buffer\")\nvar\n    MyAgentSetupRecord: Record \"My Agent Setup\";\n    AgentSetup: Codeunit \"Agent Setup\";\nbegin\n    // For new agents, set default values for custom properties\n    // For existing agents, load current configuration\n    if IsNullGuid(TempMyAgentSetup.\"User Security ID\") then\n        TempMyAgentSetup.\"Custom Property\" := 'Default Value'\n    else\n        if MyAgentSetupRecord.Get(TempMyAgentSetup.\"User Security ID\") then\n            TempMyAgentSetup.TransferFields(MyAgentSetupRecord, false);\n\n    if TempMyAgentSetup.IsEmpty() then\n        TempMyAgentSetup.Insert();\n\n    // Initialize the Agent Setup Buffer with agent metadata\n    if AgentSetupBuffer.IsEmpty() then\n        AgentSetup.GetSetupRecord(\n            AgentSetupBuffer,\n            TempMyAgentSetup.\"User Security ID\",\n            Enum::\"Agent Metadata Provider\"::\"My Agent\",\n            'My Agent - ' + CompanyName(),  // Agent name\n            'My Agent',                      // Display name\n            'Description of what this agent does.');  // Summary\nend;\n```\n### Saving the setup record\nSave the agent configuration when the user selects Update. Use the `Agent Setup` codeunit to persist the agent settings and set instructions for new agents.\n```al\nlocal procedure SaveSetupRecord(var TempMyAgentSetup: Record \"My Agent Setup\" temporary; var AgentSetupBuffer: Record \"Agent Setup Buffer\")\nvar\n    AgentSetup: Codeunit \"Agent Setup\";\n    Agent: Codeunit Agent;\n    IsNewAgent: Boolean;\nbegin\n    IsNewAgent := IsNullGuid(AgentSetupBuffer.\"User Security ID\");\n\n    // Save the agent configuration using the Agent Setup codeunit\n    if AgentSetup.GetChangesMade(AgentSetupBuffer) then begin\n        TempMyAgentSetup.\"User Security ID\" := AgentSetup.SaveChanges(AgentSetupBuffer);\n\n        // For new agents, set the instructions\n        if IsNewAgent then\n            Agent.SetInstructions(TempMyAgentSetup.\"User Security ID\", GetInstructions());\n    end;\nend;\n```\n### Saving custom properties\nSave any agent-specific custom properties to your setup table.\n```al\nlocal procedure SaveCustomProperties(var TempMyAgentSetup: Record \"My Agent Setup\" temporary)\nvar\n    MyAgentSetupRecord: Record \"My Agent Setup\";\nbegin\n    if not MyAgentSetupRecord.Get(TempMyAgentSetup.\"User Security ID\") then begin\n        MyAgentSetupRecord.Init();\n        MyAgentSetupRecord.\"User Security ID\" := TempMyAgentSetup.\"User Security ID\";\n    end;\n\n    MyAgentSetupRecord.\"Custom Property\" := TempMyAgentSetup.\"Custom Property\";\n\n    if not MyAgentSetupRecord.Modify() then\n        MyAgentSetupRecord.Insert();\nend;\n```\n## Using the Agent Setup codeunit\nThe `Agent Setup` codeunit from the System Application is designed to work with custom setup pages, providing helper methods for UI-based agent configuration. It uses the `Agent Setup Buffer` record to track configuration changes and persist them when saved.\n### Key methods\nMethod|Description\nGetSetupRecord|Initializes the `Agent Setup Buffer` with agent metadata for new or existing agents.\nGetChangesMade|Returns whether any changes have been made to the agent configuration.\nSaveChanges|Persists the agent configuration, creating a new agent or updating an existing one. Returns the agent's User Security ID.\n### UI helpers for configuration pages\nThe `Agent Setup` codeunit also provides helper methods to open common configuration pages:\n Open the language and region settings page for the agent\n Open the agent access control page to manage which users can interact with the agent\n Open a profile lookup to let users select from available profiles\n Open an agent lookup to let users select from available agents\n## Setup page design considerations\nThe following design principles are recommended when creating a setup page for your agent.\n As a source table, you must use a table with the user security ID of your agents as the primary key. The table should contain other relevant settings for your agent.\n The source table should be used as a temporary table, so that any changes aren't applied until the user decides to update their configuration by clicking the update button.\n Always use the setup part as it ensures a common visual identity for agents and also comes with relevant disclaimers around the use of AI in your feature.\n## Related information\nConfigure agents programmatically (preview)<ai-agent-sdk-configuration>\nCoding agents in AL (preview)<ai-agent-sdk-overview>\nDefine and register an agent programmatically (preview)<ai-agent-sdk-define-register>\nManaging agent tasks programmatically (preview)<ai-agent-sdk-tasks>\nThe ConfigurationDialog page type (preview)<../developer/devenv-page-type-configuration-dialog>"}