Agent Issues

This guide helps you diagnose and resolve common agent-related problems.

Agent not responding

Symptoms: You send a message and nothing happens, or you see an error message. Possible causes and fixes:

AI model service issue — The underlying AI model may be temporarily unavailable. Wait a minute and try again.
Agent configuration error — The agent may have an invalid configuration. An administrator should check the agent’s settings in the Agents page.
Tool failure — A tool the agent is trying to use may be failing. Check toolkit connections in the admin panel.

Symptoms: The agent takes a long time before text starts appearing. Possible causes and fixes:

Complex tool usage — If the agent is searching knowledge bases, calling external tools, or executing code, each step adds time. This is normal behavior.
Large context — Long conversations with many messages create a larger context for the model to process. Start a new conversation if the current one has become very long.
Model selection — More capable models (reasoning models, larger models) can be slower. An administrator can try a faster model if speed is a priority.
Server load — During peak usage, response times may increase.

Symptoms: The agent provides incorrect information, ignores your question, or goes off-topic. Possible causes and fixes:

Missing knowledge — The relevant documents may not be in the connected knowledge base. Check that the KB contains the information and that it’s been indexed.
Poor system prompt — The agent’s instructions may not be clear enough. An administrator should review and refine the system prompt.
Wrong agent — You may be chatting with an agent that isn’t designed for your question type. Try selecting a different agent.
Strict mode — If the agent is in strict mode and can’t find relevant documents, it will decline to answer rather than guess.
Outdated documents — The knowledge base may contain outdated information. Verify documents are current.

Symptoms: The agent responds but doesn’t cite any sources, even for questions that should match documents. Possible causes and fixes:

Knowledge search not enabled — Verify the agent has the knowledge search tool enabled.
No knowledge base connected — Verify at least one KB is connected to the agent.
KB not indexed — Check the knowledge base’s indexing status — documents may still be processing.
KB access control — You may not have access to the KB. Check your group memberships.
Query mismatch — Your question may not match the documents well. Try rephrasing.

If issues persist after troubleshooting: