Agents in Business Central – part 4 – troubleshooting

In the previous parts of this series, we explored the foundational concepts behind Business Central agents.

• Part 1 explained the architecture and how agents operate inside the platform.
• Part 2 covered the importance of well‑designed instructions and how they shape the agent’s behavior.
• Part 3 focused on limiting agents and the UI to ensure safety, predictability, and control.

Now, in Part 4, it’s time to look at something every builder eventually needs:
How do you troubleshoot an agent when something goes wrong?

Because no matter how well you design an agent, there will be moments where it doesn’t behave as expected. Maybe it misinterprets an instruction. Maybe a field value is missing. Maybe a task collides with another process. Or maybe the user simply doesn’t understand what the agent wants from them.

This article walks you through the core elements that help you diagnose issues, understand what happened, and improve your agent over time.

Agent Consumption

Not a real troubleshooting page. But agents consume credit and with that you have to communicate clearly to users / customers how much on average you agent consumed.
With the Agent Consumption page you can clearly see this:

See also:
Manage consumption-based billing – Business Central | Microsoft Learn
How to set this up.

Agent tasks and details

With the option “View details” on the “Agent Task Log” you already have a good view what the agent saw, memorized, where the agent has access to:

Currently this is the only way to troubleshoot the agent.

Also if you look at the fasttab “What the agent saw” you see the description field.
Remember that this is the tooltip instead of the property “description” in an AL table object.

Also, when you agent has an error you have to test the whole process again. This can be a very tidiest job!

Common pitfalls

• Unclear error messages
  • It is important that your error messages are clear enough for the agent (you have to do it also for the users). Agent then will try to solve the error. So actionable error messages will be perfect. But describe the why and how to solve it very clearly. Don’t put it in the prompt but in the error message.
• Unclear tooltips
  • As you can see in the section “What the agent saw” the agent is looking at the tooltips. So describe it very carefully.
• Too much fields
  • In part 3 was it all about what the agent saw. So also in this one keep the fields and actions as less as possible so that the agent cannot make any mistakes.
• Same captions
  • Prevent that you have the same caption on the lines and headers. For example if you have “No.” on your header and lines as a field caption the agent will get confused!