Skip to main content

Troubleshooting Agents

At a glance​

This guide covers common Agent Studio issues: tool errors, incorrect responses, conversation timeouts, and configuration problems.

Conversation issues​

The agent does not respond​

Possible causes:

  • The LLM provider is unavailable
  • The provider API key is invalid or expired
  • The response timeout has been exceeded

Solutions:

  1. Check the LLM provider status in Agent Studio > Monitoring.
  2. Verify the provider API key in the workspace settings.
  3. Retry after a few moments — LLM providers may experience load spikes.

The agent gives incorrect responses​

Possible causes:

  • The system instructions are too vague
  • The agent does not have access to the right tools
  • The knowledge base context is insufficient

Solutions:

  1. Improve the agent's system instructions: be specific about the domain, tone, and boundaries.
  2. Check the enabled tools in Agent Studio > Your agent > Tools.
  3. Enrich the knowledge base with more relevant documents.
  4. Test with Viewer mode to see the agent's reasoning step by step.

The agent repeats the same response​

Cause: The model temperature is too low or the conversation history is too short.

Solutions:

  1. Slightly increase the temperature in the agent configuration.
  2. Check the context window size — a history that is too short can cause repetitions.

Tool errors​

"Tool unavailable"​

Possible causes:

  • The tool has been disabled or deleted
  • The agent does not have permission to use this tool

Solutions:

  1. Check the list of active tools in the agent configuration.
  2. Re-enable the tool if necessary.
  3. Verify the required scopes for the tool.

"Tool execution error"​

Possible causes:

  • The parameters provided to the tool are invalid
  • The data source called by the tool is unavailable
  • The tool has exceeded its timeout

Solutions:

  1. Check the error details in the Viewer (OODA loop).
  2. Verify that the data sources used by the tool are active.
  3. Retry — the agent may automatically correct the parameters on the next attempt.

The agent does not use the right tools​

Cause: The tool descriptions do not match the context of the question.

Solutions:

  1. Improve tool descriptions to be more explicit about their use cases.
  2. Add usage examples in the agent's system instructions.
  3. Verify that the agent has access to enough tools to cover the expected questions.

Performance issues​

Response too slow​

Possible causes:

  • The LLM model is overloaded
  • The agent is running too many tool loops
  • The knowledge base is large

Solutions:

  1. Use a faster model for simple questions (configurable in the agent settings).
  2. Limit the number of tool iterations in the configuration.
  3. Optimize the knowledge base by segmenting documents by domain.

"Conversation expired"​

Cause: The conversation has exceeded the maximum allowed duration.

Solution: Rephrase your question more precisely so that the agent can respond in fewer steps.

Configuration issues​

The agent does not see ontology entities​

Cause: The ontology search tool is not enabled.

Solution: Enable the ontologyContext and hybridSearch tools in the agent configuration.

The agent cannot find documents​

Cause: The documents have not been indexed in the knowledge base.

Solutions:

  1. Verify that the documents are imported in the Knowledge base.
  2. Wait for indexing to complete (visible in the document status).
  3. Enable the searchDocumentation tool in the agent configuration.

See also​

Need help?​

Contact us: Support and contact.