Troubleshoot an agent
Diagnose and fix an agent that's giving wrong or unhelpful answers.
Advanced · ~10 min · Prerequisites: a published agent
Building and editing agents is admin-only. Members can run and observe agents, but only admins can create or change them.
What you'll do
Work through a structured sequence — test panel, instructions, tools, version history — to find the root cause of a misbehaving agent and fix it without guesswork.
Reproduce in the test panel
Before changing anything, reproduce the problem in a controlled environment. Open the builder at /admin/agents/<slug>/edit and click the test panel icon to open the test chat on the right side.
Send the exact prompt (or as close as you can reconstruct) that produced the bad result. Confirm the problem is reproducible — if it only happens occasionally, try a few variations. The test panel is isolated from member history and analytics, so you can iterate freely here without affecting what members see.
For guidance on what the test panel shows and how to interpret its output, see Testing an agent.
Check instructions first
Most agent problems are prompt problems. Before suspecting the model or tools, read through the Instructions section carefully with the failing case in mind:
- Missing coverage. Does the instruction set say anything about the topic or task the agent failed on? If not, add explicit guidance.
- Conflicting rules. Does the agent have two instructions that pull in opposite directions for this input? Resolve the conflict by making one rule more specific than the other.
- Vague boundaries. If the agent went off-topic, the instructions probably don't state clearly what falls outside its scope. Add a "do not…" clause for the out-of-scope behavior.
- Formatting issues. If the content is correct but the structure is wrong (wrong length, wrong format), add a concrete output example to the instructions that shows what a good response looks like.
Make one change at a time and re-test after each change so you know which edit fixed the problem.
Check tools & permissions
If the agent is giving errors, calling the wrong tool, or failing to take an action it should:
- Open the Tools section in the builder and confirm the right tools are enabled for this agent's role. An agent with too many tools can pick the wrong one; an agent missing a tool will try to work around it with text.
- Check whether the tool call itself is failing — the test panel surfaces tool errors inline. If a Composio action is failing, confirm the connected app is still authorized under your org's connectors (see Tools & integrations).
- Review the instructions for language that tells the agent when to use each tool. If there's no explicit guidance, the agent guesses — and often guesses wrong for edge cases.
- Check Permissions to confirm the agent has access to the actions it needs and isn't being blocked by a guardrail.
Roll back if a recent publish broke it
If the agent was working correctly before a recent publish and the problem started immediately after, roll back rather than trying to diagnose the diff manually.
Open Version history in the builder, find the last version that worked, and restore it. This is faster than iterating on a broken draft — get members back to a working state first, then investigate the failed version's changes at your own pace.
See Version & roll back an agent for the step-by-step restore procedure.
If you can't pin down the root cause after checking instructions, tools, and version history, open analytics and look for the pattern of failures across real conversations — the breadth of the problem often points to the cause. See Analytics.