Troubleshooting

1. Identify the symptom
   ↓
2. Isolate the component
   (Configuration? Knowledge? Tools? Conversation?)
   ↓
3. Test in isolation
   (Test just that component)
   ↓
4. Check the basics
   (Is it enabled? Saved? Loaded?)
   ↓
5. Review recent changes
   (What was modified last?)
   ↓
6. Apply fix
   ↓
7. Verify fix works

✓ Did you click "Save" after making changes?
✓ Did you start a new conversation to test changes?
✓ Are all files finished processing?
✓ Are all tools/integrations still connected?
✓ Is the agent set to public/private correctly?
✓ Did you test with a clear, specific request?
✓ Is your internet connection stable?

1. Go to Introduction tab
2. Check your system instructions are there
3. Click "Save Introduction Details" again
4. Wait for confirmation message

1. Start a brand new conversation
2. Test with a sample question
3. Check if behavior changed

Temporarily replace system instructions with:

"You are a test agent. When users say hello, respond
with 'SYSTEM INSTRUCTIONS WORKING' in all caps."

Save, start new conversation, say "hello"
- If you get the response → System instructions work, original prompt was the issue
- If you don't → Deeper technical issue

1. Verify changes saved:
   - Go to Introduction / Sample Questions tab
   - Confirm your text is there
   - Click save again

2. Clear browser cache:
   - Refresh page (Cmd+Shift+R or Ctrl+Shift+R)
   - Or clear browser cache completely

3. Start new conversation:
   - Don't reuse old conversation
   - Click "New Chat" or equivalent
   - Welcome message should update

Don't:
"Try to stay on topic about [domain]."

Do:
"ONLY respond to questions about [domain].

If users ask about anything else, respond exactly:
'I specialize in [domain]. I can't help with [their topic].
For general questions, try [alternative].'

Topics outside scope:
- [Topic 1]
- [Topic 2]
- [Topic 3]"

"Accuracy rules:
- NEVER make up information
- If you don't know, say: 'I don't have that information'
- Only use data from knowledge base or tool results
- When uncertain, acknowledge uncertainty explicitly"

1. Go to Training tab
2. Look at uploaded files
3. Check for:
   - Processing spinner (still working)
   -  Checkmark (successfully processed)
   -  Error icon (failed)

If stuck processing >5 minutes → refresh page or re-upload
If error → file may be corrupted or unsupported format

Ask: "What files are in your knowledge base?"
Or: "What do you know about [exact topic from your doc]?"

If agent doesn't mention your file → not successfully added
If it does mention it but retrieves wrong info → retrieval issue

Problem: Content isn't semantically matching

Solutions:
1. Restructure document with clear headings
2. Remove boilerplate/noise
3. Break large docs into focused pieces
4. Use descriptive file names
5. Add metadata headers

Example:
Instead of: "Document.pdf"
Use: "[POLICY] Customer Refund Policy - Updated 2024.pdf"

If you have 100+ documents:
- Too much content can dilute retrieval
- Remove less relevant docs
- Focus on highest quality sources

1. Audit knowledge base:
   - How many files? (>100 is a lot)
   - File sizes? (>10MB each is large)
   - Duplicate content?

2. Optimize:
   - Remove duplicates
   - Delete least-used sources
   - Split large files into smaller focused docs
   - Keep total under 50-75 high-quality sources

3. If must keep large knowledge base:
   - Consider multiple specialized agents instead of one
   - Use more targeted search prompts

1. Check for conflicts:
   - Do you have multiple docs on same topic?
   - Contradictory information?
   → Keep only most authoritative/current version

2. Improve structure:
   - Add clear section headers
   - Use bullet points and lists
   - Separate topics clearly

3. Remove outdated:
   - Delete old versions
   - Update changed information
   - Refresh URL-based knowledge

1. Go to Action Agents tab
2. Is the workflow checked?
3. Click "Save Action Agents Selection"
4. Start new conversation

Ask: "Use [exact workflow name] to [task]"

If called → Agent CAN use it, just doesn't know when
If not called → Configuration or connection issue

Do your system instructions mention the workflow?

Add:
"When users ask to [task], use the '[Workflow Name]' workflow.
Example: User says 'research Company X' → call 'Company Research' workflow"

Bad name: "Agent 1", "My Workflow"
Good name: "Company Research Tool", "Email Sender"

Rename workflow to be more descriptive

1. Go to the workflow agent itself
2. Run it manually
3. Does it complete successfully?

If workflow is broken, knowledge agent can't call it

1. Test workflow independently:
   - Run the workflow agent by itself
   - Does it work outside knowledge agent?
   - If no → fix the workflow first

2. Check data being passed:
   - What data is knowledge agent sending to workflow?
   - Does it match workflow's expected inputs?
   - Update system instructions to format data correctly

3. Check workflow requirements:
   - Does workflow need authentication?
   - API keys configured?
   - Rate limits hit?

4. Add error handling:
   System instructions:
   "If [Workflow Name] fails:
   1. Tell user what happened
   2. Offer alternative approach
   3. Don't keep retrying blindly"

1. Go to Integrations tab
2. Find the integration
3. Click "Disconnect"
4. Click "Connect" again
5. Complete OAuth flow
6. Verify "Connected" status

1. During OAuth, did you grant all needed permissions?
2. Some integrations need specific scopes
3. Re-connect and ensure all permissions granted

Ask agent: "Use [Integration] to [simple action]"
Example: "Use Slack to send a test message to #test"

If simple action works → complex use case is the issue
If simple action fails → integration configuration problem

Is the external service down?
- Check service status page (e.g., status.slack.com)
- Try accessing service directly in browser
- Wait and retry if service is down

1. Verify server is running:
   - Check server endpoint is accessible
   - Test server health endpoint
   - Review server logs

2. Check configuration:
   - Correct server URL?
   - Authentication credentials correct?
   - Network access allowed?

3. Review MCP server implementation:
   - Following MCP specification?
   - See [MCP Server docs](/mcp-server)

4. Test with minimal MCP server:
   - Create simple "hello world" MCP server
   - If that works → your custom server has issues
   - If that fails → MCP configuration in agent is wrong

1. Verify logged in:
   - Check if you see your account name
   - If not, sign in
   - Try conversation again

2. Check browser settings:
   - Not in incognito/private mode?
   - Cookies enabled?
   - Local storage enabled?

3. Try different browser:
   - Test in Chrome/Firefox/Safari
   - If works in one browser → original browser settings issue

1. Start new conversation:
   - Very long conversations (20+ turns) may hit limits
   - Fork or start fresh
   - Summarize what you need agent to remember

2. Keep conversations focused:
   - Don't jump between unrelated topics
   - One main task per conversation
   - Start new conversation for new topics

3. If happens in short conversations:
   - Report to support (this shouldn't happen)
   - Include conversation link

1. Verify link is complete:
   - Full URL including https://
   - No characters cut off
   - Copy link again fresh

2. Check conversation still exists:
   - Did you delete it?
   - Is agent still public?
   - Log in and view in your history

3. Check agent visibility:
   - Is knowledge agent set to public?
   - Private agents can't have public shared conversations

1. Refresh page (Cmd+R or Ctrl+R)

2. Clear browser cache

3. Log out and log back in

4. Try different browser

5. If persists → technical issue, contact support

Identify bottleneck:

1. Simple question, no tools/knowledge:
   - "Hello, how are you?"
   - Should be <3 seconds
   - If slow → platform performance issue

2. Knowledge retrieval:
   - Ask about knowledge base content
   - Should be 3-8 seconds
   - If slow → knowledge base too large

3. Tool calling:
   - Ask to use workflow
   - Timing = workflow execution time + overhead
   - If slow → workflow is slow or tool issue

4. Multiple tools:
   - Complex request with 3+ tools
   - Can take 30-60+ seconds (normal)
   - If >2 minutes → investigate individual tools

If knowledge base is slow:
- Reduce number of documents
- Remove large files
- Optimize document structure

If tools are slow:
- Optimize workflow agents (see workflow docs)
- Use faster integrations
- Reduce number of sequential tool calls

If platform is slow:
- Check status page
- Try during off-peak hours
- Report persistent issues to support

System instructions:

"Efficiency rules:
- Use minimum tools needed to complete task
- Don't call tools 'just in case'
- If 1 tool can do the job, don't call 3
- Ask yourself: 'Is this tool call necessary?'

Example:
User: 'What is Company X's website?'
L Bad: Call research tool, enrichment tool, database tool
 Good: Search knowledge base or call 1 research tool"

1. Add usage controls:
   System instructions:
   "Resource limits:
   - Max [N] tool calls per conversation
   - After limit: 'We've reached the tool usage limit.
     Start new conversation to continue.'"

2. Optimize tool usage:
   - Review system instructions
   - Are you calling tools unnecessarily?
   - Can you batch operations?

3. Use caching:
   - Store common queries in knowledge base
   - Reduce repeated API calls

4. Monitor usage:
   - Review conversation patterns
   - Identify expensive operations
   - Optimize or restrict those operations

Test prompt:
"Research Company X. After responding, explain:
1. What knowledge you retrieved
2. Which tools you called and why
3. How you decided what to do"

This reveals the agent's decision-making process.

System instructions (temporary):
"You can ONLY use your knowledge base. Do not call any tools.
If asked to do something requiring tools, say 'Tools disabled for testing.'"

Test: Does knowledge retrieval work?

System instructions (temporary):
"Ignore your knowledge base. Only use tools to answer questions."

Test: Do tools work correctly?

Remove all knowledge and tools temporarily.

Test: Does agent follow personality and boundaries?

Version A: Current (broken) configuration
Version B: Minimal working configuration

Compare:
- Which one works?
- What's different?
- Gradually add features from A to B until it breaks
- That feature is the culprit

1. Open browser developer tools (F12 or Cmd+Option+I)
2. Go to Console tab
3. Start conversation with agent
4. Look for error messages (red text)
5. Screenshot errors and report to support

1. Clear description of issue:
   "When I [action], I expect [result], but instead [actual result]"

2. Steps to reproduce:
   "1. Go to [location]
    2. Click [button]
    3. Error appears"

3. Screenshots:
   - Show the issue
   - Include any error messages
   - Show browser console if technical

4. Conversation link:
   - Share specific conversation where issue occurs
   - Helps support see exact problem

5. What you've tried:
   - List troubleshooting steps already attempted
   - Saves time ruling out common fixes

→ Test all sample questions work
→ Test all workflows individually
→ Test multi-workflow scenarios
→ Test with ambiguous requests
→ Test error scenarios (tool failures)
→ Review 5-10 test conversations
→ Check knowledge retrieval accuracy
→ Verify all integrations connected
→ Confirm no sensitive data in knowledge
→ Test shared conversation links work
→ Review system instructions for clarity
→ Check welcome message and prompt hint

→ Review 10-20 recent conversations
→ Check for new error patterns
→ Verify integrations still connected
→ Test 3-5 common scenarios

→ Full test suite run
→ Knowledge base audit
→ Review and update system instructions
→ Check for broken workflow agents
→ Update outdated information

→ Full regression testing
→ Compare before/after behavior
→ Review first 10 conversations post-change
→ Be ready to rollback if issues appear