Thank you for your interest in contributing to this project! This repository thrives on community contributions that help us build a comprehensive understanding of AI agent failure modes and their solutions.
Document real-world failures you've encountered:
- Follow our failure case submission guidelines
- Include reproduction steps when possible
- Anonymize sensitive information
Share solutions and prevention techniques:
- Describe implementation details
- Link to GitHub repositories with working examples
- Reference related academic work where possible
Add academic insights and empirical studies:
- Link to relevant papers and studies
- Summarize key findings
- Discuss practical implications
- Suggest future research directions
Develop diagnostic and monitoring utilities:
- Failure detection tools
- Mitigation frameworks
- Evaluation benchmarks
- Visualization utilities
Add your example directly to the appropriate failure mode file in docs/failure-modes/:
-
Choose the Right File:
tool-hallucination.md- for tool output errorsresponse-hallucination.md- for agent response errorsgoal-misinterpretation.md- for wrong objective casesplan-generation.md- for flawed planningtool-use.md- for incorrect tool selection/usageverification-termination.md- for completion failuresprompt-injection.md- for security bypass cases
-
Include Required Information:
- Scenario: Context and setup - what was the agent supposed to do?
- Failure: What went wrong and what the agent did
- Impact: Consequences - financial loss, incorrect outputs, etc.
- Source: Link to publicly verifiable documentation (required)
-
Follow Existing Format: Use the pattern
### Company/Product Description (Date)and match the structure of existing examples
Add to existing failure mode documentation or create new tool documentation:
- For Detection/Mitigation Techniques: Add to the "Detection and Mitigation Strategies" section of the relevant failure mode file
- For Tools: Create new documentation in
docs/tools/following the standard structure (Overview, Key Features, Pricing, Additional Resources) - Include Required Information:
- Clear description of your approach and why it works
- Link to working GitHub repository with implementation
- When the technique is most effective
- Performance/effectiveness data if available
- Research: Add to README Resources section with brief description highlighting practical insights
- Tools: Link to external GitHub repositories with comprehensive documentation
- Ensure: All external repositories have proper README, usage instructions, and dependencies listed
git clone https://github.com/vectara/awesome-agent-failures.git
cd awesome-agent-failuresgit checkout -b feature/your-contribution-name- Add your content following the submission guidelines above
- Update relevant documentation
- Ensure formatting consistency
- Provide a clear description of your contribution
- Reference any related issues
- Request review from maintainers
- Use clear, concise language
- Follow Markdown formatting standards
- Include relevant emojis for section headers
- Maintain consistent terminology across documents
- Use kebab-case for filenames (
my-failure-case.md) - Include descriptive names that reflect content
- Follow established directory structure
- Add appropriate file extensions
Markdown Standards:
- Use standard GitHub Flavored Markdown syntax
- Include proper heading hierarchy (H1 for main title, H2 for sections, etc.)
- Use consistent formatting for code blocks, links, and emphasis
- Ensure proper line spacing (no unnecessary blank lines between sections)
Link Requirements:
- All external links must be publicly accessible (no paywalls or login required)
- Links should be stable and unlikely to break (prefer official sources)
- Use descriptive link text, not "click here" or raw URLs
- Test all links before submission
Content Standards:
- Write in clear, professional English
- Use consistent terminology matching existing documentation
- Include specific dates, company names, and quantifiable impacts where possible
- Anonymize sensitive information while maintaining educational value
Required vs. Optional Fields:
- Required Information: All submission guidelines above must be followed
- Optional: Additional context, metrics, or analysis that enhances understanding
- Conditional: Some fields may be required based on contribution type (e.g., GitHub links for tools)
failure-case: New failure mode documentationmitigation: Solution or prevention strategyresearch: Academic contribution or studytool: Diagnostic or monitoring utilitydocumentation: Improvements to existing docsbug: Error in existing contentenhancement: Feature request or improvement
Organize contributions into appropriate categories:
- Failure Modes: Primary taxonomy categories
- Case Studies: Real-world failure examples
- Solutions: Mitigation and prevention strategies
- Tools: Utilities for detection and analysis
- Research: Academic papers and empirical studies
- Failure Cases: Must have publicly verifiable source and document real-world impact
- Mitigation Strategies: Must link to working implementation with clear documentation
- Tools/Research: Must be publicly accessible and directly relevant to AI agent failure modes
We are committed to fostering an open and welcoming environment. All contributors are expected to maintain professional and respectful behavior in all interactions.
- Use inclusive and professional language
- Respect diverse perspectives and experiences
- Provide constructive feedback and criticism
- Credit others' contributions appropriately
- Build on existing work when possible
- Share knowledge and insights freely
- Help newcomers understand contribution process
- Foster learning-oriented discussions
- Prioritize beneficial applications over harmful ones
- Respect privacy and confidentiality
- Consider broader societal implications
- Promote responsible AI development
- GitHub Issues: Create an issue for bugs, questions, or suggestions
- GitHub Discussions: Join discussions for community Q&A
- Pull Requests: Submit contributions via pull requests
- Repository: vectara/awesome-agent-failures
- Issues: For technical questions, create a GitHub issue
- Discussions: For general questions, use GitHub Discussions
By contributing to this project, you agree to license your contributions under the Apache 2.0 License. This ensures:
- Open access for all users
- Freedom to use, modify, and distribute
- Compatibility with commercial applications
- Community ownership of collective knowledge
- Contributors retain copyright to their original work
- Project maintains right to use and distribute contributions
- Proper attribution provided in all derivative works
- Credit given to original authors and sources
- Never include proprietary or confidential information
- Anonymize case studies to protect privacy
- Remove personal identifiers and sensitive data
- Consider legal implications of shared information
Your contributions make this project valuable for the entire AI community. Whether you're sharing a failure case, proposing a solution, or improving documentation, you're helping build a safer and more reliable future for AI agents.
Ready to contribute? Check out our good first issues to get started!
For questions about contributing, please create an issue or start a discussion.