Develop a Custom Business Central Agent with AL SDK: …

Practical, click-by-click guide

Follow the numbered steps in a Business Central sandbox. Product labels vary by version and locale; official Microsoft pages are linked for verification.

Result and version boundary

Create a native Business Central agent type skeleton and test a read-only task. Microsoft currently marks the Agent SDK as preview. Sandbox evaluation is documented from version 27.4, with production support from 28.1. Features in newer builds cannot be assumed in older deployments.

Step 1: Prepare a sandbox

Check BC version, environment, company, VS Code and AL Language. Use fictional test records. Confirm the SDK symbols are available in your target build.

Step 2: Generate the Agent template

In VS Code open Ctrl+Shift+P, execute AL: New Project and choose the Agent template. This generates version-appropriate interface scaffolding. Do not guess interface signatures from outdated snippets.

Step 3: Inspect app.json and symbols

Check app ID, publisher, version, application and runtime compatibility. Configure launch.json for your sandbox and execute AL: Download Symbols. If interfaces are missing, check version and feature availability rather than inventing replacements.

enumextension 50101 "Demo Agent Provider" extends "Agent Metadata Provider"
{
    value(50101; "Demo Review Agent")
    {
        Caption = 'Demo Review Agent';
        Implementation =
            IAgentFactory = DemoAgentFactory,
            IAgentMetadata = DemoAgentMetadata,
            IAgentTaskExecution = DemoAgentTaskExecution;
    }
}

Important: the example will not compile alone. Generate the Agent template and implement referenced interfaces and Copilot capability for the installed SDK.

Step 4: Register Agent Metadata Provider

Extend the Agent Metadata Provider enum and map the agent type to implementation codeunits. The example below illustrates the registration, not the full implementation. Use allocated object IDs and ensure the referenced codeunits actually implement the interfaces.

Step 5: Implement IAgentFactory

Complete the generated factory codeunit using the methods supplied by your SDK version. Define how agent instances are created and initialized, including setup, default settings and minimal permissions.

Step 6: Implement IAgentMetadata

Provide display information and an accurate purpose for the agent. Keep the read-only scope explicit: it can summarize approved vendor and invoice information, not post or change bank accounts.

Step 7: Implement IAgentTaskExecution

Use the generated task-execution methods to connect a basic vendor lookup task. Begin with an existing fictional vendor and produce a factual summary. Do not enable write operations in the first version.

Step 8: Register Copilot capability and setup

A corresponding Copilot capability must be registered in addition to the agent type. Implement setup pages and other template requirements for your release. An enum extension alone is not a functioning agent.

Step 9: Apply minimal permissions

Restrict agent permission sets to required objects, tables and operations. Define configuration rights separately from task usage. Check the agent profile’s accessible pages and never grant SUPER as a shortcut.

Step 10: Build and publish to sandbox

Compile with the AL extension, resolve every compiler error and publish to the sandbox. Create and activate an instance using the supported setup experience. A blog example is not proof that a specific SDK build compiles.

Step 11: Verify tasks and tracing

Test an existing and missing vendor, restricted permissions, ambiguous source data and prompt-injection text. Review the agent task log and ensure untrusted document content cannot change its instructions.

Step 12: Introduce human approval

As a second phase, allow the agent to propose a review request, while actual posting and bank changes remain protected by AL business rules, approval state and version checking. Recompile and rerun regression tests after SDK changes.

Checklist before moving beyond sandbox

Record the exact BC version and supported feature state
Run expected-success and expected-failure tasks
Verify least-privilege rights with another test user
Review data privacy and approval rules
Document log review, disabling and recovery

Microsoft source documentation

https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/ai/ai-agent-sdk-overview

Develop a Custom Business Central Agent with AL SDK: Hands-On Tutorial