{"title":"Configure agents programmatically (preview)","url":"https://jonas-paprotka.de/docs/dev-itpro/ai/ai-agent-sdk-configuration/","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-configuration, 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-configuration","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 configure agent instances, manage lifecycle settings, and update agent instructions programmatically in Dynamics 365 Business Central.","date":"2026-10-02","meta":{"topic":"how-to"},"outline":[{"level":1,"title":"Configure agents programmatically (preview)","slug":"configure-agents-programmatically-preview","at":0,"chars":9654},{"level":2,"title":"Configuring an agent instance","slug":"configuring-an-agent-instance","at":1139,"chars":3061},{"level":3,"title":"Lifecycle management","slug":"lifecycle-management","at":1338,"chars":905},{"level":3,"title":"Identity and display settings","slug":"identity-and-display-settings","at":2243,"chars":245},{"level":3,"title":"Localization settings","slug":"localization-settings","at":2488,"chars":184},{"level":3,"title":"Permissions and access control","slug":"permissions-and-access-control","at":2672,"chars":1528},{"level":2,"title":"Agent instructions","slug":"agent-instructions","at":4200,"chars":1248},{"level":3,"title":"Setting agent instructions from resources","slug":"setting-agent-instructions-from-resources","at":4427,"chars":1021},{"level":2,"title":"Creating agent instances programmatically","slug":"creating-agent-instances-programmatically","at":5448,"chars":1230},{"level":2,"title":"Cross-agent operations","slug":"cross-agent-operations","at":6678,"chars":2052},{"level":2,"title":"Related information","slug":"related-information","at":8730,"chars":924}],"text":"# Configure agents programmatically (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 configure agent instances and manage agent instructions programmatically.\nThere can be one or multiple instances of an agent in Business Central. Each agent instance can have its own instructions, permissions, user settings, and agent access controls defined separately. Each agent instance is uniquely identified by its User Security ID, which is passed as a parameter to all the methods of the API.\n## Configuring an agent instance\nThe Agent codeunit provides methods to configure various aspects of an agent instance after creation. All configuration methods require the agent's User Security ID.\n### Lifecycle management\n Activate or deactivate agent instances to control whether they can process tasks\n Check the current activation state of an agent\nThe archiving methods have the following availability:\n> APPLIES TO: Business Central 2026 release wave 2 and later\n Use Agent.Archive<https://learn.microsoft.com/dynamics365/business-central/application/system-application/codeunit/system.agents.agent#archive> to archive a deactivated agent that you no longer need.\n Use Agent.IsArchived<https://learn.microsoft.com/dynamics365/business-central/application/system-application/codeunit/system.agents.agent#isarchived> to check whether an agent is archived.\n Use IAgentArchiving.IsArchivingSupported<https://learn.microsoft.com/dynamics365/business-central/application/system-application/interface/system.agents.iagentarchiving#isarchivingsupported> to check whether an agent type supports archiving.\n### Identity and display settings\n Get or set the agent's display name\n Retrieve the agent's user name\n Set the agent's instructions that guide how it completes tasks\n Assign a profile to control which Role Center and UI elements the agent uses\n### Localization settings\n Update the agent's language, regional settings (locale), and time zone\n Retrieve current user settings including profile, language, and regional preferences\n### Permissions and access control\n Assign permission sets to control what data and operations the agent can access\n Retrieve the current permission sets assigned to the agent\n Configure which users can manage the agent or assign tasks to it through agent access controls\nSee Agent permissions<ai-development-toolkit-permissions>.\n```al\nprocedure ConfigureAgent(AgentUserSecurityID: Guid; AgentInstructions: SecretText)\nvar\n    TempAccessControlBuffer: Record \"Access Control Buffer\" temporary;\n    TempAgentAccessControl: Record \"Agent Access Control\" temporary;\n    Agent: Codeunit Agent;\nbegin\n    // Set agent instructions\n    Agent.SetInstructions(AgentUserSecurityID, AgentInstructions);\n\n    // Set display name\n    Agent.SetDisplayName(AgentUserSecurityID, 'Updated Agent Name');\n\n    // Assign a profile\n    Agent.SetProfile(AgentUserSecurityID, 'ACCOUNTANT', SystemApplicationAppId);\n\n    // Update localization settings (language, locale, timezone)\n    Agent.UpdateLocalizationSettings(AgentUserSecurityID, 1033, 1033, 'UTC');\n\n    // Update permission sets\n    TempAccessControlBuffer.\"Role ID\" := 'D365 BASIC';\n    TempAccessControlBuffer.Scope := TempAccessControlBuffer.Scope::System;\n    TempAccessControlBuffer.Insert();\n    Agent.UpdateAccessControl(AgentUserSecurityID, TempAccessControlBuffer);\n\n    // Update which users can interact with the agent\n    Agent.UpdateAgentAccessControl(AgentUserSecurityID, TempAgentAccessControl);\n\n    // Activate the agent\n    Agent.Activate(AgentUserSecurityID);\nend;\n```\n## Agent instructions\nAgent instructions are defined on each agent instance separately. This allows for customizing instructions based on custom settings per agent and for dynamically updating them during the agent's lifetime.\n### Setting agent instructions from resources\nIf an agent has instructions that won't change based on per-instance settings or other parameters, the easiest way to define them is in the resources of the agent's AL application. The instructions can then be set every time an agent instance is created by accessing the resource file.\nFirst, add the instruction file to your app.json resources:\n```json\n{\n    \"resourceFolders\": [\"Resources\"]\n}\n```\nThen, load and apply the instructions when creating the agent:\n```al\nprocedure AssignStaticInstructions(AgentUserSecurityID: Guid)\nvar\n    Agent: Codeunit Agent;\n    Instructions: SecretText;\n    InstructionsLbl: Label 'Instructions.txt', Locked = true;\nbegin\n    // Load instructions from resource file\n    Instructions := NavApp.GetResourceAsText(InstructionsLbl);\n\n    // Apply to the agent instance\n    Agent.SetInstructions(AgentUserSecurityID, Instructions);\nend;\n```\n> NOTE\n> Upgrade code is needed for older instances if instructions are only applied during creation.\n## Creating agent instances programmatically\nWhile the typical way to create agent instances is through a ai-agent-sdk-setup-page, you can also create them programmatically using the Agent codeunit. This approach is intended for automation scenarios where agent instances need to be created as part of a business process, for example, a custom wizard.\n```al\nprocedure CreateMyAgent(AgentInstructions: SecretText)\nvar\n    TempAgentAccessControl: Record \"Agent Access Control\" temporary;\n    Agent: Codeunit Agent;\n    AgentUserSecurityID: Guid;\n    UserName: Code[50];\nbegin\n    UserName := 'MYAGENT';\n\n    // Create an agent instance with the specified metadata provider\n    AgentUserSecurityID := Agent.Create(\n        Enum::\"Agent Metadata Provider\"::\"My Agent\",\n        UserName,\n        'My Agent Display Name',\n        TempAgentAccessControl);\n\n    // Set the agent's instructions\n    Agent.SetInstructions(AgentUserSecurityID, AgentInstructions);\n\n    // Activate the agent so it can start processing tasks\n    Agent.Activate(AgentUserSecurityID);\nend;\n```\n> IMPORTANT\n> You can't create agent instances from install codeunits, upgrade codeunits, or background sessions. Agent creation requires an interactive user session.\n## Cross-agent operations\nFor security reasons, it's only possible to use the AI development toolkit to interact with agents defined in your own application. Creating instances, tasks, messages and any configuration changes targeting an agent defined in a different application is blocked with an error.\nThe following example fails if `\"Other Agent\"` is defined in a different application:\n```al\nprocedure ConfigureOtherAgent()\nvar\n    Agent: Codeunit Agent;\n    OtherAgentUserSecurityID: Guid;\nbegin\n    // This will fail with an error if \"Other Agent\" is defined in a different app\n    Agent.SetDisplayName(OtherAgentUserSecurityID, 'Updated Name');\nend;\n```\nIt's possible, however, to allow access to your agent for other apps by creating your own API for interacting with it. To do this, public procedures, which implement the functionality must be exposed.\n```al\ncodeunit 50110 \"My Agent API\"\n{\n    Access = Public;\n\n    /// <summary>\n    /// Updates the display name of the My Agent instance.\n    /// </summary>\n    /// <param name=\"AgentUserSecurityID\">The User Security ID of the agent instance.</param>\n    /// <param name=\"NewDisplayName\">The new display name to set.</param>\n    procedure SetDisplayName(AgentUserSecurityID: Guid; NewDisplayName: Text[80])\n    var\n        Agent: Codeunit Agent;\n    begin\n        Agent.SetDisplayName(AgentUserSecurityID, NewDisplayName);\n    end;\n\n    /// <summary>\n    /// Activates or deactivates the My Agent instance.\n    /// </summary>\n    /// <param name=\"AgentUserSecurityID\">The User Security ID of the agent instance.</param>\n    /// <param name=\"Activate\">True to activate, false to deactivate.</param>\n    procedure SetActiveState(AgentUserSecurityID: Guid; Activate: Boolean)\n    var\n        Agent: Codeunit Agent;\n    begin\n        if Activate then\n            Agent.Activate(AgentUserSecurityID)\n        else\n            Agent.Deactivate(AgentUserSecurityID);\n    end;\n}\n```\nOther applications can then call these public procedures to interact with your agent without directly using the API.\n## Related information\nCreate agent setup pages (preview)<ai-agent-sdk-setup-page>\nUnderstand agent visibility (preview)<ai-development-toolkit-agent-visibility#archived-agents>\nCoding agents in AL (preview)<ai-agent-sdk-overview>\nDefine and register an agent programmatically (preview)<ai-agent-sdk-define-register>\nAgent models (preview)<ai-agent-models>\nManaging agent tasks programmatically (preview)<ai-agent-sdk-tasks>\nAgent permissions (preview)<ai-development-toolkit-permissions>\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>\nWrite effective instructions (preview)<ai-development-toolkit-instructions>\nInstruction keywords (preview)<ai-development-toolkit-instruction-keywords>\nSet up permissions and profiles (preview)<ai-development-toolkit-permissions-profiles>"}