Getting Started

Get from zero to a working GenerateText call: install the apps, declare dependencies, then call "AIOS Client" with a provider model.

Prerequisites

1. Install the AL Language extension.
2. Ensure Business Central Application symbols are available (Application 28.x).
3. Have a sandbox or dev environment you can publish extensions to.

Source repository: GuillemPM/AL-AI-Toolkit (MIT).

Get the apps

The SDK ships as several standalone Business Central extensions. You can install the packaged apps, or clone the repository and build them yourself.

Download a release

Packaged .app files are published on the Releases page. Download the apps you need, then upload them in Business Central under Extension Management, using Manage > Upload Extension.

Install in dependency order, because Business Central rejects an app whose dependencies are not present yet:

1. AI Open SDK (core).
2. AI Open SDK Provider Utils, if you install OpenAI, OpenCode Zen, or OpenAI Compatible.
3. The provider apps you call.

Build from source

Clone the repository once, then package and publish the stack to your environment:

git clone https://github.com/GuillemPM/AL-AI-Toolkit.git
cd AL-AI-Toolkit

Every folder under apps/ is a standalone AL extension with its own app.json and src/. Open AL-AI-Toolkit.code-workspace for the whole stack, or open a single app folder if you only work on one.

1. Open apps/AIOpenSDK.Core, point .vscode/launch.json at your environment, then run AL: Download Symbols once. This fills the shared .alpackages/.

2. From the repository root, package core and Provider Utils so the provider apps can resolve them:

   ./scripts/prepare-deps.sh     # Linux or macOS

   .\scripts\prepare-deps.ps1    # Windows

3. Publish core, Provider Utils, and the providers to your dev endpoint:

   $env:BC_USERNAME = 'YOUR_USER'
   $env:BC_PASSWORD = 'YOUR_PASSWORD'
   .\scripts\publish-apps.ps1

   The target comes from apps/AIOpenSDK.Core/.vscode/launch.json. Override it with BC_SERVER, or with -Server on the script. There is a publish-apps.sh for Linux and macOS.

Alternatively, open a single app and use Package and Publish from VS Code. Full workflows, including provider-only development, live in docs/DEVELOPMENT.md.

Choose apps

Provider adapters ship as separate Business Central apps. Your extension depends on core plus each provider you call. "AIOS Mock" lives in core, so tests need no extra app.

OpenAI, OpenCode Zen, and OpenAI Compatible also require AI Open SDK Provider Utils; that dependency is declared on the provider app, so you usually do not list it yourself.

Example app.json fragment for Anthropic:

"dependencies": [
  {
    "id": "f624c4ac-75e8-4ce4-9a31-c2d6ff2a05a1",
    "name": "AI Open SDK",
    "publisher": "Guillermo Padilla",
    "version": "0.1.0.0"
  },
  {
    "id": "b6caa435-9837-4155-9932-0b591bdeb4d1",
    "name": "AI Open SDK Anthropic",
    "publisher": "Guillermo Padilla",
    "version": "0.1.0.0"
  }
]

App Ids match the published toolkit packages. Prefer the Ids from your symbol feed or the release you installed if they differ.

Approve the provider and assign permissions

Two setup steps in Business Central stop the first call from failing. Do them once per company before you call a live provider.

1. Approve the privacy notice. Each provider app registers a privacy notice, because it sends data outside Business Central. Open Privacy Notices Status, find the provider (for example AI Open SDK Anthropic), and agree to it. Until then, calls to that provider fail with an InvalidRequest error. "AIOS Mock" needs no approval. To check the approval from AL, see Error handling.

2. Assign permissions. Users who run your AI features need the SDK permission sets for the provider they call. Each provider set already includes core:

   Provider	Assignable permission set
   Anthropic	AIOS Anthropic User
   OpenAI	AIOS OpenAI User
   OpenCode Zen	AIOS OCZen User
   OpenAI Compatible	AIOS Compatible User
   Mock only (tests)	AIOS User Mock

To give users one permission set for your whole feature, include the non-assignable object sets in your own. For OpenAI, OpenCode Zen, and OpenAI Compatible, also include AIOS ProvUtils Objects:

permissionset 50100 "MYAPP AI User"
{
    Assignable = true;
    Caption = 'My App - AI User';
    IncludedPermissionSets =
        "AIOS Objects",             // core client, schema, tools
        "AIOS Anthropic Objects",   // the provider you call
        "MYAPP Objects";            // your own objects
}

First call

Load the API key into SecretText, bind a model from the provider factory, and call "AIOS Client":

Anthropic: Codeunit "AIOS Anthropic";
Client: Codeunit "AIOS Client";
Result: Codeunit "AIOS Generate Result";
ApiKey: SecretText;
begin
    // Load into SecretText from Isolated Storage / setup
    Result := Client.GenerateText(
        Anthropic.Model('claude-fable-5', ApiKey),
        'Hello');
    Message(Result.Output());
end;

GenerateText returns "AIOS Generate Result" and errors on failure, so there is no status code to check on the happy path. Result.Output() holds the reply text, and the Message above shows something like:

Hello. How can I help you today?

The same result carries the raw response and usage alongside the text, which is what you inspect while wiring things up:

Full surface: AIOS Generate Result.

Keep API keys as SecretText end to end (hidden in the debugger; HTTP headers use the SecretText overloads).

What to try next

Interactive samples live in the toolkit repo under apps/AIOpenSDK.Examples/ (demo page "AIOS Toolkit Demo" and usage codeunits).