Agents in Business Central – part 5 – Creating agent from code

Agents in Business Central – part 5 – Creating agent from code

By Bert Verbeek 2

Welcome back to this blog series on building agents in Business Central.
So far, we explored architecture (Part 1), crafting instructions (Part 2), limiting agents and UI (Part 3), and troubleshooting (Part 4).

Now it’s time for Part 5, where we move beyond configuration and into the heart of AL development:
Creating, configuring, and registering agents directly from code.

This is where your agent stops being “just a prototype” and becomes a structured, well‑defined, extensible component inside your Business Central solution.

When Should You Build Agents Programmatically?

The Agent is perfect for experimenting, validating ideas, and learning how the pieces fit together.
But when you want:

  • Full control
  • Versioning and ALM
  • Predictable behaviors
  • AppSource suitability
  • Rich customization

…you switch from configuration to code‑based agents.

Business Central offers a clear architectural pattern for this: through agent‑specific interfaces, setup pages, capability registration, and KPI tracking.

Let’s walk through the most important building blocks.

Register capability

Like all other copilot capabilities you need to register also your agent so in that way you need to extend enum “Copilot Capability”:

And then on install you can register your agent:

If you have done that you can set the capability:

The interfaces

There are two interfaces that are important:

IAgentFactory

It defines how an agent presents itself and gets configured during setup — covering everything from the agent’s default profile and initials, to its first-time setup experience, Copilot capability registration, and default access controls.

IAgentMettadata

While IAgentFactory handles how an agent is created, the IAgentMetadata interface (also in System.Agents) defines how an agent presents itself at runtime. It’s the contract that controls the agent’s display name, initials, setup page, summary dashboard, and task message views — essentially everything the user sees when interacting with the agent in Business Central.

Through its methods like GetDisplayName, GetInitials, GetSummaryPageId, and GetAgentAnnotations, this interface lets developers fully customize the agent’s UI experience.

IAgentExperimental and IAgentTaskExecution

There is also an interface IAgentExperimental that you can implement. This ons has one procedure “GetPageScripts”. So it looks like that an agent can also use Page scripting scripts to fill in some data in the future. You cannot implement this because it is internal.

Next to IAgentExperimental there is also an implementation of IAgentTaskExecution. With this interface you can include extra validations and user suggestions:

  • AnalyzeAgentTaskMessage
    • This lets you inspect each message the agent produces and add annotations (Info / Warning / Error) before the message is finalized.
  • GetAgentTaskUserInterventionSuggestions
    • When the agent’s task requires human intervention (e.g., the user needs to review/approve something), this procedure lets you provide pre-built suggestion buttons the reviewer can pick. Each suggestion has a Summary (shown to the user), Instructions (sent to the agent if selected), and a Description (used to determine relevance).
  • GetAgentTaskPageContext
    • This tells the agent what currency, language, and date format to use when communicating.

Creating the agent

When that is all done you can finally create your agent from code. For that you can use codeunit “Agent”
BCApps/src/System Application/App/Agent/Setup/Agent.Codeunit.al at main · microsoft/BCApps

And setting the profile:

Setup page

If you want to create a setup page for you agent like this one:

you have to create a page with the PageType ConfigurationDialog and assign a table and set the SourceTableTemporary to true.
An example you can find here:
InventoryCheckAgent/src/Setup/ICASetupDialog.Page.al at main · Bertverbeek4PS/InventoryCheckAgent

Also remember that the sourcetable that you have assign have a field “User Security ID”

KPI page

When you hover over the agent icon you can also create a nice KPI page:

This is doen through a CardPart and setting some cuegroups like is done on this example:
InventoryCheckAgent/src/RoleCenter/ICAKPI.Page.al at main · Bertverbeek4PS/InventoryCheckAgent

Please remember that the source table also must have a “User Security ID” field. Otherwise when you hover over it you get an unexpected error!
And you can assign it on the implementation of the IAgentMetadata interface:

2 COMMENTS

Sofia

Hi.
I checked the documentation as well as your code for better understanding on how to use the new development tools. However, there is something that I can’t quite understand how it’s working in your code.
In a scenario where the custom configuration page is being used to create and update agents, if a user opens your page and creates a new agent, it will save a setup record with a null user security ID, because in UpdateControls() it will use the GetOrCreate() procedure in the setup table and create it there, since at the time no user security ID exists for that configuration page.
Then if I go and get the setup page, it will always be showcasing that empty record.
Did you notice this behavior when testing the agent?

Reply

Leave a Reply

Your email address will not be published. Required fields are marked *