Simple Agent Designer Documentation
Index

Common Issues

This page covers frequently encountered issues when using Simple Agent Designer and provides solutions for each.

Installation and Setup Issues

Extension Not Visible in AppSource

Symptom: You cannot find Simple Agent Designer in the Business Central Extension Marketplace.

Possible Causes:

  • Your Business Central version is older than 26.0.0.0
  • Your environment is not configured for US or CA country/region

Solution:

  1. Check your BC version: Search for "System Information" and verify the Application Version
  2. Verify your country setting in Company Information
  3. If your version is below 26.0.0.0, upgrade your Business Central environment
  4. Contact Hougaard support for availability in other countries

Missing Pages After Installation

Symptom: After installing, searching for "Agent Setup" or "AI Agents" returns no results.

Possible Causes:

  • The AI Accountant Hgd permission set has not been assigned
  • Browser cache is stale

Solution:

  1. Ask your administrator to assign the AI Accountant Hgd permission set to your user
  2. Sign out and sign back in to Business Central
  3. Clear your browser cache and reload

Dependency Error During Installation

Symptom: Installation fails with a message about a missing dependency.

Solution:

  1. Ensure the AL Compiler and Interpreter extension by Hougaard is installed first
  2. For on-premises: Publish and install the dependency extension before Simple Agent Designer
  3. For SaaS: The dependency should resolve automatically — contact support if it does not

AI Provider Issues

"No Response from AI" or Timeout

Symptom: Processing a workload hangs or times out without an AI response.

Possible Causes:

  • Invalid AI provider endpoint URL
  • Network connectivity issues between BC server and AI provider
  • AI provider service outage

Solution:

  1. Go to Setup → AI Providers and verify the endpoint URL is correct
  2. Test the endpoint URL from the BC server using a browser or network tool
  3. Check the AI provider's status page for any service outages
  4. Verify your firewall allows outbound HTTPS connections to the provider
  5. If you recently switched to one of the newer providers (Google Gemini, xAI Grok, Mistral, DeepSeek, Moonshot Kimi, Alibaba Qwen, Zhipu GLM, MiniMax), double-check that provider's endpoint and key — each has its own base URL and credential format

Authentication Error

Symptom: Processing fails with an authentication or authorization error.

Possible Causes:

  • Invalid or expired API key
  • Incorrect API key entered
  • API key does not have sufficient permissions

Solution:

  1. Go to Setup → AI Providers
  2. Click on the Access Key field for the affected provider to open the key management page
  3. Generate a new API key
  4. Enter the new key in the Access Key field
  5. Test with the Interactive Agent chat

Rate Limit Errors (429)

Symptom: Processing intermittently fails or slows down significantly.

Cause: The AI provider is limiting your request rate.

Solution:

  • Simple Agent Designer automatically retries with a fixed 10-second wait between attempts (up to 10 retries) — not exponential backoff
  • If the issue persists, upgrade your AI provider tier for higher rate limits
  • Reduce concurrent processing (avoid processing many workloads simultaneously)
  • Consider using a different AI provider for some agents to spread the load

Empty or Nonsensical AI Responses

Symptom: The agent responds with empty text or irrelevant content.

Possible Causes:

  • Model name is incorrect or not available
  • Model is too small for the task complexity
  • Instructions are unclear or contradictory

Solution:

  1. Verify the LLM Model name on the agent matches an available model
  2. Try a more capable model (e.g., switch from a smaller "mini"/"nano" model to a full-size model such as gpt-5-mini or a larger Claude/Gemini model)
  3. Review and clarify agent instructions
  4. Test with a simple question via the Interactive Agent chat

Workload Processing Issues

Workload Stuck in "Started" Status

Symptom: A workload shows "Started" status but never completes.

Possible Causes:

  • Background session crashed
  • AI provider timeout not handled
  • The agent entered an infinite tool call loop

Solution:

  1. Wait a few minutes — the process may still be running
  2. If it does not complete, try reprocessing the workload
  3. Use Debug Run instead of Process to watch the execution in real time
  4. Review the last process activity entries for clues about where it stopped

"License Validation Failed" or Processing Blocked in Production

Symptom: In a production environment, workload processing and interactive chat are blocked, or you see a license error.

Cause: The extension runs free only in a SaaS sandbox (demo mode). Production requires a valid, purchased license key. Processing and chat are blocked until one is registered. Validation is also blocked if the extension cannot reach the online license server.

Solution:

  1. Go to Setup → App License and check your license status
  2. If no key has been registered, enter your Registration Key and choose Register (validating the Registration Key field also triggers registration)
  3. If expired, contact Hougaard to renew — note there is a 2-week warning window before expiry, and on expiry the stored key is cleared
  4. Ensure the extension's outbound HttpClient calls are approved by an administrator. If they are blocked, an HttpClient Warning page appears and validation cannot complete
  5. Confirm the license server host check.hougaardlicense.com is reachable from your environment (allow outbound HTTPS to it)

See Registration for the full licensing model.

Excel Splitter Creates Empty Child Workloads

Symptom: After Excel splitting, child workloads have empty descriptions or titles.

Possible Causes:

  • The Excel file has empty rows
  • The header row is missing or inconsistent
  • The wrong Excel Splitter setting is selected

Solution:

  1. Open the original Excel file and remove any empty rows
  2. Verify the first row contains proper headers (if using "Yes With Header")
  3. If the file has no header, use "Yes No Header" instead
  4. Reupload the file and reprocess

Table Splitter Returns No Records

Symptom: A DataBased workload processes successfully but creates no child workloads.

Possible Causes:

  • Filter criteria are too restrictive
  • "Add Since Last Filter" is enabled and there are no changes since the last run
  • The table number is incorrect

Solution:

  1. Open the Workload Type Card
  2. Review the Table No. and Filter String
  3. Use Assist Edit on the filter to verify records match
  4. If using incremental processing, check the Last Run timestamp
  5. Try temporarily disabling "Add Since Last Filter" to see if records exist

Tool and Function Calling Issues

Agent Does Not Call Tools

Symptom: An agent with tools enabled never uses tools during processing.

Possible Causes:

  • Use Tools is not enabled on the agent
  • The AI model does not support tool calling
  • Agent instructions do not indicate when to use tools
  • The tools are not relevant to the task

Solution:

  1. Verify Use Tools = Yes on the agent
  2. Check the Tools Available page to confirm tools are registered
  3. Use a model that supports tool calling (GPT-4 family, Claude family)
  4. Add explicit guidance to the agent instructions about when to use tools

Tool Execution Errors

Symptom: Tools are called but return errors.

Possible Causes:

  • The user lacks BC permissions for the target table
  • The tool parameters contain invalid values
  • The record being accessed does not exist

Solution:

  1. Check the process activity log for the specific error message
  2. Verify the user has appropriate BC permissions
  3. Review the tool parameters in the activity log
  4. Test the operation manually in Business Central

Agent Loops on Tool Calls

Symptom: Processing takes very long because the agent keeps calling tools repeatedly.

Possible Causes:

  • The AI is not receiving useful results from tool calls
  • Agent instructions are ambiguous about when to stop using tools
  • The model is not interpreting tool results correctly

Solution:

  1. Use Debug Run to watch the tool call loop
  2. Add clearer completion criteria to the agent instructions
  3. Review tool results — they may not contain the information the AI expects
  4. Try a more capable model that handles tool calling better

Agent Cooperation Issues

Agents Not Communicating

Symptom: The coordinator agent does not delegate to other agents.

Possible Causes:

  • The coordinator's instructions do not reference other agent IDs
  • The referenced Agent IDs are incorrect
  • The response format does not match what the orchestration engine expects — delegation requires a fenced json block containing a "to" (target Agent ID) and a "payload"` object

Solution:

  1. Verify the Agent IDs in the coordinator's instructions match actual Agent IDs
  2. Ensure instructions tell the coordinator to delegate by emitting a JSON code block, for example: { "to": "DATAQUERY", "payload": { "task": "..." } }
  3. Use Debug Run to see if the AI generates delegation messages
  4. Review the orchestration engine's detection of the "to"/"payload" delegation block

Messages Not Returning to Coordinator

Symptom: A delegated agent processes work but results never return to the coordinator.

Possible Causes:

  • The delegated agent completes without queuing a response
  • The Agent ID of the requestor is incorrect

Solution:

  1. Check the process activity for both agents
  2. Verify the delegated agent's output includes results that the orchestration engine can route back
  3. Simplify the cooperation to two agents for testing

Performance Issues

Processing Is Very Slow

Possible Causes:

  • Using a very large/slow AI model
  • Large conversation context (many tools, long instructions)
  • AI provider rate limiting
  • Network latency

Solution:

  1. Use a faster/smaller model for simple tasks
  2. Reduce instruction length where possible
  3. Check for rate limit retries in the activity log
  4. Verify network connectivity to the AI provider