Report Builder Agent

The Report Builder Agent is an AI chat assistant embedded in the layout editor. You describe the layout you want — optionally attaching a sample document — and the agent builds or edits the layout for you. This page explains setup, everyday usage, and the skill library.

What the Agent Can Do

Build a complete layout from a description ("Create a clean, modern invoice layout with our logo top right")
Reproduce a sample document — attach a PDF or an image of an existing form and ask the agent to match it
Restyle an existing layout (fonts, colors, spacing, headers/footers)
Add or change individual parts ("add a QR code with the payment link in the footer")
Configure page settings, backgrounds, and watermarks
Test print the layout itself, look at the resulting PDF, and iterate until it is right

The same AI engine also powers the report set actions Learn Skill from Layout and Apply Skill — those run without the chat window, showing a progress dialog instead (see Report Sets).

Setup

Bring Your Own Key. The agent works on a BYOK model: nothing works until you configure your own AI provider and key. You do not need Simple Agent Designer or any other product to use it — any supported third-party AI provider account will do. Claude (Anthropic) and ChatGPT (OpenAI) are both known to work well.

Before the agent works, an administrator must configure an AI provider on the Simple Object Designer setup page, in the Agent group:

Field	Description
Agent AI Provider	Azure Open AI, ChatGPT Open AI, Anthropic (Claude), or LM Studio
Provider Endpoint	The provider's API URL
Provider Key	Your API key. Stored encrypted and never shown again after entry; a read-only "Provider Key Is Set" flag confirms one is stored
Provider Model	Optional model name. Leave blank to use the provider default — but see the version note below

Configuration steps:

Open the Simple Object Designer Setup page
Select your AI provider
Enter your key
Enter the endpoint and model as well, where the provider requires them

The configuration process is not dependent on the Business Central version — running BC 27 does not change these steps.

About the Provider Key field: it is a protected secret. After entry it is never displayed back, so the field looks empty even though the key is stored. Check the read-only Provider Key Is Set flag rather than assuming the paste failed.

About the Provider Model field: it is normally optional. In app version 1.0, however, leaving it blank could prevent the agent from activating, and an explicit model name had to be entered. Later versions work correctly with it blank. If the agent will not activate on 1.0, either enter a model name or update SOD — see Updating SOD.

Additional requirements:

Allow HttpClient Requests must be enabled for Simple Object Designer in Extension Management — the agent calls your AI provider directly over HTTPS
You need your own account/subscription with the chosen AI provider; usage is billed by that provider under your own agreement
The provider account must have available credit or billing set up. An account with no credit stops the agent from working even when every setup field is correct.
LM Studio lets you run a local model instead of a cloud provider (an API key is optional for it)

Azure Open AI endpoint format

Azure requires a specific endpoint shape, and getting it wrong is the most common Azure setup failure.

Set Provider Endpoint to: https://<resource-name>.openai.azure.com/openai/v1/chat/completions
Set Provider Model to the name of your Azure deployment
Azure AI Foundry-style endpoints (host services.ai.azure.com) must also have /openai/v1/chat/completions appended
A bare resource endpoint without the /openai/v1/chat/completions path will not work

Using Copilot / Azure AI

If your organization's policy restricts AI usage to Copilot within your own tenant:

Create a deployment in Azure AI Foundry
Take the endpoint, model and key from that deployment
Enter them in the Simple Object Designer Setup as above, following the Azure endpoint format

Data Privacy

The agent sends your prompts, attached files, the report's layout code, and dataset information (including example values captured during Learn Report) to the configured AI provider. Choose a provider and account that satisfies your organization's data-handling requirements.

Security and Data Handling

For readers evaluating the agent against an internal AI or security policy:

Customer data is not used to train the model.
Processing happens through your own configured AI provider account under the BYOK model, so the data path and its terms are the ones you have already agreed with that provider.
Hougaard introduces no additional data-usage of its own.

Using the Agent

Open a layout in the visual editor (or the Full Page Canvas editor)
The Report Builder Agent pane appears as a FactBox with the greeting "Tell me what you need — I'll Build the Report Layout for you"
Type your request and send it — or use the upload button to attach a sample PDF or image first

While the agent works you can watch it in real time:

The chat shows each tool step with a progress indicator and a collapsible summary of the tools used
The canvas switches to a read-only "monitor" mode and refreshes as the agent edits, so you see the layout being built. Your own unsaved canvas changes are saved first, so the agent works on top of what you see on screen
The agent can test print the layout and inspect the resulting PDF itself, then correct problems it sees
If the report needs filters to produce data, the agent can open the report's request page so you pick sensible test filters

You can send a new message while the agent is working — it is delivered as an interruption and the agent adjusts course.

Example Prompts

"Recreate the attached invoice as closely as possible."
"Make the header dark blue with white text and move the logo to the left."
"Add a group per customer with a subtotal line under each group."
"Add a 'DRAFT' watermark diagonally across every page."
"The totals don't line up with the amount column — fix the alignment."

The Skill Library

The agent has a skill library: reusable Markdown documents (house style rules, naming conventions, layout recipes) that are injected into the agent's instructions so it applies them in every session.

Open it with the Skills action on the agent pane. Each skill has:

Field	Description
Code	Short unique identifier (the slug the agent uses to read or update it)
Title	Skill title
Description	One-line summary used to decide when the skill is relevant
Auto-Loaded	Whether the skill is automatically loaded into the agent's instructions. Turn off to keep a draft without affecting the agent
Content	The skill body, written in Markdown

Notes:

Skills are shared across all companies in the environment
The agent itself can save new skills or update existing ones when you ask it to remember something ("remember that our documents always use the Inter font")
Use skills for durable guidance ("all amounts right-aligned, two decimals"), not for one-off instructions

The skill library is separate from a report set's visual style skill, which describes one concrete look for a group of documents (see Report Sets).

Limits and Behavior

A single request is limited to 40 tool steps; if the agent hits the cap it stops and asks you to narrow the request
Very long answers can be cut off at the provider's output limit
Temporary provider errors (rate limits, outages) are retried automatically before an error is shown
The agent works on the layout that is currently open in the editor — it is not a general-purpose chat

Troubleshooting

Symptom	Check
Error about "Allow HttpClient Requests"	Enable HttpClient requests for Simple Object Designer in Extension Management
"… is missing an API key"	Enter the Provider Key on the setup page (Agent group)
"Failed to create the URL for the request. Please, make sure to set a valid URL."	No AI provider or no valid Provider Endpoint is configured. The agent is BYOK — configure Agent AI Provider, Provider Endpoint and Provider Key in the Agent group
"The Simple Object Designer cannot activate the agent due to missing setup. Please configure an Agent in the SOD setup."	(1) Confirm a provider is configured including the Provider Key; (2) on app version 1.0, fill in Provider Model; (3) confirm the provider account has available credit
Agent says it isn't set up although endpoint and key are filled in	Update SOD to the latest version. Older versions required Provider Model to be filled in before the agent would activate
"The data does not represent a valid JSON token" when a prompt runs	The Azure Open AI endpoint is not in the required format. Use `https://<resource-name>.openai.azure.com/openai/v1/chat/completions` and set the model to your deployment name. Make sure SOD is current — this format is supported in builds following the Azure Responses API changes
"AI Provider error" after retries	Provider outage or invalid key/endpoint/model — verify the Agent settings, and check the account has credit
Agent responses seem to ignore your standards	Check the skill library: is the relevant skill present and Auto-Loaded?
Layout looks unfinished after a run	Ask the agent to test print and fix what it sees, or refine your request