Initial commit

Author: prajwalendra

.github/workflows/pages.yml

@@ -0,0 +1,42 @@
+name: Deploy GitHub Pages
+
+on:
+  push:
+    branches: ["main"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+      - name: Build with Jekyll
+        uses: actions/jekyll-build-pages@v1
+        with:
+          source: ./docs
+          destination: ./_site
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -0,0 +1,49 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project specific
+generated-diagrams/
+*.log
+
+# AgentCore
+.agentcore/
+.bedrock_agentcore/
+.bedrock_agentcore.yaml
+
+# Local guides
+IMPLEMENTATION_GUIDE.md

README.md

@@ -1,11 +1,292 @@
-## My Project
+# Observability Agent with Amazon Bedrock AgentCore
 
-TODO: Fill this README out!
+[![License: MIT-0](https://img.shields.io/badge/License-MIT--0-yellow.svg)](https://opensource.org/licenses/MIT-0)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![AWS](https://img.shields.io/badge/AWS-Bedrock%20AgentCore-orange?logo=amazonaws)](https://aws.amazon.com/bedrock/agentcore/)
+[![Strands SDK](https://img.shields.io/badge/Built%20with-Strands%20SDK-purple)](https://strandsagents.com/)
 
-Be sure to:
+An AI-powered observability agent that helps Site Reliability Engineers (SREs) investigate incidents and reduce Mean Time to Resolution (MTTR). Built with Amazon Bedrock AgentCore and the Strands Agent SDK.
 
-* Change the title in this README
-* Edit your repository description on GitHub
+This sample implements the architecture from [Reduce Mean Time to Resolution with an observability agent](https://aws.amazon.com/blogs/big-data/reduce-mean-time-to-resolution-with-an-observability-agent/).
+
+## Architecture
+
+![Observability Agent Architecture](images/observability-agent-architecture.png)
+
+The agent queries three data sources to investigate incidents:
+- **Logs** - Application logs stored in Amazon OpenSearch Serverless
+- **Traces** - Distributed traces stored in Amazon OpenSearch Serverless  
+- **Metrics** - Infrastructure metrics stored in Amazon Managed Service for Prometheus
+
+## Choose Your Path
+
+### Option A: Quick Start (Build from Scratch)
+
+Best for: Learning, POC, testing the agent with sample data.
+
+This path creates all required AWS resources and populates them with test data simulating a payment service failure.
+
+**Time:** ~15 minutes | **Cost:** ~$5/day for OpenSearch Serverless
+
+[→ Quick Start Guide](#quick-start-build-from-scratch)
+
+### Option B: Integrate with Existing Infrastructure
+
+Best for: Production use with your existing observability stack.
+
+This path connects the agent to your existing OpenSearch and Prometheus deployments.
+
+**Time:** ~10 minutes | **Prerequisites:** Existing OpenSearch + Prometheus
+
+[→ Integration Guide](#integrate-with-existing-infrastructure)
+
+---
+
+## Quick Start (Build from Scratch)
+
+### Prerequisites
+
+- AWS account with appropriate permissions
+- Python 3.11+
+- AWS CLI configured with credentials
+
+### Step 1: Clone and Setup
+
+```bash
+git clone https://github.com/aws-samples/observability-agent-bedrock-agentcore.git
+cd observability-agent-bedrock-agentcore
+
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+pip install -r requirements.txt
+```
+
+### Step 2: Create OpenSearch Serverless Collection
+
+```bash
+# Set your AWS account ID
+export AWS_ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
+export AWS_REGION=us-east-1
+
+# Create encryption policy
+aws opensearchserverless create-security-policy \
+  --name observability-enc \
+  --type encryption \
+  --policy '{"Rules":[{"ResourceType":"collection","Resource":["collection/observability-agent"]}],"AWSOwnedKey":true}'
+
+# Create network policy
+aws opensearchserverless create-security-policy \
+  --name observability-net \
+  --type network \
+  --policy '[{"Rules":[{"ResourceType":"collection","Resource":["collection/observability-agent"]},{"ResourceType":"dashboard","Resource":["collection/observability-agent"]}],"AllowFromPublic":true}]'
+
+# Create data access policy
+aws opensearchserverless create-access-policy \
+  --name observability-access \
+  --type data \
+  --policy "[{\"Rules\":[{\"ResourceType\":\"collection\",\"Resource\":[\"collection/observability-agent\"],\"Permission\":[\"aoss:*\"]},{\"ResourceType\":\"index\",\"Resource\":[\"index/observability-agent/*\"],\"Permission\":[\"aoss:*\"]}],\"Principal\":[\"arn:aws:iam::${AWS_ACCOUNT_ID}:root\"]}]"
+
+# Create collection
+aws opensearchserverless create-collection \
+  --name observability-agent \
+  --type SEARCH
+```
+
+Wait for the collection to become ACTIVE (~2-3 minutes):
+
+```bash
+aws opensearchserverless batch-get-collection --names observability-agent
+```
+
+### Step 3: Configure Environment
+
+```bash
+# Get collection endpoint
+export OPENSEARCH_HOST=$(aws opensearchserverless batch-get-collection \
+  --names observability-agent \
+  --query 'collectionDetails[0].collectionEndpoint' \
+  --output text | sed 's|https://||')
+
+echo "OpenSearch Host: $OPENSEARCH_HOST"
+```
+
+### Step 4: Generate Test Data
+
+```bash
+python scripts/generate_test_data.py
+```
+
+This creates sample logs and traces simulating a payment service failure with ~40% error rate.
+
+### Step 5: Deploy the Agent
+
+```bash
+pip install bedrock-agentcore-starter-toolkit
+
+agentcore configure --entrypoint agent/main.py --non-interactive
+agentcore deploy
+```
+
+### Step 6: Grant Permissions
+
+Get the AgentCore role name from the deploy output, then:
+
+```bash
+# Replace with your actual role name from deploy output
+export AGENTCORE_ROLE=AmazonBedrockAgentCoreSDKRuntime-us-east-1-XXXXXX
+export COLLECTION_ID=$(aws opensearchserverless batch-get-collection \
+  --names observability-agent \
+  --query 'collectionDetails[0].id' \
+  --output text)
+
+# Add OpenSearch permissions
+aws iam put-role-policy \
+  --role-name $AGENTCORE_ROLE \
+  --policy-name OpenSearchServerlessAccess \
+  --policy-document "{
+    \"Version\": \"2012-10-17\",
+    \"Statement\": [{
+      \"Effect\": \"Allow\",
+      \"Action\": [\"aoss:APIAccessAll\"],
+      \"Resource\": \"arn:aws:aoss:${AWS_REGION}:${AWS_ACCOUNT_ID}:collection/${COLLECTION_ID}\"
+    }]
+  }"
+
+# Update OpenSearch data access policy
+POLICY_VERSION=$(aws opensearchserverless get-access-policy \
+  --name observability-access --type data \
+  --query 'accessPolicyDetail.policyVersion' --output text)
+
+aws opensearchserverless update-access-policy \
+  --name observability-access \
+  --type data \
+  --policy-version $POLICY_VERSION \
+  --policy "[{\"Rules\":[{\"ResourceType\":\"collection\",\"Resource\":[\"collection/observability-agent\"],\"Permission\":[\"aoss:*\"]},{\"ResourceType\":\"index\",\"Resource\":[\"index/observability-agent/*\"],\"Permission\":[\"aoss:*\"]}],\"Principal\":[\"arn:aws:iam::${AWS_ACCOUNT_ID}:root\",\"arn:aws:iam::${AWS_ACCOUNT_ID}:role/${AGENTCORE_ROLE}\"]}]"
+```
+
+### Step 7: Test the Agent
+
+```bash
+# Wait for IAM propagation
+sleep 30
+
+# Investigate errors
+agentcore invoke '{"prompt": "Are there any errors in my application?"}'
+
+# Check specific service
+agentcore invoke '{"prompt": "What is wrong with the payment service?"}'
+```
+
+---
+
+## Integrate with Existing Infrastructure
+
+### Prerequisites
+
+- Existing Amazon OpenSearch Service or OpenSearch Serverless with logs/traces
+- (Optional) Amazon Managed Service for Prometheus with metrics
+- Python 3.11+
+
+### Step 1: Clone and Setup
+
+```bash
+git clone https://github.com/aws-samples/observability-agent-bedrock-agentcore.git
+cd observability-agent-bedrock-agentcore
+
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+### Step 2: Configure Your Endpoints
+
+Edit `agent/main.py` or set environment variables:
+
+```bash
+# For OpenSearch Serverless
+export OPENSEARCH_HOST=your-collection-id.us-east-1.aoss.amazonaws.com
+
+# For Amazon Managed Prometheus (optional)
+export AMP_WORKSPACE_ID=ws-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+
+export AWS_REGION=us-east-1
+```
+
+### Step 3: Customize Index Patterns (if needed)
+
+If your indices use different naming conventions, update the index patterns in `agent/main.py`:
+
+```python
+# Default patterns (OpenTelemetry standard)
+"otel-v1-apm-span-*"  # For traces
+"otel-logs-*"          # For logs
+
+# Example: Custom patterns
+"your-traces-*"
+"your-logs-*"
+```
+
+### Step 4: Deploy and Configure Permissions
+
+```bash
+pip install bedrock-agentcore-starter-toolkit
+agentcore configure --entrypoint agent/main.py --non-interactive
+agentcore deploy
+```
+
+Then add the AgentCore role to your OpenSearch data access policy (see Step 6 in Quick Start).
+
+### Step 5: Test
+
+```bash
+agentcore invoke '{"prompt": "Show me the health of my services"}'
+```
+
+---
+
+## Agent Tools
+
+The agent exposes four tools for querying observability data:
+
+| Tool | Data Source | Description |
+|------|-------------|-------------|
+| `get_red_metrics` | OpenSearch (traces) | Rate, Error, Duration metrics by service |
+| `search_logs` | OpenSearch (logs) | Search logs by service, severity |
+| `get_spans` | OpenSearch (traces) | Search distributed trace spans |
+| `query_metrics` | Prometheus | Query metrics using PromQL |
+
+## Security
+
+This sample follows AWS security best practices:
+
+- **No hardcoded credentials** - Uses IAM roles for authentication
+- **TLS everywhere** - All connections use HTTPS with certificate verification
+- **Input validation** - All tool inputs are validated and sanitized
+- **Least privilege** - IAM policies grant minimal required permissions
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for security issue reporting.
+
+## Clean Up
+
+To avoid ongoing charges, delete the resources when done:
+
+```bash
+# Delete AgentCore resources
+agentcore destroy
+
+# Delete OpenSearch Serverless (if created)
+aws opensearchserverless delete-collection --id YOUR_COLLECTION_ID
+aws opensearchserverless delete-security-policy --name observability-enc --type encryption
+aws opensearchserverless delete-security-policy --name observability-net --type network
+aws opensearchserverless delete-access-policy --name observability-access --type data
+```
+
+## References
+
+- [AWS Blog: Reduce MTTR with an Observability Agent](https://aws.amazon.com/blogs/big-data/reduce-mean-time-to-resolution-with-an-observability-agent/)
+- [Amazon Bedrock AgentCore Documentation](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/)
+- [Strands Agents SDK](https://strandsagents.com/latest/documentation/docs/)
+- [Amazon OpenSearch Serverless](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/serverless.html)
 
 ## Security
 
@@ -14,4 +295,3 @@ See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more inform
 ## License
 
 This library is licensed under the MIT-0 License. See the LICENSE file.
-