Troubleshooting common issues with AI agents

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. Preliminary AI agent troubleshooting questions

Is the AI agent enabled and assigned to the right channel? see
Creating an AI agent to automatically resolve customer issues.


Are relevant articles, knowledge sources, or integrations published
and available to your customers? see
Troubleshooting ticket automation in AI agents
and
Optimizing your knowledge content for generative AI.


Is the
correct language
activated and supported?


Have you reviewed the
conversation logs
for errors, escalation, or
no response?



Note: When you answer those questions,
you know whether you face
a configuration issue, a content issue, a channel, or a language
issue, or something that needs Zendesk Customer Support.


When you follow the advice above, review common issues below:

Expand all tabs



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';
}
});
});
The AI agent doesn’t respond to questions
Common causes to a lack of replies from your AI agent

The agent isn’t connected to the channel
Articles or sources are unpublished or inaccessible
The language isn't active
A setup or integration step is incomplete

To resolve this issue:

Confirm the agent is enabled, assigned to the correct channel, and connected to the right knowledge source. For more information, see Troubleshooting ticket automation in AI agents and Reviewing conversation logs for AI agents.
Check whether the language is active and supported

AI agent replies when it should hand off
Common causes

The fallback logic is too permissive
The procedure routes all ambiguous cases through the AI response step
Knowledge content is too broad to trigger a clean handoff

To resolve this issue:

Review your escalation strategies and flows

Verify your fallback behavior, and confidence or routing logic

Test with weak-match examples

AI agent escalates too early or shows a technical error
Common causes

Inputs are missing or malformed
Flow logic doesn’t handle edge cases well
Integration errors or parameter mismatches
An unhandled condition in the procedure

To resolve this issue:

Check your required parameters and fallback handling
Test the integration in the integration builder and check that the request parameters match
Check the HTTP status code
Investigate any technical errors in the dialogue
Verify the conversation logs for differences between successful and failed cases

For more information, see Troubleshooting an integration for AI agents.
Knowledge sources are missing, incomplete, or inconsistent
Common causes

The help center is not active and published
Articles are unpublished or their Visible to field does not allow customers and the AI agent to access the content
The source was not imported correctly
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.

To resolve this issue:

If you use articles from the Zendesk help center, ensure that the help center is active and published
Ensure that article settings are published and the Placement > Visible to field is set to Everyone

Confirm the knowledge sources were added in the right place, imported successfully, and is accessible to the AI agent. Verify imported knowledge sources for AI agents.
Verify if the crawl failed because it timed out, is missing pages, or the crawl includes the right pages but the wrong content. see Troubleshooting issues with web crawler imports for AI agents and Using a web crawler to index external content.
Compare configuration search rules between instances. for AI agents Advanced only

Check for restricted articles and where the end user does not have access

AI agent behaves differently by language
Common causes to multiple responses for each language

The language hasn’t been activated
The agent is falling back because it can’t detect or serve the target language
The content exists, but not in the expected language

To resolve this issue:

Confirm that the target language is activated

Language detection is configured
Content exists in the correct language

AI agent integration is failing
Common causes to a failed app integration with AI agents

Invalid credentials
Unsupported payload format
Endpoint or mapping errors
External system timeout or failure

To resolve this issue:

Check the connection
Verify the authentication and conversation logs
Test the integration in the integration builder
Check that the request parameters match and the HTTP status code
Investigate any technical errors in the dialogue
Test the integration in the builder if available

For full steps to follow, see Troubleshooting an integration for AI agents.

Common causes to a failed CRM connectivity

The bot doesn’t join conversations
Escalations to agents fail
Tagging errors occur during CRM-based flow handling

To resolve this issue:

Verify whether the bot joins conversations
Ensure that agent escalations and human hand offs succeed
Verify if tags are applied correctly

For full steps to follow, see Troubleshooting CRM connection with AI agents.
When to contact Zendesk Customer Support about AI agents Contact Zendesk Customer Support if:
The issue persists after you carefully verify your configuration against this article
The behavior is inconsistent across instances
You can replicate the issue
Logs show an error you can't resolve
The issue appears to be a product bug or backend provisioning problem
If you need help to submit a request, see How to contact Customer Support.
Before you contact Zendesk Customer Support
Gather the following details to assist with our investigation:

Your Zendesk subdomain or URL

The AI agent name
Channel
Conversation or ticket ID
Time of the issue
Steps to reproduce
Screenshots or screen recording
Relevant conversation logs
Any related integration details

Additional articles

Troubleshooting ticket automation in AI agents
Configuring escalation strategies and flows for AI agents
Configuring language detection for AI agents
Reviewing conversation logs for AI agents
Troubleshooting an integration for AI agents
Troubleshooting CRM connection with AI agents

Troubleshooting issues with web crawler imports for AI agents (AI agents - Advanced only)


