{"id":47566453,"url":"https://github.com/aws-samples/sample-why-agents-fail","last_synced_at":"2026-04-14T01:00:33.011Z","repository":{"id":340268525,"uuid":"1155842362","full_name":"aws-samples/sample-why-agents-fail","owner":"aws-samples","description":"Research-backed demos fixing the 3 critical AI agent failure modes: hallucinations, token waste, and   memory loss. Working Python code using Strands Agents","archived":false,"fork":false,"pushed_at":"2026-03-10T23:18:02.000Z","size":2429,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-11T04:42:27.693Z","etag":null,"topics":["agentic-ai","bedrock","openai","paper","strands-agents","tutorial"],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit-0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aws-samples.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-12T00:53:55.000Z","updated_at":"2026-03-10T23:18:06.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/aws-samples/sample-why-agents-fail","commit_stats":null,"previous_names":["aws-samples/sample-why-agents-fail"],"tags_count":0,"template":false,"template_full_name":"amazon-archives/__template_MIT-0","purl":"pkg:github/aws-samples/sample-why-agents-fail","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-samples%2Fsample-why-agents-fail","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-samples%2Fsample-why-agents-fail/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-samples%2Fsample-why-agents-fail/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-samples%2Fsample-why-agents-fail/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aws-samples","download_url":"https://codeload.github.com/aws-samples/sample-why-agents-fail/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-samples%2Fsample-why-agents-fail/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31777348,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T00:11:49.126Z","status":"ssl_error","status_checked_at":"2026-04-14T00:10:29.837Z","response_time":93,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-ai","bedrock","openai","paper","strands-agents","tutorial"],"created_at":"2026-03-30T06:00:24.600Z","updated_at":"2026-04-14T01:00:32.993Z","avatar_url":"https://github.com/aws-samples.png","language":"Jupyter Notebook","readme":"# 🤖 Why AI Agents Fail (And How to Fix Them)\n\n\n[![GitHub stars](https://img.shields.io/github/stars/aws-samples/sample-why-agents-fail.svg?style=for-the-badge\u0026logo=github\u0026color=yellow)](https://github.com/aws-samples/sample-why-agents-fail/stargazers) [![License](https://img.shields.io/badge/License-MIT--0-blue.svg?style=for-the-badge)](LICENSE) [![Python](https://img.shields.io/badge/Python-3.9+-green.svg?style=for-the-badge\u0026logo=python)](https://python.org) [![AWS](https://img.shields.io/badge/AWS-Bedrock-orange.svg?style=for-the-badge\u0026logo=amazon-aws)](https://aws.amazon.com/bedrock/) [![Strands](https://img.shields.io/badge/🧬-Strands_Agents-blue.svg?style=for-the-badge)](https://strandsagents.com)\n\n\n*Research-backed solutions to the three critical failure modes that break AI agents in production: hallucinations, timeouts, and memory loss.*\n\n⭐ **[Star this repository](https://github.com/aws-samples/sample-why-agents-fail)**\n\n---\n\n## 🎯 Learning Path: Understand → Prevent → Scale\n\nThis repository demonstrates research-backed techniques for preventing AI agent failures with working code examples.\n\n| 🚨 Failure Mode | 💡 Solution Approach | 📊 Projects | ⏱️ Total Time |\n|----------------|---------------------|-------------|---------------|\n| **[Hallucinations](#-stop-ai-agent-hallucinations)** | Detection and mitigation through 4 techniques | 4 demos | 2 hours |\n| **[Getting Stuck](#-stop-agents-from-wasting-tokens)** | Context overflow, MCP timeouts, reasoning loops | 3 demos | 1.5 hours |\n| **Memory Loss** | Persistent memory and context retrieval | Coming soon | - |\n\n---\n\n## 🎭 Stop AI Agent Hallucinations\n\n**The Problem**: Agents fabricate statistics, choose wrong tools, ignore business rules, and claim success when operations fail.\n\n**The Solution**: 4 research-backed techniques that detect, contain, and mitigate hallucinations before they cause damage.\n\n### 📓 Hallucination Prevention Demos\n\n| 📓 Demo | 🎯 Focus \u0026 Key Learning | ⏱️ Time | 📊 Level |\n|---------|------------------------|----------|----------|\n| **01 - [Graph-RAG vs Traditional RAG](stop-ai-agent-hallucinations/01-faq-graphrag-demo/)** | Structured data retrieval - Compare RAG vs Graph-RAG on 300 hotel FAQs, Neo4j knowledge graph with auto entity extraction, eliminate statistical hallucinations | 30 min | ![Intermediate](https://img.shields.io/badge/-Intermediate-yellow) |\n| **02 - [Semantic Tool Selection](stop-ai-agent-hallucinations/02-semantic-tools-demo/)** | Intelligent tool filtering - Filter 31 tools to top 3 relevant, reduce errors and token costs, dynamic tool swapping | 45 min | ![Intermediate](https://img.shields.io/badge/-Intermediate-yellow) |\n| **03 - [Multi-Agent Validation Pattern](stop-ai-agent-hallucinations/03-multiagent-demo/)** | Cross-validation workflows - Executor → Validator → Critic pattern catches hallucinations, Strands Swarm orchestration | 30 min | ![Intermediate](https://img.shields.io/badge/-Intermediate-yellow) |\n| **04 - [Neurosymbolic Guardrails for AI Agents](stop-ai-agent-hallucinations/04-neurosymbolic-demo/)** | Symbolic validation - Compare prompt engineering vs symbolic rules, business rule compliance, LLM cannot bypass | 20 min |![Intermediate](https://img.shields.io/badge/-Intermediate-yellow) |\n\n### 📊 Key Results\n\n| 🎯 Technique | 📈 Improvement | 🔍 Metric |\n|--------------|----------------|-----------|\n| **Graph-RAG** | Accuracy | Precise queries on 300 hotel FAQs via knowledge graph |\n| **Semantic Tool Selection** | Reduce errors and token costs | Tool selection hallucination detection (research validated), Token cost per query |\n| **Neurosymbolic Rules** | Compliance | Business rule enforcement - LLM cannot bypass |\n| **Multi-Agent Validation** | Detects errors | Invalid operation detection before reaching users |\n\n**[→ Explore hallucination prevention demos](stop-ai-agent-hallucinations/)**\n\n---\n\n## 🔄 Stop Agents from Wasting Tokens\n\n**The Problem**: Agents get stuck when context windows overflow with large data, MCP tools stop responding on slow APIs, or agents repeat the same tool calls without making progress — burning tokens and blocking workflows.\n\n**The Solution**: 3 research-backed techniques that prevent context overflow, handle unresponsive APIs, and detect reasoning loops before they waste resources.\n\n### 📓 Token Waste \u0026 Stuck Agent Demos\n\n| 📓 Demo | 🎯 Focus \u0026 Key Learning | ⏱️ Time | 📊 Level |\n|---------|------------------------|----------|----------|\n| **01 - [Context Window Overflow](stop-ai-agents-wasting-tokens/01-context-overflow-demo/)** | Memory management — Store large data outside context with Memory Pointer Pattern, 7x token reduction validated by IBM Research | 30 min | ![Intermediate](https://img.shields.io/badge/-Intermediate-yellow) |\n| **02 - [MCP Tools Not Responding](stop-ai-agents-wasting-tokens/02-mcp-timeout-demo/)** | Async patterns — Handle slow/unresponsive APIs with async handleId, prevent 424 errors, immediate responses | 20 min | ![Intermediate](https://img.shields.io/badge/-Intermediate-yellow) |\n| **03 - [Reasoning Loops](stop-ai-agents-wasting-tokens/03-reasoning-loops-demo/)** | Loop detection — DebounceHook blocks duplicate calls, clear SUCCESS/FAILED states stop retries, 7x fewer tool calls | 25 min | ![Intermediate](https://img.shields.io/badge/-Intermediate-yellow) |\n\n**[→ Explore token waste prevention demos](stop-ai-agents-wasting-tokens/)**\n\n---\n\n## Your Agent Doesn't Remember You\n\n*(Coming soon)*\n\n---\n\n## 🔧 Technologies Used\n\n\u003cdetails\u003e\n\n| 🔧 Technology | 🎯 Purpose | ⚡ Key Capabilities |\n|---------------|------------|---------------------|\n| **[Strands Agents](https://strandsagents.com)** | AI agent framework | Dynamic tool swapping, multi-agent orchestration, conversation memory, hooks system |\n| **[Amazon Bedrock](https://aws.amazon.com/bedrock/)** | LLM access | Claude 3 Haiku/Sonnet for agent reasoning and tool calling |\n| **[Neo4j](https://neo4j.com)** | Graph database | Relationship-aware queries, precise aggregations, multi-hop traversal |\n| **[FAISS](https://github.com/facebookresearch/faiss)** | Vector search | Semantic similarity, tool filtering, efficient nearest neighbor search |\n| **[SentenceTransformers](https://www.sbert.net/)** | Embeddings | Text embeddings for semantic tool selection and memory retrieval |\n\n\u003c/details\u003e\n\n---\n\n## Prerequisites\n\n**Before You Begin:**\n- Python 3.9+ installed locally\n- LLM access: OpenAI (default), Amazon Bedrock, Anthropic, or Ollama\n- `OPENAI_API_KEY` environment variable (for default setup)\n- AWS CLI configured if using Amazon Bedrock (`aws configure`)\n- Basic understanding of AI agents and tool calling\n\n**Model Configuration:**\nAll demos use OpenAI with GPT-4o-mini by default. You can swap to any provider supported by Strands — see [Strands Model Providers](https://strandsagents.com/latest/documentation/docs/user-guide/concepts/model-providers/) for configuration.\n\n**AWS Credentials Setup (if using Amazon Bedrock):**\nFollow the [AWS credentials configuration guide](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html?trk=87c4c426-cddf-4799-a299-273337552ad8\u0026sc_channel=el) to configure your environment.\n\n---\n\n## 🚀 Quick Start Guide\n\n### 1. **Clone Repository**\n```bash\ngit clone https://github.com/aws-samples/sample-why-agents-fail\ncd sample-why-agents-fail\n```\n\n### 2. **Start with Hallucinations**\n```bash\ncd stop-ai-agent-hallucinations\n```\n\n### 3. **Explore All Techniques**\nEach demo folder contains detailed README files and working code examples.\n\n---\n\n## 💰 Cost Estimation\n\n| 💰 Service | 💵 Approximate Cost | 📊 Usage Pattern | 🔗 Pricing Link |\n|-------------|---------------------|------------------|------------------|\n| OpenAI GPT-4o-mini | ~$0.15 per 1M input tokens | Agent reasoning and tool calling | [OpenAI Pricing](https://openai.com/pricing) |\n| Amazon Bedrock (Claude) | ~$0.25 per 1M input tokens | Alternative LLM provider | [Bedrock Pricing](https://aws.amazon.com/bedrock/pricing/) |\n| Neo4j (local) | Free | Graph database for demos | [Neo4j Pricing](https://neo4j.com/pricing/) |\n| FAISS (local) | Free | Vector search library | [FAISS GitHub](https://github.com/facebookresearch/faiss) |\n| SentenceTransformers | Free | Local embeddings | [SBERT Docs](https://www.sbert.net/) |\n\n\u003e 💡 All demos can run locally with minimal costs. OpenAI GPT-4o-mini is the most cost-effective option for testing.\n\n---\n\n## 📖 Additional Learning Resources\n\n- [Strands Agents Documentation](https://strandsagents.com) - Framework documentation and model providers\n- [Amazon Bedrock Documentation](https://docs.aws.amazon.com/bedrock?trk=87c4c426-cddf-4799-a299-273337552ad8\u0026sc_channel=el) - LLM service guide and model access\n- [Search for tools in your AgentCore gateway with a natural language query](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-using-mcp-semantic-search.html)\n- [Neo4j Graph Database Guide](https://neo4j.com/docs/) - Graph database setup and Cypher queries\n\n\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**⭐ **[Star this repository](https://github.com/aws-samples/sample-why-agents-fail)**** • **📖 [Start Learning](stop-ai-agent-hallucinations/)**\n\n\u003c/div\u003e\n\n\n---\n\n## 🤝 Contributing\n\nContributions are welcome! See [CONTRIBUTING](CONTRIBUTING.md) for more information.\n\n---\n\n## Security\n\nIf you discover a potential security issue in this project, notify AWS/Amazon Security via the [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/). Please do **not** create a public GitHub issue.\n\n---\n\n## 📄 License\n\nThis library is licensed under the MIT-0 License. See the [LICENSE](LICENSE) file for details.\n\n\n","funding_links":[],"categories":["Community Projects"],"sub_categories":["For PyPI Packages"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws-samples%2Fsample-why-agents-fail","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faws-samples%2Fsample-why-agents-fail","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws-samples%2Fsample-why-agents-fail/lists"}