---
title: Debugging an AI Agent
description: Learn how to troubleshoot common AI Agent issues, review call logs, and resolve problems related to responses, pronunciation, escalations, and test calls.
---
[Skip to content](https://support.maqsam.com/debugging-an-ai-agent#main-content)
- [English](https://support.maqsam.com/debugging-an-ai-agent)
- [العربية](https://support.maqsam.com/ar/debugging-an-ai-agent)
English
Show submenu for translations
[](https://support.maqsam.com?hsLang=en)
Open main navigation
Close main navigation
- - [English](https://support.maqsam.com/debugging-an-ai-agent)
- [العربية](https://support.maqsam.com/ar/debugging-an-ai-agent)
English
Show submenu for translations
Welcome to Maqsam
- There are no suggestions because the search field is empty.
1. [Welcome to Maqsam](https://support.maqsam.com/?hsLang=en)
2. [Artificial Intelligence](https://support.maqsam.com/artificial-intelligence?hsLang=en)
3. [AI Agent Studio](https://support.maqsam.com/artificial-intelligence?hsLang=en#ai-agent-studio)
# Debugging an AI Agent
### 🔍 Overview
This guide helps you identify and troubleshoot common AI Agent issues and provides recommended actions to resolve them.
---
### ✋ Before You Start
Before investigating a specific issue, follow these steps:
1. Navigate to **AI Agent** and locate the agent you want to test.
2. Start a **test call**.
3. During the call, try to:
1. Test questions covered in your Knowledge Base.
2. Test all scenarios configured in the instructions field.
3. Verify that the agent follows all configured Guardrails.
4. Review the call from **Call Log**s, and check:
1. Whether the transcription is accurate.
2. Whether the correct tools and knowledge sources were used.
3. Whether the agent behaved as expected.
---
### 🐞 Debug Common Issues
Review the table below for common issues and the recommended actions to resolve them.
| **#** | **Issue** | **Recommended Action** |
| --- | --- | --- |
| **1** | **🚫 The web test call fails to start** | Check your internet connection, and try again. If the issue persists, raise a ticket to the [Support](mailto:support@maqsam.com)and provide: - Agent name - Account name - Issue: the test call has failed |
| **2** | **🎙️ The AI Agent's voice cuts off during the call** | Check your internet connection, and try again. If the issue occurs during web testing calls: - Test the agent through IVR using a phone call instead of the web tester. - Edit the agent and test using a different voice model. If the issue persists, contact [Support](mailto:support@maqsam.com)and provide: - Agent name - Account name - Issue: the AI agent's voice cuts off |
| **3** | **❓ The AI Agent does not answer a specific question correctly** | Verify that the answer exists in the linked Knowledge Base. If the answer does not exist in the Knowledge Base, please add it and reset. If the answers does exist in the Knowledge Base, please do the following: - Review the Call Logs and check whether the Knowledge Base was retrieved. - Rewrite the content to make it clearer and more specific. - If the content was not retrieved, update the Instructions to direct the agent to use the Knowledge Base when handling similar questions. - Retest the agent. |
| **4** | **🗣️ The AI Agent mispronounces words** | - Add the required pronunciation to the agent’s pronunciation dictionary. - If the word was already added to the pronunciation dictionary, adjust the phonetic spelling. - Run a new test call to validate the change. If the issue persists, contact [Support](mailto:support@maqsam.com)and provide: - Agent name - Account name - Issue: the AI agent mispronounces some words |
| **5** | **🔁 The AI Agent escalates calls when it is not required** | - Review the Escalate to Human Agent action configuration. - Check the escalation trigger conditions configured for the action. - Update the trigger conditions to clearly define when the AI Agent should escalate and when it should continue handling the conversation. - Run a new test to validate behavior. |
| **6** | **🚨 The AI Agent does not escalate calls when required** | - Review the Escalate to Human Agent action configuration. - Verify that the escalation trigger conditions cover the required scenarios. - Update the trigger conditions to explicitly include cases where a human agent should be involved. - Run a new test to validate behavior. |
| **7** | **🕒 The AI Agent transfers calls to a human agent 24/7** | - Open the Escalate to Human Agent configuration. - Enable the After Working Hours Fallback option. - Configure your team's working days, business hours, and time-zone correctly. - Run a new test to verify behavior\> |
---
### 💡 Best Practice
After making any changes to your AI Agent's configuration, run new test calls and review the call logs again to confirm that the issue has been resolved before deploying the agent to production.
- [Getting Started](https://support.maqsam.com/getting-started?hsLang=en)
- [Administration](https://support.maqsam.com/administration?hsLang=en#main-content)
- [💳 Billing & Payments](https://support.maqsam.com/administration?hsLang=en#billing-payments)
- [⚙️ Account Settings](https://support.maqsam.com/administration?hsLang=en#%EF%B8%8F-account-settings)
- [Voice](https://support.maqsam.com/voice?hsLang=en#main-content)
- [🔀 IVR Builder](https://support.maqsam.com/voice?hsLang=en#ivr-builder)
- [📞 All Voice Features](https://support.maqsam.com/voice?hsLang=en#all-voice-features)
- [Messaging](https://support.maqsam.com/messaging?hsLang=en#main-content)
- [💬 WhatsApp](https://support.maqsam.com/messaging?hsLang=en#whatsapp)
- [Integrations](https://support.maqsam.com/integrations?hsLang=en#main-content)
- [🔌 HubSpot Integration](https://support.maqsam.com/integrations?hsLang=en#hubspot-integration)
- [🔌 Pipedrive Integration](https://support.maqsam.com/integrations?hsLang=en#pipedrive-integration)
- [🔌 Intercom Integrtion](https://support.maqsam.com/integrations?hsLang=en#intercom-integrtion)
- [🔌 Zendesk Integration](https://support.maqsam.com/integrations?hsLang=en#zendesk-integration)
- [🔌 FreshDesk Integration](https://support.maqsam.com/integrations?hsLang=en#freshdesk-integration)
- [🔌 Salesloft Integration](https://support.maqsam.com/integrations?hsLang=en#salesloft-integration)
- [🔌 Salesforce Integration](https://support.maqsam.com/integrations?hsLang=en#salesforce-integration)
- [🔌 Zoho Phonebridge Integration](https://support.maqsam.com/integrations?hsLang=en#zoho-phonebridge-integration)
- [Artificial Intelligence](https://support.maqsam.com/artificial-intelligence?hsLang=en#main-content)
- [AI Agent Studio](https://support.maqsam.com/artificial-intelligence?hsLang=en#ai-agent-studio)
- [Reports](https://support.maqsam.com/reports?hsLang=en)
- [Legal & Compliance](https://support.maqsam.com/legal-compliance?hsLang=en)
- [FAQs](https://support.maqsam.com/faqs?hsLang=en#main-content)
- [🔌 Integrations](https://support.maqsam.com/faqs?hsLang=en#integrations)
- [⚙️ Accounts](https://support.maqsam.com/faqs?hsLang=en#%EF%B8%8F-accounts)
- [💬 Messaging](https://support.maqsam.com/faqs?hsLang=en#messaging)
- [💳 Payments](https://support.maqsam.com/faqs?hsLang=en#payments)
- [📞 Voice](https://support.maqsam.com/faqs?hsLang=en#voice)
- [✅ Troubleshooting](https://support.maqsam.com/faqs?hsLang=en#troubleshooting)
[](https://maqsam.com/)
Copyright © 2026, Maqsam