Weekend Challenge: Build an Agent People Actually Enjoy Using — StackSage AI: An AI-Powered AWS Troubleshooting Agent
Meet StackSage AI, an AWS troubleshooting agent built with Amazon Bedrock to simplify cloud debugging through clear explanations, actionable fixes, and a developer-friendly experience.
StackSage AI: From AWS Errors to Clear Answers - Building a Troubleshooting Agent Developers Enjoy Using
What if your AI assistant didn't just explain an AWS error, but helped you figure out what to do next—without overwhelming you with technical details?
As an AI/ML Engineer, I've spent time exploring how AI can solve practical engineering problems. One thing I've noticed is that debugging isn't always difficult because the problem is complicated. Sometimes, the hardest part is simply knowing where to start.
A Lambda function fails. An S3 request returns
AccessDenied. Amazon Bedrock throws a validation error. Suddenly, you're switching between logs, documentation, IAM policies, and configuration files, trying to connect the dots.That inspired me to build StackSage AI, an AI-powered AWS troubleshooting agent created for the AWS Builder Center Weekend Challenge: Build an agent people actually enjoy using.
My goal was not to build another chatbot. I wanted to create a practical developer assistant that makes troubleshooting more approachable, explains technical problems in plain English, and helps developers move forward with confidence.
What is StackSage AI, and who is it for?
StackSage AI is an AI-powered troubleshooting assistant that helps developers investigate common AWS errors and understand potential solutions.
It is designed for cloud developers, AI/ML engineers, students, and AWS builders who want to spend less time deciphering error messages and more time building applications.
The agent focuses on common troubleshooting scenarios involving:
- AWS Lambda execution failures
- Amazon S3 access and object retrieval errors
- IAM permissions and access-denied issues
- Amazon API Gateway configuration problems
- Amazon Bedrock validation and configuration errors
A user submits an error message or relevant log excerpt. StackSage AI analyzes the available information and provides a structured response containing a diagnosis, likely root cause, reasoning, and recommended troubleshooting steps.
The objective is straightforward: turn confusing error messages into clear, actionable next steps.
How I built StackSage AI
I designed StackSage AI around a serverless AWS architecture, combining a modern web interface with a backend that orchestrates AI-powered troubleshooting.
The architecture separates the user experience, request handling, model inference, and operational monitoring.
AWS services and technologies
| Service or technology | Purpose in StackSage AI |
|---|---|
| Next.js and React | Build the interactive troubleshooting interface. |
| AWS Amplify | Host and deploy the web frontend. |
| Amazon API Gateway | Receive requests from the frontend and route them to the backend. |
| AWS Lambda | Validate inputs, orchestrate prompts, invoke the model, and format responses. |
| Amazon Bedrock | Power error analysis, explanations, and troubleshooting recommendations. |
| Amazon CloudWatch | Support logging, monitoring, and backend debugging. |
The frontend is built with Next.js and React, while AWS Amplify provides the planned hosting and deployment layer. Amazon API Gateway exposes the backend endpoint, and AWS Lambda manages the request-processing workflow.
Amazon Bedrock provides the foundation-model inference capability. The model receives a carefully structured prompt containing the relevant error context and instructions to produce useful, organized troubleshooting guidance.
I chose a focused serverless design because the project doesn't need unnecessary infrastructure to demonstrate its core value. A well-designed agent solving one specific problem is more useful than an unnecessarily complicated system.
Architecture diagram
Figure 1: StackSage AI architecture, showing the flow from user-submitted AWS errors through API Gateway, Lambda, and Amazon Bedrock, with CloudWatch supporting operational monitoring.
The diagram illustrates the complete request lifecycle, from submitting an error to returning a structured diagnosis and suggested fixes to the user.
How the troubleshooting workflow works
The workflow follows a simple sequence:
- Submit: The developer pastes an AWS error message or relevant log excerpt into StackSage AI.
- Validate: The backend validates the request and prepares the troubleshooting context.
- Analyze: AWS Lambda invokes Amazon Bedrock with instructions to investigate the reported issue.
- Diagnose: The model generates a likely explanation, identifies possible root causes, and suggests remediation steps.
- Respond: The backend formats the response and returns it to the frontend.
- Explore: The developer can review the diagnosis, understand the reasoning, and follow the recommended checks.
CloudWatch supports backend observability, helping developers investigate application-side failures.
This workflow keeps the agent focused on its main responsibility: helping users understand problems and identify sensible next steps.
The delightful detail: debugging without the information overload
The most important design decision was not adding another AWS service. It was thinking carefully about how the agent communicates.
AI assistants can generate lengthy explanations packed with technical details. Sometimes that is exactly what an experienced engineer needs. But when someone is stuck, a wall of text can make a frustrating situation even worse.
I wanted StackSage AI to feel more like a patient technical teammate.
Instead of presenting everything at once, the experience is organized around three simple actions:
Show me the fix — guide the user through practical troubleshooting steps.
Explain why — explain the technical reasoning behind the diagnosis.
I fixed it — allow the user to continue the troubleshooting conversation after trying a suggested solution.
Consider an example: a Lambda function cannot retrieve an object from Amazon S3.
Instead of immediately overwhelming the developer with IAM documentation, bucket policies, and permissions terminology, the agent can begin with a concise explanation:
“Let's narrow this down. Your Lambda function may not have permission to read the requested S3 object.”
It can then guide the user through checking the Lambda execution role, relevant IAM permissions, the bucket policy, and the requested object key.
The developer can explore the explanation when needed without being forced to read everything upfront.
This progressive approach is the experience I wanted to create: clear answers first, deeper technical detail when requested, and practical guidance throughout.
How I approach accuracy and safety
An AI-generated diagnosis should never be treated as proof that a root cause has been confirmed.
StackSage AI is designed to distinguish likely causes from established facts, explain uncertainty, and encourage users to verify their resource configuration before making changes.
For example, an S3
AccessDenied error may involve an IAM identity policy, a bucket policy, an explicit deny, or another access-control mechanism. The agent should guide the developer through these possibilities instead of assuming every case has the same solution.Security is equally important. Users should not share AWS secret access keys or other credentials. Recommended changes should be reviewed before application, and potentially destructive operations require particular caution.
StackSage AI is intended to provide troubleshooting guidance while leaving control of AWS resources in the developer's hands.
Proof that StackSage AI works
The project repository is available on GitHub:
Repository: StackSage AI — GitHub Repository
The most useful examples are:
- An
AccessDeniederror involving S3 permissions - A
NoSuchKeyerror caused by an incorrect or missing object key - An Amazon Bedrock validation error
These examples illustrate different troubleshooting patterns and demonstrate how the agent handles distinct types of AWS problems.
The most important measure of success is not whether the response sounds impressive. It is whether the developer understands the likely problem, knows what to investigate next, and can evaluate the suggested fix safely.
What I learned from building StackSage AI
This project brings together several areas I enjoy exploring as an AI/ML Engineer: generative AI, prompt engineering, serverless architecture, cloud application development, and user-centered design.
It reinforced an important idea for me: a capable AI model alone does not make a great AI product.
The surrounding experience matters just as much. How the agent introduces itself, how it handles uncertainty, how clearly it explains a problem, and how easily a user can take the next step all influence whether the tool is genuinely useful.
Going forward, I'd like to expand the range of supported AWS errors, improve the grounding of troubleshooting recommendations, and systematically evaluate the quality and consistency of the agent's diagnoses.
My long-term goal is to make StackSage AI a practical companion for developers who want to spend less time guessing and more time building.
Let's build better AI agents together
The idea behind StackSage AI is simple: troubleshooting should help developers learn, not leave them feeling more confused.
I'm excited to keep exploring how thoughtful AI engineering and a well-designed user experience can make cloud development more accessible.
I'd love to hear your feedback!
What makes an AI agent genuinely enjoyable to use? Would you prefer more detailed technical explanations, interactive troubleshooting steps, or recommendations grounded in official AWS documentation?
If you have ideas for additional AWS error scenarios, suggestions for improving the architecture, or feedback on the user experience, please share them in the comments.
If you enjoyed this project, give the article a like, share your thoughts, and follow my journey as I continue building practical AI applications on AWS.
Let's build agents that don't just answer questions, but genuinely help people move forward.
Project repository: StackSage AI — GitHub Repository
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article