Agent Troubleshooting

When an AI agent doesn't behave as expected, there's usually a straightforward explanation. This guide covers the most common agent issues and how to fix them.

Agent Not Responding to @Mentions

Check if the Agent is Enabled

Agents can be disabled in their settings. Go to the agent's profile and verify it's active.

Check the Agent's Skills

If an agent has no tool skills attached, it may not have the capabilities to handle your request. Verify skills are attached in the agent's settings.

Check Your Plan

Some agent features require the Pro plan or higher. If you're on the Starter plan, you're limited to 2 agents.

Channel Permissions

Agents can only respond in channels they have access to. If the agent isn't responding in a specific channel, check whether it's a private channel that the agent hasn't been added to.

Agent Giving Wrong or Irrelevant Answers

Refine the System Prompt

The system prompt shapes how an agent thinks and responds. If answers are off-target:
- Be more specific about the agent's role and expertise
- Add constraints ("Never make up statistics", "Always cite sources")
- Include domain context ("Our product is a B2B SaaS tool for HR teams")

Adjust Temperature

• Lower temperature (0.3) for factual, consistent responses
• Higher temperature (0.8) for creative, varied responses
• Default is 0.7, which balances both

Provide Better Context in Your Message

Agents work with the context you give them. Instead of "write a report," try "write a Q2 revenue report comparing against Q1, focusing on enterprise customers, using data from the Sales Dashboard."

Check Context Window

Very long conversations can push important context out of the agent's working memory. Start a new thread for distinct topics rather than continuing a very long conversation.

Agent Tool Errors

"Tool execution failed"

This usually means:
- Connector not configured — The agent tried to use a tool that requires a connector (e.g., GitHub) that hasn't been set up. Go to Settings > Connectors to configure it.
- Permissions insufficient — The connector's OAuth token may have expired. Re-authenticate the connector.
- Rate limited — External APIs sometimes throttle requests. Wait a moment and try again.

Agent Creates Wrong Resources

If an agent creates tasks or documents with incorrect information:
- Iterate in the thread: "That's not right — the due date should be Friday, not Monday"
- The agent will learn from corrections within the conversation
- For persistent issues, update the agent's system prompt with specific instructions

Agent Memory Issues

Stale or Incorrect Memories

Agents save facts from conversations that persist across sessions. If an agent is acting on outdated information:

@Agent recall what you remember about our pricing structure

Review the memories and correct any that are wrong:

@Agent our pricing changed last month — the Pro plan is now $29/month, 
not $25. Please update your memory.

Agent Forgetting Context Between Conversations

Agent memory is selective — it saves what it determines is important. If something critical keeps getting forgotten, explicitly ask the agent to save it:

@Agent save this to memory: our fiscal year starts in April, 
not January. All quarterly reports should use April as Q1 start.

"Waiting" Task State

When a task is in the "waiting" state, it means the agent (or someone else) is working on it but it's blocked or pending input. Common causes:
- Agent is executing a multi-step workflow
- Agent needs more information from you
- An external connector is processing

Check the task's discussion thread for updates from the agent about what it's waiting on.

Credit Exhaustion

If an agent stops mid-conversation, your workspace may have run out of AI credits:
- Check Settings > Billing for your credit balance
- Purchase a credit top-up to continue immediately
- Credits reset at each billing cycle

Still Stuck?

• Review the agent's activity in the admin panel (workspace owners)
• Check the What Are AI Agents? guide for foundational understanding
• See Building Custom Agents for configuration best practices