Troubleshooting

Running into issues with your agent? This page covers the most common problems and how to fix them. Most issues come down to configuration — a quick adjustment usually gets things back on track.

Agent not responding

If your agent isn't replying when you send a message:

• Check the agent's status. Make sure the agent is active and hasn't been paused or disabled.
• Refresh the page. Occasionally, a temporary connection issue can cause messages to appear stuck. A refresh usually resolves it.
• Review the instructions. If the instructions are contradictory or unclear, the agent may struggle to generate a response. Simplify and clarify them.

Agent giving wrong or unhelpful answers

If your agent responds but the answers aren't useful:

• Tighten the instructions. Vague instructions lead to vague answers. Be specific about what the agent should do, what sources it should reference, and how it should format responses.
• Check knowledge connections. If the agent is supposed to reference specific documents, make sure those documents are actually connected in the Knowledge tab. Missing knowledge is the most common reason for inaccurate answers.
• Reduce the tool set. Too many tools can confuse the agent about which one to use. Disable tools that aren't relevant to the agent's role.

Tools not working

If your agent has tools enabled but doesn't seem to use them:

• Verify the tool is toggled on. Open the Tools tab and confirm the tool you expect is actually enabled.
• Test with a direct request. Ask the agent to explicitly use the tool — for example, "Search the knowledge base for our refund policy." If it works with a direct request but not naturally, the instructions may need to mention when to use the tool.
• Check permissions. Some tools require specific access rights. Make sure the agent has the necessary permissions for the connected services.

Schedule not running

If a scheduled task isn't executing when expected:

• Check the schedule is active. Open the Scheduling tab and confirm the toggle is on.
• Verify the frequency settings. Double-check the day, time, and interval. A common mistake is setting a weekly task for the wrong day.
• Review recent run history. Look at the run log to see if the task ran and failed, or if it didn't run at all. A failed run usually includes an error message that points to the issue.

Permission denied errors

If a team member can't access an agent:

• Check the Permissions tab. Confirm the person (or their team) is listed with the right access level.
• Verify organization membership. The person must be a member of your Opisense organization to access any agents.
• Check the access level. Remember that Users can chat with the agent but can't change settings. Managers can do both. Make sure the right level is assigned.

Still stuck?

If none of the above solves your issue:

1. Try clearing the agent's memory and starting a fresh conversation
2. Check the Opisense status page to see if there's a known service issue
3. Reach out to support through the Help section in the sidebar