Agents in Business Central – part 1 – the architecture

Since Business Central 27.4 minor update you can create your own agents inside Business Central:

Currently this feature is in Public Preview!

You need to have the following requirements:
– Enable the “Custom Agent” capability in Business Central.
– Appropriate permissions to design an agent in Business Central. This must include the “AGENT – ADMIN” permission set assigned to your user.
– The permission set “AGENT – DIAGNOSTICS” is to see the execution costs and the serialized page in the agent task log entries.
– A sandbox environment for testing and experimentation from version 27.4
– Billing setup for agent capabilities in your tenant.

In this blog series I will go through all the major topics how you can create your own agent.
Before how you can use the prompting or creating the agent from AL code it is important how the architecture is from the agent to understand how the agent is working. The following picture describes it:

Trigger the agent

To trigger the agent you need to create a task in Business Central. When a task is created the agent will start working with it.
You can create a task with the codeunit “Agent Task Builder”:
BCApps/src/System Application/App/Agent/Interaction/AgentTaskBuilder.Codeunit.al at main · microsoft/BCApps
This codeunit has several functions. For example creating the task:

With the codeunit “Agent Task” you can restart a task but also stop a task or check the status of it:
BCApps/src/System Application/App/Agent/Interaction/AgentTask.Codeunit.al at main · microsoft/BCApps
If a task is created the orchestrator will pick it up as shown in the picture below:

The orchestrator will do:

• Asynchronous execution
  Task status tells the orchestrator how to handle them.
• Separate session
  Agent tasks run on a separate session where the agent is the user.
• Parallel execution
  Many tasks for the same agent can run in parallel.
• Separate transaction
  Each task can be seen as a separate user session, thus uncommitted data may not be viewable and concurrent modifications can collide.

Examples of creating a task

You can create a task programmatically as shown above. For example if an email is received (create a codeunit that is triggered by the Job Queue) or a field is changed. You need to take care if it is a reply on an already task that exists or he has to create a new task.
For emails there is a conversation ID. If there is a reply in a mail change the conversation ID is allways the same:

Creating messages

When the message is a reply on an already task you can use the codeunit “Agent Task Message Builder”:
BCApps/src/System Application/App/Agent/Interaction/AgentTaskMessageBuilder.Codeunit.al at main · microsoft/BCApps
With this codeunit you can add to messages but also include the attachments.

Outgoing messages

For outgoing messages you can create a codeunit that is triggered by the Job queue (just like the incoming messages).
First we need to find all the messages that has the type is output and the status is reviewd:

Then we process each outgoing messages:

And with the GetText we get the output text for the e-mail body:

Be aware that you can create a table where all messages that are send away for your archive like from who it was and to who is sends away with a date.
And also remind that you can with codeunit “Agent Message” you have to set the status to Sent.

And you are ready!

Next blog will about some specific features for the prompting.