Common issues and solutions for AI agent creation and usage.
Symptoms:
- Doesn't follow specified format
- Skips important steps
- Acts generically instead of specialized role
Solutions:
- Make instructions more explicit
❌ "Be professional"
✅ "Use formal business tone. No contractions. Address as 'Dear [Name]'"
- Use numbered steps for processes
When responding:
1. First, acknowledge the request
2. Then, provide analysis
3. Finally, give recommendation
- Add examples of desired behavior
EXAMPLE:
User: "Summarize this meeting"
You: "## Key Decisions
- Approved Q3 budget..."
- Check prompt length
- If over 1000 words, model may miss details
- Condense or break into clear sections
Symptoms:
- Sometimes excellent, sometimes poor
- Format changes between responses
- Tone varies unpredictably
Solutions:
- Lower temperature
- Set to 0.1-0.3 for consistent behavior
- 0 = completely deterministic
- Add format constraints
ALWAYS format as:
- Section 1: [specific content]
- Section 2: [specific content]
- Never deviate from this structure
- Remove ambiguous language
❌ "Be helpful and creative"
✅ "Provide exactly 3 options. Format as numbered list."
Symptoms:
- Responses too long
- Unnecessary details
- Rambling explanations
Solutions:
- Set explicit length limits
- Maximum 150 words per response
- Use bullet points for anything over 3 items
- One paragraph maximum
- Increase frequency penalty
- Set to 0.8-1.5
- Discourages repetitive filler words
- Add brevity instructions
BREVITY RULES:
- Get to the point immediately
- No introductory phrases
- Cut all unnecessary words
- Active voice only
Symptoms:
- Incomplete answers
- Missing critical details
- Unhelpful brevity
Solutions:
- Request elaboration in prompt
- Provide comprehensive coverage
- Include examples for each point
- Explain reasoning
- Minimum 200 words when appropriate
- Lower frequency penalty
- Set to 0 or negative
- Allows more natural expression
- Add detail requirements
For each recommendation:
- Why it works
- How to implement
- Potential issues
- Expected timeline
Symptoms:
- Same words/phrases repeated
- Redundant content
- Circular explanations
Solutions:
- Increase presence penalty
presence_penalty: 1.0-1.5
- Increase frequency penalty
frequency_penalty: 1.0-1.5
- Add variety instructions
- Use varied vocabulary
- Don't repeat the same examples
- Provide different angles each time
Issue: GPT doesn't save
- Check if you're on ChatGPT Plus
- Try different browser
- Clear cache and retry
- Verify all required fields filled
Issue: Knowledge files not working
- Confirm file format (PDF, TXT, DOCX supported)
- Check file size (max varies by plan)
- Wait a few minutes after upload
- Try re-uploading
Issue: Can't share GPT
- Check privacy settings (Only me / Link / Public)
- Verify you have GPT Plus
- Try generating new share link
- Check if workplace admin restricted sharing
Issue: Instructions not applying
- Verify instructions in Project settings, not chat
- Check you're in correct project
- Try creating new conversation within project
- Restart browser if persistent
Issue: Project knowledge not accessible
- Confirm files uploaded successfully
- Check file format compatibility
- Verify file size under limits
- Wait for processing (large files take time)
Issue: Context limit reached
- Claude Projects have 200K token limit
- Long conversations + large docs = limit reached
- Solution: Start new conversation in same project
- Or: Remove some uploaded documents
Issue: Agent not appearing
- Check if PR merged
- Wait 24 hours for deployment
- Clear browser cache
- Search by exact identifier
Issue: Agent translation incorrect
- Our i18n is automated and imperfect
- You can provide manual translations
- Submit PR with corrected locale files
- See CONTRIBUTING.md for format
Issue: Can't add agent to workspace
- Refresh browser
- Check internet connection
- Try different browser
- Report as bug if persistent
Common mistakes:
- Trailing commas
❌ {
"title": "My Agent",
"tags": ["tag1", "tag2",]
}
✅ {
"title": "My Agent",
"tags": ["tag1", "tag2"]
}- Unescaped quotes
❌ "systemRole": "You are a "professional" agent"
✅ "systemRole": "You are a \"professional\" agent"- Missing commas
❌ {
"title": "Agent"
"description": "Does stuff"
}
✅ {
"title": "Agent",
"description": "Does stuff"
}Solution:
- Use JSON validator: jsonlint.com
- Use code editor with JSON syntax highlighting
- Copy working example and modify
For GitHub submissions:
- Check file location
- Must be in
/src/directory - Use exact filename from identifier
- Extension must be
.json
- Check naming
✅ src/my-agent-name.json
❌ src/my_agent_name.json
❌ src/MyAgentName.json
❌ My-Agent-Name.json (wrong directory)
- Verify committed
git status
git add src/your-agent.json
git commit -m "Add agent"Problem: Agent works in testing but fails in real use
Solutions:
- Test with real users
- Have someone else try it
- Use actual scenarios, not synthetic
- Test edge cases and ambiguities
- Document test cases
Test 1: [Scenario]
Input: [What you sent]
Expected: [What should happen]
Actual: [What happened]
- Version control your prompts
- Save each iteration
- Note what changed and why
- Can roll back if needed
Causes:
- Temperature too high
- Randomness causes variation
- Lower to 0.3 or below
- Ambiguous instructions
- Model interprets differently each time
- Be more explicit
- Context matters
- Previous messages affect responses
- Test in fresh conversations
Common reasons:
- Duplicate agent
- Check existing agents first
- Search by function, not just name
- Differentiate if similar
- Low quality prompt
- Too vague or generic
- No clear purpose
- Poor formatting
- Inappropriate content
- Violates guidelines
- Offensive/harmful
- Copyright issues
- Technical errors
- Invalid JSON
- Missing required fields
- Wrong file location
Next steps:
- Read reviewer feedback
- Make requested changes
- Resubmit with explanation
Timeline: Usually 48-72 hours
If longer:
- Check PR for reviewer comments
- Verify all checks passed
- Tag maintainer if urgent
- Join Discord for status update
Causes:
- Model selection
- GPT-4 slower than GPT-3.5
- Claude Opus slower than Sonnet
- Check model in settings
- Long context
- Large uploaded files
- Long conversation history
- Solution: Start fresh conversation
- Complex instructions
- Overly detailed prompts
- Multiple nested conditions
- Simplify if possible
- High reasoning_effort (Claude)
- Set to "low" or "medium"
- Reserve "high" for complex tasks
ChatGPT:
- Plus: ~50 messages/3 hours for GPT-4
- Solution: Use GPT-3.5 or wait
Claude:
- Pro: Higher limits but still exist
- Solution: Space out requests
AI Agents Library:
- Varies by plan
- Contact support for limit info
- Search existing issues
- Check FAQ.md
- Review examples in EXAMPLES.md
- Test in fresh conversation
Include:
- Agent identifier or full JSON
- What you expected
- What actually happened
- Steps to reproduce
- Platform (ChatGPT/Claude/AI Agents Library)
- Screenshots if relevant
For critical bugs or security issues:
- Mark as [URGENT] in subject
- Don't publicly share exploit details
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.