Stage 7 of 10

Agent in AL

Convert your agent to AL code so it can be packaged and distributed as an extension.

Overview

👨‍💻 Developer track starts here
From this stage onwards the workshop shifts to writing AL code. If you're not a developer — or you'd simply like more time to experiment with your agent in the Business Central UI — that's completely fine! Head back to Stage 5 and keep iterating on your agent's instructions and profile. There's no obligation to continue beyond this point.

A UI-built agent only lives in the environment where it was created. Moving it to AL means you can version control it, deploy to any environment, and eventually distribute it via AppSource. Use the XML from Stage 6 as your reference — you’ll recreate the same agent as a proper AL extension.

📖 Docs reference
Coding agents in AL — Overview
Convert an exported agent to AL

Part 1 — Create the AL Project

1

Create a new AL project using the Agent template

In VS Code, hit Ctrl+Shift+P and run AL: New Project. When prompted for a template, pick Agent.

Name it something like MyWorkshopAgent and choose a folder.

2

Set the runtime version in app.json

Open app.json and set "runtime" to "17.0" — you need this for the Agent SDK interfaces to be available.

{
  "id": "...",
  "name": "MyWorkshopAgent",
  "runtime": "17.0",
  ...
}
3

Configure launch.json to point at your environment

Open .vscode/launch.json and update it to target your environment — grab the environment name and tenant ID from your handout.

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "al",
      "request": "launch",
      "name": "My Workshop Environment",
      "environmentType": "Sandbox",
      "environmentName": "<your-environment-name>",
      "tenant": "<your-tenant-id>"
    }
  ]
}

Replace the placeholder values with what's on your handout (same environment name as the URL).

4

Download symbols

Run AL: Download Symbols from the command palette. VS Code will connect to your environment and pull down the symbols needed to compile. You'll be asked to sign in if needed.

5

Explore the generated structure

The template gives you a full working skeleton. Key files:

  • AgentMetadataProvider enum extension — registers your agent type
  • AgentFactory codeunit — implements IAgentFactory (default profile, permissions, setup page)
  • AgentMetadata codeunit — implements IAgentMetadata (display name, initials, summary)
  • AgentTaskExecution codeunit — implements IAgentTaskExecution
  • Instructions .txt resource file — the plain-text instructions for your agent
  • Setup page — the configuration dialog shown when creating an instance
  • Install codeunit — registers the Copilot capability on installation

Part 2 — Adapt the Template to Match Your Exported Agent

Keep the XML from Stage 6 open alongside VS Code — you’ll use it as a reference for the next few steps.

6

Copy the instructions into the resource file

Find the instructions text in the XML and paste it into the instructions .txt resource file generated by the template, replacing the placeholder. The IAgentFactory loads this on agent creation.

7

Set the default profile

In the AgentFactory codeunit, find the GetDefaultProfile method. Update the Profile ID to match the profile from your exported agent (e.g. 'BUSINESS MANAGER').

procedure GetDefaultProfile(var TempAllProfile: Record "All Profile" temporary)
begin
    TempAllProfile."Profile ID" := 'BUSINESS MANAGER';
    TempAllProfile."App ID" := '437dbf0e-84ff-417a-965d-ed2bb9650972';
    TempAllProfile.Insert();
end;
8

Set the default permissions

Open the My Agent permission set included in the template and add the permission sets from the XML. We used SUPER for the workshop, but you'd normally go least-privilege in production.

9

Update the display name and initials

In the Setup page, update the display name and initials to match your agent.

Part 3 — Publish and Verify

10

Publish the extension

Press F5 (or run AL: Publish) to compile and deploy the extension to Business Central.

11

Create an instance of your AL agent

Go to the Agents (preview) page — your agent type should be listed. Select it and run through the setup dialog. It'll apply the profile and permissions from your AL code automatically.

ℹ AL agents and the task designer
Unlike UI-built agents, AL agents can't be triggered from the task designer in the UI. Programmatic task creation is covered in Stage 9 — that's how you'll run tasks against this agent.
💡 Why this matters
Once it's in AL you can commit to source control, run it through CI/CD, promote it with a .app file, and eventually submit to AppSource — no BC UI needed.
✓ Stage complete when…
Your AL extension is published and an agent instance is created from it on the Agents (preview) page.