agents-on-aws

---

---

🚀 Community-Driven Learning Resource Help build the most comprehensive AWS agent development guide on GitHub!

📢 How You Can Help:

• 🐛 Report Issues
• 💡 Suggest New Guides
• ✍️ Submit Improvements
• 📚 Add Missing Concepts
• ✅ Review Open PRs

---

Table of Contents

• Release Status
• Why This Repo?
• What is This?
• Quick Start
• Learning Paths
• Available Guides
• Coming Soon
• Tech Stack
• Every Guide Has
• Cost
• Contributing
• Contributors
• License

---

📣 Release Status

This is an active project — new guides are added as they are built and verified. ⭐ Star the repo to follow along.

	Status
✅ Released	Guides 001–007 — tested, deployed, working
🚧 Coming Soon	More guides across Runtime · Memory · Gateway · Identity · Observability · Browser · Code Interpreter · Harness · Policy · Registry · Multi-Agent

---

💡 Why This Repo?

✅ End-to-End Coverage — From your first local agent to a full production multi-agent system, nothing is skipped
✅ Every AgentCore Service — Runtime · Memory · Gateway · Identity · Browser · Code Interpreter · Harness · Observability · Policy · Registry · Payments
✅ Runnable, Not Theoretical — Every guide deploys real AWS infrastructure with CDK Python; bash deploy.sh and it works
✅ Security First — Dedicated identity, policy, and credential management guides — not an afterthought
✅ Cost Transparent — Every guide shows its cost estimate before you deploy a single resource
✅ Zero Lock-in — Any agent framework (Strands, LangGraph, CrewAI), any foundation model (Nova, Claude, GPT-4o)

---

🤖 What is This?

This repo is a complete, hands-on guide to building AI agents on AWS using Amazon Bedrock AgentCore.

Each guide teaches a specific concept with real source code, CDK infrastructure, shell scripts, architecture diagrams (Mermaid), and a cost estimate. Deploy one or all.

AgentCore Service	What it does
🚀 Runtime	Serverless microVM hosting — session isolation, any framework, any model
🧠 Memory	STM + LTM — preferences, summaries, semantic facts, cross-agent sharing
🔌 Gateway	MCP tool server — Lambda, OpenAPI, Smithy, semantic discovery, OAuth
🔐 Identity	Workload identity, inbound JWT, outbound OAuth, consent flows
📊 Observability	OTEL tracing, CloudWatch dashboards, cross-account, zero config
🌐 Browser	Cloud browser — Nova Act, live view, human-in-loop, session recording
💻 Code Interpreter	Sandboxed Python/JS/TS execution, large S3 files
⚙️ Harness	Config-only agents — no Docker, no CDK, running in 30 seconds
📈 Quality	LLM-as-Judge evals, AI prompt optimization, A/B testing, Cedar policies
🗂️ Registry	Centralized tool catalog — publish, discover, cross-account sharing
💳 Payments	x402 microtransactions, budget limits (optional)
🤝 Multi-Agent	Orchestrator patterns, A2A, CrewAI, Step Functions, full production capstone

---

⚡ Quick Start

New here? Start with guides 001–007 — they are available now and cover everything from local agents to your first AgentCore Runtime deployment.

Step 1 — One-time setup (~10 min)

# Install Node.js CLI tools
npm install -g @aws/agentcore aws-cdk

# Clone the repo
git clone https://github.com/anveshmuppeda/agents-on-aws.git
cd agents-on-aws

# Create the shared Python virtual environment and install all packages
bash setup-env.sh

# Configure AWS
aws configure                                                  # set region: us-east-1
aws sts get-caller-identity --query Account --output text    # get your account ID
cdk bootstrap aws://YOUR_ACCOUNT_ID/us-east-1               # one-time CDK setup

Bedrock model access — open the Amazon Bedrock console, enable Amazon Nova Pro, click Save.

Step 2 — Verify setup

source .venv/bin/activate
cd 00-foundations/001-prerequisites
python3 verify_setup.py
# All 12 checks passed! You're ready to go. ✅

JSII Node warning? Cosmetic — not an error. Silence it: export JSII_SILENCE_WARNING_UNTESTED_NODE_VERSION=1

Step 3 — Run your first agent locally (no cost)

source .venv/bin/activate
cd 00-foundations/003-local-agent-strands
python3 Source/app/agent.py

Step 4 — Deploy to AgentCore Runtime

source .venv/bin/activate
cd 01-runtime/006-agent-on-agentcore-runtime
bash deploy.sh      # ~5 min — Docker → ECR → CfnRuntime
bash invoke.sh      # test your live agent
bash destroy.sh     # ⚠️ always run this to stop billing

---

📖 Learning Paths

Paths below use currently released guides (001–007). Full paths across all modules will be available as more guides are released.

🟢 Available Now — "Get started with AgentCore" (~2 hours)

001 → 003 → 004 → 006 → 007

Setup → local agent → understand the agent loop → first Runtime deploy → Harness vs Runtime comparison.

🟡 Planned — "Build a complete agent" (~1 day)

Once guides 008–020 are released: Add sessions → LangGraph → any model → MCP server → A2A → streaming → memory (STM + LTM)

🔴 Planned — "Production-ready system" (~1 week)

Once all modules are released: Full sequence from foundations to capstone — every AgentCore service in one production-ready system.

---

✅ Available Guides (001–007)

These guides are tested, deployed, and verified on a real AWS account.

Module 0 — Foundations

#	Guide
001	prerequisites
002	project-template
003	local-agent-strands
004	local-agent-no-framework
005	agent-on-lambda

Module 1 — AgentCore Runtime (partial)

#	Guide
006	agent-on-agentcore-runtime
007	harness-vs-runtime

---

🚧 Coming Soon — 50+ More Guides

New guides are added as they are built and verified.
⭐ Star the repo to follow along.

---

To add a guide to the Available section

Move the guide's row in README.md from ## 🚧 Coming Soon up to ## ✅ Available Guides, and update the status in docs/GUIDES.md. That's the only change needed.

---

Here's what's coming across every AgentCore service:

🚀 AgentCore Runtime — Deep Dive

8 more guides covering:
Session isolation · LangGraph on Runtime · Swap any model (Claude / Nova / GPT-4o) · MCP servers · Agent-to-Agent (A2A) · Streaming tokens · Async long-running tasks · Persistent filesystem with EFS

🧠 AgentCore Memory

5 guides covering:
Short-term memory (STM) · LTM session summaries · LTM user preferences · LTM semantic facts · Shared memory across multiple agents

🔌 AgentCore Gateway

7 guides covering:
Lambda as MCP tool · OpenAPI target (any REST API) · AWS services via Smithy · Semantic tool discovery · Agent-to-Agent via Gateway · OAuth inbound auth · Outbound credential injection

🔐 AgentCore Identity

5 guides covering:
Workload identity basics · Inbound JWT auth · Outbound OAuth to 3rd-party services · Per-user credential binding · OAuth consent portal

📊 AgentCore Observability

5 guides covering:
Built-in metrics (zero config) · Custom OpenTelemetry spans · One-click observability for Gateway + Memory · Cross-account telemetry · Browser session tracing

🌐 AgentCore Browser

4 guides covering:
First browser session · Nova Act natural language automation · Live view + human-in-the-loop · Session recording to S3

💻 AgentCore Code Interpreter

4 guides covering:
Python sandbox basics · Large file operations (up to 5 GB) · Multi-language (Python, JS, TypeScript) · Combined Gateway + Code Interpreter data pipeline

⚙️ AgentCore Harness

4 guides covering:
Config-only agent in 30 seconds · Built-in skills · Versioning + A/B testing · Export to Runtime code

📈 Quality, Optimization & Policy

7 guides covering:
LLM-as-Judge evaluations · Custom domain evaluators · AI-generated prompt improvements · Controlled A/B rollout · Cedar policies · Natural language policy authoring · Temporal session-aware policies

🗂️ Registry & Payments

5 guides covering:
Publish MCP servers to the Registry · Dynamic agent discovery · Cross-account sharing · x402 microtransactions · Per-session spending limits

🤝 Multi-Agent & Capstone

5 guides covering:
Orchestrator + specialists + shared Memory · A2A + Registry dynamic discovery · CrewAI crew on Runtime · Step Functions + Harness · Full production system — all services together

---

🛠 Tech Stack

Layer
Agent framework
Foundation model
Infrastructure
AgentCore services
Language
Container
Region

---

---

📐 Every Guide Has

NNN-guide-name/
├── README.md            ← What · Why · 3 Mermaid diagrams · Steps · Cost · Cleanup
├── deploy.sh            ← CDK deploy (auto-activates .venv, sets AWS_PROFILE)
├── invoke.sh            ← Test the deployed agent via boto3
├── invoke-dev.sh        ← Test against local dev server
├── dev.sh               ← Local hot-reload dev server
├── destroy.sh           ← Teardown — removes ALL AWS resources
├── Source/
│   ├── app/agent.py     ← Agent code (BedrockAgentCoreApp + @app.entrypoint)
│   ├── requirements.txt
│   └── Dockerfile       ← ARM64, port 8080
└── Infra/
    ├── app.py           ← CDK entry point
    ├── cdk.json
    ├── requirements.txt
    └── stacks/
        └── main_stack.py  ← Uses shared role from 000-common-infra

---

💰 Cost

Every guide has a Cost Estimate section. Most guides cost under $0.20/day during testing.

⚠️ Always run bash destroy.sh after testing to stop billing.

Resource
AgentCore Runtime (microVM)
AgentCore Browser
AgentCore Code Interpreter
Amazon Bedrock Nova Pro
Amazon ECR
CloudWatch Logs

See the AgentCore pricing page for current rates.

---

🤝 Contributing

Contributions welcome! Each guide follows the structure in 002-project-template.

1. Fork → create feature/NNN-guide-name branch
2. Follow the template (README · scripts · Source/ · Infra/)
3. bash deploy.sh && bash invoke.sh && bash destroy.sh must all work cleanly
4. All infrastructure via CDK — no CLI-only guides
5. Include ## Cost Estimate in the README
6. Open a PR

See CONTRIBUTING.md for the full guide.

---

👥 Contributors

---

🔗 Related Resources

Resource
AgentCore Developer Guide
AgentCore Pricing
Strands Agents SDK
AgentCore GitHub Samples (AWS)
AWS CDK Python Reference
My Kubernetes Repo

---

📄 License

MIT — see LICENSE

---

⭐ Stargazers over time

---

Built with ❤️ for the AWS agent developer community.

⭐ Star this repo to get notified when new guides drop!