Troubleshooting common issues with AI agents

<p>Use this article if your AI agent doesn't respond as expected, escalates too early, or behaves differently across channels or instances. It covers the most common configuration and setup issues, along with the first checks to make before you contact Zendesk Customer Support.</p><h2 id="h_01KW1XV9FYKRA30V4VKY9G5T2F">Preliminary AI agent troubleshooting questions</h2><ol>
<li data-list-item-id="e97572d6e806c7113b33fe4fd59abff59">Is the AI agent enabled and assigned to the right channel? <a href="https://support.zendesk.com/hc/en-us/articles/10488757995034-Creating-an-AI-agent-to-automatically-resolve-customer-issues" target="_blank" rel="noopener noreferrer">Creating an AI agent to automatically resolve customer issues</a>.</li>
<li data-list-item-id="eec5cbf15cf2d54f2d8edf2bd5efa76a0">Are relevant articles, knowledge sources, or integrations published and available to your customers? See <a href="https://support.zendesk.com/hc/en-us/articles/4408845739162-Optimizing-your-knowledge-content-for-generative-AI" target="_blank" rel="noopener noreferrer">Optimizing your knowledge content for generative AI</a>.</li>
<li data-list-item-id="ee4dfaea18738327890d6f6006a684990">Is the <a href="https://support.zendesk.com/hc/en-us/articles/8357756692890-Configuring-language-detection-for-AI-agents" target="_blank" rel="noopener noreferrer">correct language</a> activated and supported?</li>
<li data-list-item-id="e40de56fbd7896aeb7bf6e2916db6fbc1">Have you reviewed the <a href="https://support.zendesk.com/hc/en-us/articles/8357749580186-Reviewing-conversation-logs-for-AI-agents" target="_blank" rel="noopener noreferrer">conversation logs</a> for errors, escalation, or no response?</li>
</ol><p>When you follow the advice above, review common issues below:</p><div style="margin-bottom: 20px; text-align: right;">
<button id="master-toggle" class="btn fw-semibold text-dark" data-action="expand" style="background-color: #DEF991; border: none; outline: none; border-radius: 7px; padding: 10px 20px; font-size: 15px; transition: background-color 0.2s ease;" onmouseover="this.style.backgroundColor='#cbef6d'" onmouseout="this.style.backgroundColor='#DEF991'">
Expand all tabs
</button>
</div>
<script>
document.addEventListener('DOMContentLoaded', function () {
const toggleBtn = document.getElementById('master-toggle');

toggleBtn.addEventListener('click', function () {
const action = this.getAttribute('data-action');
const headers = document.querySelectorAll('.accordion');

headers.forEach(header => {
const isActive = header.classList.contains('active');
const panel = header.nextElementSibling; // Grabs the corresponding .panel container

if (action === 'expand' && !isActive) {
// Open it by simulating a standard click
header.click();
} else if (action === 'collapse' && isActive) {
// Close it by simulating a standard click
header.click();
}
});

// Flip button text and states
if (action === 'expand') {
this.setAttribute('data-action', 'collapse');
this.textContent = 'Collapse all tabs';
} else {
this.setAttribute('data-action', 'expand');
this.textContent = 'Expand all tabs';
}
});
});
</script><div class="accordion"><strong>The AI agent doesn’t respond to questions</strong></div><div class="panel">
<h3 id="h_01KW1YN6KFRQWFG6WKGEY165RB">Common causes of a lack of replies from your AI agent</h3>
<ul>
<li data-list-item-id="eebe13e4336254fcd22378b32ba76b760">The agent isn’t connected to the channel</li>
<li data-list-item-id="e2d44f9fe58c261c78449d54896223c22">Articles or sources are unpublished or inaccessible</li>
<li data-list-item-id="e8a6c9880541a3ee9694220c04701f9bb">The language isn't active</li>
<li data-list-item-id="e94ae2b503abe2c65820a5f4c635e7c4c">A setup or integration step is incomplete</li>
</ul>
<h3 id="h_01KW1YNQPJ2JVCN59XFPN9ERST">To resolve this issue:</h3>
<ol>
<li data-list-item-id="e6b4a8bc74e214973204be2a9d1f85da0">Confirm the agent is enabled, assigned to the correct channel, and connected to the right knowledge source. For more information, see: <a href="https://support.zendesk.com/hc/en-us/articles/8357749659034-Troubleshooting-ticket-automation-in-AI-agents" target="_blank" rel="noopener noreferrer">Troubleshooting ticket automation in AI agents</a> and <a href="https://support.zendesk.com/hc/en-us/articles/8357749580186-Reviewing-conversation-logs-for-AI-agents" target="_blank" rel="noopener noreferrer">Reviewing conversation logs for AI agents</a>.</li>
<li data-list-item-id="e43a7b7dcd3f949ff63f6e9291374c8fd">Check whether the <a href="https://support.zendesk.com/hc/en-us/articles/8357756692890-Configuring-language-detection-for-AI-agents" target="_blank" rel="noopener noreferrer">language</a> is active and supported</li>
</ol>
</div><div class="accordion"><strong>The AI agent replies when it should hand off</strong></div><div class="panel">
<h3 id="h_01KW1Z2P836S5APTJ5804SA4P4">Common causes</h3>
<ul>
<li data-list-item-id="efa8d5858d885bb63f6407b03e4aa2a46">The fallback logic is too permissive</li>
<li data-list-item-id="e97dc137482a10d3c042f86473ee3d0ce">The procedure routes all ambiguous cases through the AI response step</li>
<li data-list-item-id="e09d593e34a5479b7588dfd65f9e2f612">Knowledge content is too broad to trigger a clean handoff</li>
</ul>
<h3 id="h_01KW1Z2P84VS6JPF0B853VQBYF">To resolve this issue:</h3>
<ol>
<li data-list-item-id="eb3e5ba216886089c98a45eb3f591fc50">Review your <a href="https://support.zendesk.com/hc/en-us/articles/8357756604186-Configuring-escalation-strategies-and-flows-for-AI-agents" target="_blank" rel="noopener noreferrer">escalation strategies and flows</a>
</li>
<li data-list-item-id="e0ec4e3153985e124d1df287caf45ea01">Verify your fallback behavior, and confidence or <a href="https://support.zendesk.com/hc/en-us/articles/8357749659034-Troubleshooting-ticket-automation-in-AI-agents" target="_blank" rel="noopener noreferrer">routing logic</a>
</li>
<li data-list-item-id="ea7cd55e3f542ced1afd41e1a02df2a38">Test with weak-match examples</li>
</ol>
</div><div class="accordion"><strong>The AI agent escalates too early or shows a technical error</strong></div><div class="panel">
<h3 id="h_01KW1Z2P84TJGAEAGZFZPRQSP3">Common causes</h3>
<ul>
<li data-list-item-id="ef5c060ee361b901a7aeb0220ffc38c7c">Inputs are missing or malformed</li>
<li data-list-item-id="ecbb2b9ff2a49d1a3905ea743e66e70f7">Flow logic doesn’t handle edge cases well</li>
<li data-list-item-id="e7a4afb6c2d208e0a8e6bf2ff653137ce">Integration errors or parameter mismatches</li>
<li data-list-item-id="eadb54b304fee1f2fb287b6eb3fdd5bf7">An unhandled condition in the procedure</li>
</ul>
<h3 id="h_01KW1Z2P84Z762H9YEKKRKPFC3">To resolve this issue:</h3>
<ol>
<li data-list-item-id="e3376e92d99607e580c1bde8100032073">Check your required parameters and fallback handling</li>
<li data-list-item-id="e34fa238af02913aa41c98770050dc57b">Test the integration in the integration builder and check that the request parameters match</li>
<li data-list-item-id="eb76518ae99e351ac849184b3e27992ad">Check the HTTP status code</li>
<li data-list-item-id="eb2dbc6778a83818410b28dc332ef88a8">Investigate any technical errors in the dialogue</li>
<li data-list-item-id="e335bc56d2c9333cf620b4baebe37e7c0">Verify the <a href="https://support.zendesk.com/hc/en-us/articles/8357749580186-Reviewing-conversation-logs-for-AI-agents" target="_blank" rel="noopener noreferrer">conversation logs</a> for differences between successful and failed cases</li>
</ol>
<p>For more information, see: <a href="https://support.zendesk.com/hc/en-us/articles/8919342194074-Troubleshooting-an-integration-for-AI-agents" target="_blank" rel="noopener noreferrer">Troubleshooting an integration for AI agents</a>.</p>
</div><div class="accordion"><strong>Knowledge sources are missing, incomplete, or inconsistent</strong></div><div class="panel">
<h3 id="h_01KW1Z2P84Z47C3FDXCQX6SSZA">Common causes</h3>
<ul>
<li data-list-item-id="eb7af910a0fcd351f4ce64d5346300f4d">The help center is not active and published</li>
<li data-list-item-id="e0a798482b540b1ad270f22a70343010b">Articles are unpublished or their <strong>Visible to</strong> field does not allow customers and the AI agent to access the content</li>
<li data-list-item-id="e82f9daf7b2467a42da2d3d6197daa13a">The source was not imported correctly</li>
<li data-list-item-id="ec77a9e9ab7e9c77e65f2911afbbca8b0">Different instances are on different rollout states. The feature is gated or not yet available everywhere. Search rules are not logical, labels are missing, or incorrect operators are used.</li>
</ul>
<h3 id="h_01KW1Z2P84RRRVSDGNV08KFTGX">To resolve this issue:</h3>
<ol>
<li data-list-item-id="e6c0a39d53c49720a3336e286648ed7ae">If you use articles from the Zendesk help center, ensure that the help center is active and published</li>
<li data-list-item-id="ec347255a68dd50abc3c5f3470a68a5f1">Ensure that article settings are <a href="https://support.zendesk.com/hc/en-us/articles/4408839258778-Creating-articles-in-the-knowledge-base#topic_ngr_25x_cfc" target="_blank" rel="noopener noreferrer">published</a> and the <strong>Placement</strong> &gt; <strong>Visible to</strong> <a href="https://support.zendesk.com/hc/en-us/articles/4408839258778-Creating-articles-in-the-knowledge-base#topic_ngr_25x_cfc#topic_bpt_tdq_cy" target="_blank" rel="noopener noreferrer">field</a> is set to <strong>Everyone</strong>
</li>
<li data-list-item-id="e03b02ca4f3e309a7ea47690e22992260">Confirm the <a href="https://support.zendesk.com/hc/en-us/articles/10791195957530-Importing-knowledge-sources-to-power-generative-replies-in-AI-agents-AI-agents-Advanced-only" target="_blank" rel="noopener noreferrer">knowledge sources</a> were added in the right place, imported successfully, and are accessible to the AI agent. Verify <a href="https://support.zendesk.com/hc/en-us/articles/9962106058906-Managing-imported-knowledge-sources-for-AI-agents-AI-agents-Advanced-only" target="_blank" rel="noopener noreferrer">imported knowledge sources for AI agents</a>.</li>
<li data-list-item-id="e3df3357f34cda0986d27fae017f2427c">Verify if the crawl failed because it timed out, is missing pages, or the crawl includes the right pages but the wrong content. <a href="https://support.zendesk.com/hc/en-us/articles/9961828111258-Troubleshooting-issues-with-web-crawler-imports-for-AI-agents-AI-agents-Advanced-only" target="_blank" rel="noopener noreferrer">Troubleshooting issues with web crawler imports for AI agents</a> and <a href="https://support.zendesk.com/hc/en-us/articles/4593564000410-Using-a-web-crawler-to-index-external-content" target="_blank" rel="noopener noreferrer">Using a web crawler to index external content</a>.</li>
<li data-list-item-id="e298b41123885a7752a5261fb4f83e012">Compare <a href="https://support.zendesk.com/hc/en-us/articles/9185497386394-Configuring-search-rules-for-knowledge-sources-for-AI-agents" target="_blank" rel="noopener noreferrer">configuration search rules</a> between instances. <a href="https://support.zendesk.com/hc/en-us/articles/9962106058906-Managing-imported-knowledge-sources-for-AI-agents-AI-agents-Advanced-only" target="_blank" rel="noopener noreferrer">for AI agents Advanced only</a>
</li>
<li data-list-item-id="e5b4b1b2190abd075f522f70cec69df0e">Check for restricted articles and where the end user does not have access</li>
</ol>
</div><div class="accordion"><strong>The AI agent behaves differently by language</strong></div><div class="panel">
<h3 id="h_01KW1Z2P84FHPGEWHQXV7T9HHG">Common causes of multiple responses for each language</h3>
<ul>
<li data-list-item-id="e41d071ec2461416a9bf861db64943aad">The language hasn’t been activated</li>
<li data-list-item-id="eb7bb15dd02b0868e730df2dbe86c82fe">The agent is falling back because it can’t detect or serve the target language</li>
<li data-list-item-id="e2b6b6f17e9890528ad400d2d13e8ef2c">The content exists, but not in the expected language</li>
</ul>
<h3 id="h_01KW1Z2P844TK9T56P8PSB3K2X">To resolve this issue:</h3>
<ol>
<li data-list-item-id="e9db7a4b4e6a144894eeef1c3fc3fbb44">Confirm that the <a href="https://support.zendesk.com/hc/en-us/articles/8357749666714-Adding-and-managing-supported-languages-for-AI-agents-AI-agents-Advanced-only" target="_blank" rel="noopener noreferrer">target language</a> is activated</li>
<li data-list-item-id="e50d9e300a4a949e09a7ddf526f77dd97">
<a href="https://support.zendesk.com/hc/en-us/articles/8357756692890-Configuring-language-detection-for-AI-agents" target="_blank" rel="noopener noreferrer">Language detection</a> is configured</li>
<li data-list-item-id="e4a439511ad7178cbe8c1c2b5a9c0c925">Content exists in the correct language</li>
</ol>
</div><div class="accordion"><strong>The AI agent integration is failing</strong></div><div class="panel">
<h3 id="h_01KW1Z2P848Q9P1414V2SBDA35">Common causes of a failed app integration with AI agents</h3>
<ul>
<li data-list-item-id="ea278ec81f28db8e7dd4e8664d28c3653">Invalid credentials</li>
<li data-list-item-id="eacbeb1a8edb10289dd4cef250eb5a897">Unsupported payload format</li>
<li data-list-item-id="e8fc7540515a76bf1961ef4f1a45985f5">Endpoint or mapping errors</li>
<li data-list-item-id="e69e72a047ab9e416b98f0b8c3538f6d6">External system timeout or failure</li>
</ul>
<h3 id="h_01KW1Z2P844MZ6Z790ZQ5K0ZMT">To resolve this issue:</h3>
<ol>
<li data-list-item-id="e27f06c32068f0c31b618f3260591cc9e">Check the connection</li>
<li data-list-item-id="ef31a300e09f3e5a312afecf4a1b45a76">Verify the authentication and conversation logs</li>
<li data-list-item-id="efbe89bda317a2732f1f6f1a06ba14f35">Test the integration in the integration builder</li>
<li data-list-item-id="e951c12646ca3ed01162d02303ece43f6">Check that the request parameters match and the HTTP status code</li>
<li data-list-item-id="e344d686be3e05d0c60ab1ef69158ac9b">Investigate any technical errors in the dialogue</li>
<li data-list-item-id="eebff38e7d5ce24795f73b4e468cfd08e">Test the integration in the builder if available</li>
</ol>
<p>For full steps to follow, see: <a href="https://support.zendesk.com/hc/en-us/articles/8919342194074-Troubleshooting-an-integration-for-AI-agents" target="_blank" rel="noopener noreferrer">Troubleshooting an integration for AI agents</a>.</p>
<h3 id="h_01KW20GEQP41AEESCQJB85GBSR">Common causes of a failed Customer Relationship Management (CRM) connectivity</h3>
<ul>
<li data-list-item-id="ee02260870e7c3149152878d2509ef3d0">The bot doesn’t join conversations</li>
<li data-list-item-id="e066d7428cf0e4de5ec28449f032be1b7">Escalations to agents fail</li>
<li data-list-item-id="ec28a1ae1d9a15d880c6b0ce0a2bade37">Tagging errors occur during CRM-based flow handling</li>
</ul>
<h3 id="h_01KW20GEQP7MJFZ0C2JJYKE9C4">To resolve this issue:</h3>
<ol>
<li data-list-item-id="ecfe26aaa99c358ce4b75e2e27e255f71">Verify whether the bot joins conversations</li>
<li data-list-item-id="e442af1e2b36fe30505da55587a93afd4">Ensure that agent escalations and human hand offs succeed</li>
<li data-list-item-id="e574380ffdfd8ab0ebfc40844034fd5cc">Verify if tags are applied correctly</li>
</ol>
<p>For full steps to follow, see <a href="https://support.zendesk.com/hc/en-us/articles/8357749715098-Troubleshooting-CRM-connection-with-AI-agents" target="_blank" rel="noopener noreferrer">Troubleshooting CRM connection with AI agents</a>.</p>
</div><div class="accordion"><strong>The ticket doesn’t close or the AI agent doesn’t trigger</strong></div><div class="panel">
<p>The most frequent issue involves mandatory fields in the customer relationship management (CRM) tool. Check the following:</p>
<ul>
<li data-list-item-id="e7d8a6afa5af5b8629a3f929e57c9d676">If no action updates the mandatory CRM fields, review the conversation logs, dialogue, and actions to verify that all required actions have been created.</li>
<li data-list-item-id="eb0d03080fbaf2c9276e1d49fc781710e">If the wrong parameter type was selected, such as Boolean or integer instead of string, update the corresponding action.</li>
<li data-list-item-id="eea190e8f90b6e0c2b05455e53517e6cf">If a processing error occurred, check the error logs.</li>
<li data-list-item-id="e92f2547a5d3df5e88d42675684bffea3">If the actions are in the wrong order, adjust their order so that all fields are updated before the ticket is closed.</li>
</ul>
</div><div class="accordion"><strong>The AI agent routes a successful API call to the failure branch</strong></div><div class="panel">
<h3 id="h_01M0ESKA73KH7WVG0Y7R36YHT6">Common causes of an AI agent routing a successful API call to the failure branch</h3>
<ul>
<li data-list-item-id="ecfb57d2b00c261ad5a13a7ce72e10f30">The integration response includes a successful status code, but the AI agent can’t interpret one or more returned values as expected</li>
<li data-list-item-id="ee4432417b12c1073ac55e63ba86cdad8">A required session parameter or output field is missing a clear description or is mapped incorrectly</li>
<li data-list-item-id="ebcce96ddabd8365abf7b75f3046aae88">The AI agent expects a specific value, object, or data type from the integration, but receives an empty value or a different format instead</li>
<li data-list-item-id="e73c4f1f4dc21bdccc08b4c4d28bfca7d">In sandbox environments, the use case may reference a different integration than the one you tested</li>
</ul>
<h3 id="h_01M0ESKA73FS1GCTBBTXMJ8QDY">To resolve this issue:</h3>
<ol>
<li data-list-item-id="e56069b1e99ad8a31cfb98bee31908781">Review the integration output and confirm that all expected response fields are returned in the format your AI agent procedure expects.</li>
<li data-list-item-id="eca8237a09a0c1f2a88bacea706222e53">Check that session parameters, including status code fields and other mapped outputs, are configured clearly and consistently.</li>
<li data-list-item-id="e0f59ef561c3e443a483e003a81e86864">Verify that any values used in procedure branching are present and use the correct type, such as text, number, object, or array.</li>
<li data-list-item-id="ecaf41d129b12c20919f9630fb4e94333">If you are testing in a sandbox, confirm that your use case points to the integration configured in that same sandbox environment.</li>
<li data-list-item-id="e2cde9f569e3e5e130a7f53ff11c79233">Compare a working example and a failing example in the conversation logs to identify differences in returned values or parameter mapping.</li>
<li data-list-item-id="e0aad2a9e6bc19d4edec8ee844882b370">Re-test the integration after updating mappings, parameter descriptions, or expected response values.</li>
</ol>
<p>If the API call succeeds but the AI agent still follows the failure path, the issue is often caused by response mapping or missing expected data rather than by the connection itself.</p>
</div><h2 id="h_01KW1YCYPCNMPC1PMCATFP5BAM">When to contact Zendesk Customer Support about AI agents</h2><p>Contact Zendesk Customer Support if:</p><ul>
<li data-list-item-id="e2a176fbde9d050d898a5af4e661dc67f">The issue persists after you carefully verify your configuration against this article</li>
<li data-list-item-id="ea29a8974062b0184b292ccf5e5656b0f">The behavior is inconsistent across instances</li>
<li data-list-item-id="ec3c5b137985e54bcb6e2710bb5148924">You can replicate the issue</li>
<li data-list-item-id="e561441cc6e4bd9dc61b9c5c93d7bc4b5">Logs show an error you can't resolve</li>
<li data-list-item-id="ef7e73a8dcd21ca6b207d32c9c41c2420">The issue appears to be a product bug or backend provisioning problem</li>
</ul><p>If you need help to submit a request, see <a href="https://support.zendesk.com/hc/en-us/articles/4408843597850-Contacting-Zendesk-customer-support" target="_blank" rel="noopener noreferrer">How to contact Customer Support</a>.</p><div><div><div><div><div dir="ltr"><div><div dir="ltr" data-test-id="guide-markup-preview">
<h2 id="h_01KW1YCYPCVP875F33J1WKVRYP">Before you contact Zendesk Customer Support</h2>
<p>Gather the following details to assist with our investigation:</p>
<ul>
<li data-list-item-id="e41126b95eab5ec707e05051ddbc163e7">Your <a href="https://support.zendesk.com/hc/en-us/articles/4409381383578-Where-can-I-find-my-Zendesk-subdomain" target="_blank" rel="noopener noreferrer">Zendesk subdomain or URL</a>
</li>
<li data-list-item-id="ed3874d126af01c2ced388bdd825a30db">The AI agent name</li>
<li data-list-item-id="e17b8a8688d1b9ad95795a34c115e67cc">Channel</li>
<li data-list-item-id="e78e891f1ed7d7200b8c11c0bcefcedb0">Conversation or ticket ID</li>
<li data-list-item-id="edd824812d6f60fc677a5a36f29a31608">Time of the issue</li>
<li data-list-item-id="e442d402c2dddd9396775faa0196c64e9">Steps to reproduce</li>
<li data-list-item-id="e3764d6d49ffbb277fcbbf829bad6ffc0">Screenshots or screen recording</li>
<li data-list-item-id="e3db280f0366fcbfb855389c4f8a0014d">Relevant conversation logs</li>
<li data-list-item-id="ee0ccd2ccae5f0c191c32165de460337c">Any related integration details</li>
</ul>
<h4 id="h_01KVZ0HXXF53JMFWSD0J6XSJBA">Additional articles</h4>
<ul>
<li data-list-item-id="e35b64958adfe87754765757797fe5bd4"><a href="https://support.zendesk.com/hc/en-us/articles/8357756604186-Configuring-escalation-strategies-and-flows-for-AI-agents" target="_blank" rel="noopener noreferrer"><span class="wysiwyg-underline">Configuring escalation strategies and flows for AI agents</span></a></li>
<li data-list-item-id="e896cf35acee6114bbbb612c48f2cc118"><a href="https://support.zendesk.com/hc/en-us/articles/8357756692890-Configuring-language-detection-for-AI-agents" target="_blank" rel="noopener noreferrer"><span class="wysiwyg-underline">Configuring language detection for AI agents</span></a></li>
<li data-list-item-id="ea70222835c9e57bbdf10c02c3a27553c"><a href="https://support.zendesk.com/hc/en-us/articles/8357749580186-Reviewing-conversation-logs-for-AI-agents" target="_blank" rel="noopener noreferrer"><span class="wysiwyg-underline">Reviewing conversation logs for AI agents</span></a></li>
<li data-list-item-id="e1482863c0994969c539e711c73113356"><a href="https://support.zendesk.com/hc/en-us/articles/8919342194074-Troubleshooting-an-integration-for-AI-agents" target="_blank" rel="noopener noreferrer"><span class="wysiwyg-underline">Troubleshooting an integration for AI agents</span></a></li>
<li data-list-item-id="e3a3dbb114fb6bea3cfe473ce701eb43d"><a href="https://support.zendesk.com/hc/en-us/articles/8357749715098-Troubleshooting-CRM-connection-with-AI-agents" target="_blank" rel="noopener noreferrer"><span class="wysiwyg-underline">Troubleshooting CRM connection with AI agents</span></a></li>
<li data-list-item-id="e1f5945d05d05c86f921a0e10cb6d6ae5">
<a href="https://support.zendesk.com/hc/en-us/articles/9961828111258-Troubleshooting-issues-with-web-crawler-imports-for-AI-agents-AI-agents-Advanced-only" target="_blank" rel="noopener noreferrer"><span class="wysiwyg-underline">Troubleshooting issues with web crawler imports for AI agents (AI agents - Advanced only)</span></a> <a href="href"></a>
</li>
</ul>
</div></div></div></div></div></div></div>