defi-agents

Troubleshooting Guide

Common issues and solutions for AI agent creation and usage.

Agent Behavior Issues

Agent Ignores Instructions

Symptoms:

Solutions:

  1. Make instructions more explicit
❌ "Be professional"
✅ "Use formal business tone. No contractions. Address as 'Dear [Name]'"
  1. Use numbered steps for processes
When responding:
1. First, acknowledge the request
2. Then, provide analysis
3. Finally, give recommendation
  1. Add examples of desired behavior
EXAMPLE:
User: "Summarize this meeting"
You: "## Key Decisions
- Approved Q3 budget..."
  1. Check prompt length

Inconsistent Output Quality

Symptoms:

Solutions:

  1. Lower temperature
  1. Add format constraints
ALWAYS format as:
- Section 1: [specific content]
- Section 2: [specific content]
- Never deviate from this structure
  1. Remove ambiguous language
❌ "Be helpful and creative"
✅ "Provide exactly 3 options. Format as numbered list."

Agent Too Verbose

Symptoms:

Solutions:

  1. Set explicit length limits
- Maximum 150 words per response
- Use bullet points for anything over 3 items
- One paragraph maximum
  1. Increase frequency penalty
  1. Add brevity instructions
BREVITY RULES:
- Get to the point immediately
- No introductory phrases
- Cut all unnecessary words
- Active voice only

Agent Too Brief

Symptoms:

Solutions:

  1. Request elaboration in prompt
- Provide comprehensive coverage
- Include examples for each point
- Explain reasoning
- Minimum 200 words when appropriate
  1. Lower frequency penalty
  1. Add detail requirements
For each recommendation:
- Why it works
- How to implement
- Potential issues
- Expected timeline

Repetitive Language

Symptoms:

Solutions:

  1. Increase presence penalty
presence_penalty: 1.0-1.5
  1. Increase frequency penalty
frequency_penalty: 1.0-1.5
  1. Add variety instructions
- Use varied vocabulary
- Don't repeat the same examples
- Provide different angles each time

Platform-Specific Issues

ChatGPT Custom GPT

Issue: GPT doesn’t save

Issue: Knowledge files not working

Issue: Can’t share GPT

Claude Projects

Issue: Instructions not applying

Issue: Project knowledge not accessible

Issue: Context limit reached

AI Agents Library Marketplace

Issue: Agent not appearing

Issue: Agent translation incorrect

Issue: Can’t add agent to workspace

JSON/File Issues

Invalid JSON Error

Common mistakes:

  1. Trailing commas
❌ {
  "title": "My Agent",
  "tags": ["tag1", "tag2",]
}

✅ {
  "title": "My Agent",
  "tags": ["tag1", "tag2"]
}
  1. Unescaped quotes
❌ "systemRole": "You are a "professional" agent"

✅ "systemRole": "You are a \"professional\" agent"
  1. Missing commas
❌ {
  "title": "Agent"
  "description": "Does stuff"
}

✅ {
  "title": "Agent",
  "description": "Does stuff"
}

Solution:

File Not Found

For GitHub submissions:

  1. Check file location
  1. Check naming
✅ src/my-agent-name.json
❌ src/my_agent_name.json
❌ src/MyAgentName.json
❌ My-Agent-Name.json (wrong directory)
  1. Verify committed
git status
git add src/your-agent.json
git commit -m "Add agent"

Testing Issues

Can’t Reproduce Results

Problem: Agent works in testing but fails in real use

Solutions:

  1. Test with real users
  1. Document test cases
Test 1: [Scenario]
Input: [What you sent]
Expected: [What should happen]
Actual: [What happened]
  1. Version control your prompts

Agent Works Sometimes

Causes:

  1. Temperature too high
  1. Ambiguous instructions
  1. Context matters

Submission Issues

Pull Request Rejected

Common reasons:

  1. Duplicate agent
  1. Low quality prompt
  1. Inappropriate content
  1. Technical errors

Next steps:

Merge Delayed

Timeline: Usually 48-72 hours

If longer:

Performance Issues

Slow Responses

Causes:

  1. Model selection
  1. Long context
  1. Complex instructions
  1. High reasoning_effort (Claude)

Rate Limits Hit

ChatGPT:

Claude:

AI Agents Library:

Getting More Help

Before Opening Issue

  1. Search existing issues
  2. Check FAQ.md
  3. Review examples in EXAMPLES.md
  4. Test in fresh conversation

When Opening Issue

Include:

Emergency Issues

For critical bugs or security issues:

Quick Reference

Problem → Solution:

Issue Quick Fix
Inconsistent Lower temperature to 0.3
Repetitive Increase penalties to 1.0
Too long Set word limit explicitly
Too short Request elaboration in prompt
Wrong tone Add tone examples
Ignores format Use numbered structure
Too creative Lower temperature
Too boring Increase temperature to 0.7
Invalid JSON Use validator, check commas/quotes
Slow Choose faster model or simplify

Still stuck? Join Discord or open an issue with details.

This site is open source. Improve this page.