{"id":49339567,"url":"https://github.com/citadel-cloud-management/agentforge-portal","last_synced_at":"2026-04-27T03:03:15.048Z","repository":{"id":344368222,"uuid":"1181220510","full_name":"Citadel-Cloud-Management/agentforge-portal","owner":"Citadel-Cloud-Management","description":"AgentForge - AI Agent Engineering Curriculum \u0026 Amazon Bedrock AgentCore Crash Course","archived":false,"fork":false,"pushed_at":"2026-04-11T22:20:28.000Z","size":425,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-12T00:34:32.611Z","etag":null,"topics":["ai-agents","architecture","aws","azure","bedrock","curriculum","devops","enterprise","gcp","terraform"],"latest_commit_sha":null,"homepage":"https://citadel-cloud-management.github.io/agentforge-portal/","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Citadel-Cloud-Management.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":"SECURITY.md","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-03-13T22:01:35.000Z","updated_at":"2026-04-11T22:39:23.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Citadel-Cloud-Management/agentforge-portal","commit_stats":null,"previous_names":["kogunlowo123/agentforge-portal","citadel-cloud-management/agentforge-portal"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/Citadel-Cloud-Management/agentforge-portal","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Citadel-Cloud-Management%2Fagentforge-portal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Citadel-Cloud-Management%2Fagentforge-portal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Citadel-Cloud-Management%2Fagentforge-portal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Citadel-Cloud-Management%2Fagentforge-portal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Citadel-Cloud-Management","download_url":"https://codeload.github.com/Citadel-Cloud-Management/agentforge-portal/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Citadel-Cloud-Management%2Fagentforge-portal/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32320686,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T23:26:28.701Z","status":"online","status_checked_at":"2026-04-27T02:00:06.769Z","response_time":128,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["ai-agents","architecture","aws","azure","bedrock","curriculum","devops","enterprise","gcp","terraform"],"created_at":"2026-04-27T03:03:10.315Z","updated_at":"2026-04-27T03:03:15.040Z","avatar_url":"https://github.com/Citadel-Cloud-Management.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Python](https://img.shields.io/badge/Python-3.11+-blue?logo=python\u0026logoColor=white)\n![License](https://img.shields.io/badge/License-MIT-green)\n![GitHub release](https://img.shields.io/github/v/release/kogunlowo123/agentforge-portal)\n\n# Amazon Bedrock AgentCore Crash Course\n\nA hands-on, production-focused introduction to **Amazon Bedrock AgentCore** — a fully managed service for building, deploying, and operating intelligent AI agents at scale. This repository walks you through three progressive examples that demonstrate how to build AI agents leveraging language models, RAG (Retrieval-Augmented Generation), tool use, and persistent memory management.\n\n\u003e **Live Curriculum Portal**: [kogunlowo123.github.io/agentforge-portal](https://kogunlowo123.github.io/agentforge-portal/) — the full AgentForge AI Agent Engineering Curriculum covering 8 enterprise agent categories, 40+ cloud services, and 32 hands-on exercises.\n\n---\n\n## Table of Contents\n\n- [Course Overview](#-course-overview)\n- [Architecture](#-architecture)\n- [Prerequisites](#-prerequisites)\n- [Installation](#-installation)\n- [Running the Agents](#-running-the-agents)\n  - [Example 0: LangGraph Agent](#example-0-basic-langgraph-agent-00_langgraph_agentpy)\n  - [Example 1: AgentCore Runtime](#example-1-agentcore-runtime-agent-01_agentcore_runtimepy)\n  - [Example 2: AgentCore with Memory](#example-2-agentcore-with-memory-02_agentcore_memorypy)\n- [Project Structure](#-project-structure)\n- [Key Concepts](#-key-concepts)\n- [Configuration Reference](#-configuration-reference)\n- [Troubleshooting](#-troubleshooting)\n- [Additional Resources](#-additional-resources)\n- [Contributing](#-contributing)\n- [License](#-license)\n\n---\n\n## Course Overview\n\nThis course includes three example implementations of increasing complexity, each building on the previous one:\n\n| Example | File | What You Learn |\n|---------|------|----------------|\n| **0 — LangGraph Agent** | `00_langgraph_agent.py` | Build a basic ReAct agent with LangGraph, define tools for FAQ search, use FAISS vector store for semantic retrieval |\n| **1 — AgentCore Runtime** | `01_agentcore_runtime.py` | Deploy your agent into the AgentCore managed runtime, define an entrypoint handler, configure and launch via the AgentCore CLI |\n| **2 — AgentCore + Memory** | `02_agentcore_memory.py` | Add persistent conversation memory with `AgentCoreMemorySaver` and `AgentCoreMemoryStore`, implement pre/post-model middleware hooks, track sessions and user preferences |\n\nEach example uses the **Lauki Q\u0026A dataset** (`lauki_qna.csv`) as a knowledge base for the agent to search and provide answers to user questions about telecom products and services.\n\n---\n\n## Architecture\n\n```\n                          ┌─────────────────────────────┐\n                          │     User / Client App       │\n                          └─────────────┬───────────────┘\n                                        │ invoke\n                          ┌─────────────▼───────────────┐\n                          │   AgentCore Runtime (AWS)    │\n                          │   - Entrypoint handler       │\n                          │   - Managed scaling          │\n                          │   - Session management       │\n                          └─────────────┬───────────────┘\n                                        │\n                 ┌──────────────────────┼──────────────────────┐\n                 │                      │                      │\n     ┌───────────▼──────────┐ ┌────────▼─────────┐ ┌─────────▼──────────┐\n     │   LangGraph Agent    │ │   FAISS Vector   │ │  AgentCore Memory  │\n     │   - ReAct loop       │ │   Store          │ │  - Checkpointer    │\n     │   - Tool routing     │ │   - Embeddings   │ │  - Long-term store │\n     │   - Groq LLM         │ │   - Similarity   │ │  - Session history │\n     └──────────────────────┘ └──────────────────┘ └────────────────────┘\n```\n\n### Data Flow\n\n1. **User submits a prompt** via `agentcore invoke` or API call\n2. **AgentCore Runtime** receives the payload and routes it to the entrypoint handler\n3. **Pre-model middleware** (Example 2) saves the message to long-term memory and retrieves relevant user preferences\n4. **LangGraph agent** processes the query using a ReAct loop — reasoning about which tools to call\n5. **Tools** (`search_faq`, `search_detailed_faq`, `reformulate_query`) query the FAISS vector store for semantically relevant FAQ entries\n6. **Agent synthesises** the retrieved context into a final response\n7. **Post-model middleware** (Example 2) saves the AI response to long-term memory\n8. **Response** is returned to the caller with the answer and session metadata\n\n---\n\n## Prerequisites\n\n### System Requirements\n\n| Requirement | Version | Installation |\n|-------------|---------|-------------|\n| **Python** | 3.13+ | [python.org/downloads](https://www.python.org/downloads/) |\n| **uv** | Latest | `pip install uv` or [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/) |\n| **AWS CLI** | v2+ | [AWS CLI install guide](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) |\n| **AgentCore CLI** | Latest | Installed via `bedrock-agentcore` package |\n\nVerify your setup:\n\n```bash\npython --version       # Should be 3.13+\nuv --version           # Should return a version\naws --version          # Should be aws-cli/2.x\n```\n\n### AWS Account \u0026 Credentials\n\n1. An **AWS account** with access to Amazon Bedrock enabled\n2. **AWS credentials** configured locally:\n   ```bash\n   aws configure\n   # Enter your Access Key ID, Secret Access Key, default region, and output format\n   ```\n3. Region set to a supported AgentCore region (e.g., `us-east-1`, `us-west-2`, `ap-southeast-2`)\n4. Ensure your IAM user/role has the following permissions:\n   - `bedrock:InvokeModel`\n   - `bedrock-agentcore:*` (for AgentCore runtime operations)\n   - `dynamodb:*` (for memory storage in Example 2)\n\n### API Keys\n\n| Key | Required For | Where to Get It |\n|-----|-------------|-----------------|\n| **GROQ_API_KEY** | LLM inference (all examples) | [console.groq.com](https://console.groq.com) — sign up and create an API key |\n| **HF_API_KEY** | HuggingFace embeddings (optional, for gated models) | [huggingface.co/settings/tokens](https://huggingface.co/settings/tokens) |\n\n---\n\n## Installation\n\n### Step 1: Clone the Repository\n\n```bash\ngit clone https://github.com/kogunlowo123/agentforge-portal.git\ncd agentforge-portal\n```\n\n### Step 2: Install Dependencies\n\n```bash\nuv sync\n```\n\nThis installs all dependencies from `pyproject.toml`, including:\n\n- **`bedrock-agentcore`** — AgentCore runtime SDK\n- **`langchain[aws]`** / **`langgraph`** — Agent framework and graph orchestration\n- **`langchain-groq`** — Groq LLM integration\n- **`langchain-huggingface`** — HuggingFace embeddings (uses `sentence-transformers/all-MiniLM-L6-v2`)\n- **`faiss-cpu`** — Vector similarity search\n- **`langgraph-checkpoint-aws`** — AgentCore memory checkpointing\n\n### Step 3: Configure Environment Variables\n\nCreate a `.env` file in the project root:\n\n```bash\ncp .sample_env .env\n```\n\nEdit `.env` with your credentials:\n\n```env\nGROQ_API_KEY=gsk_your_groq_api_key_here\nHF_API_KEY=hf_your_huggingface_api_key_here\n```\n\n\u003e **Security Note**: The `.env` file is excluded from version control via `.gitignore`. Never commit API keys to your repository.\n\n---\n\n## Running the Agents\n\n### Example 0: Basic LangGraph Agent (`00_langgraph_agent.py`)\n\n**What it does**: Creates a standalone LangGraph agent with three tools for FAQ search. No cloud deployment — runs entirely locally.\n\n**Key components**:\n- **`load_faq_csv()`** — Loads the Lauki Q\u0026A CSV into LangChain `Document` objects\n- **`HuggingFaceEmbeddings`** — Generates vector embeddings using `all-MiniLM-L6-v2`\n- **`FAISS.from_documents()`** — Builds an in-memory vector store from the FAQ documents\n- **`search_faq`** — Returns top-3 semantically similar FAQ entries\n- **`search_detailed_faq`** — Returns top-5 entries for complex queries\n- **`reformulate_query`** — Re-frames a question to focus on a specific aspect before searching\n- **`ChatGroq`** — LLM via Groq API (`openai/gpt-oss-20b` model)\n\n```bash\npython 00_langgraph_agent.py\n```\n\n**Expected output**: The agent will answer \"Explain roaming activation\" by searching the FAQ knowledge base, potentially calling multiple tools, and synthesizing a response.\n\n---\n\n### Example 1: AgentCore Runtime Agent (`01_agentcore_runtime.py`)\n\n**What it does**: Wraps the same agent in the AgentCore managed runtime, enabling cloud deployment, scaling, and invocation via the AgentCore CLI.\n\n**What's new compared to Example 0**:\n- **`BedrockAgentCoreApp()`** — Initializes the AgentCore application container\n- **`@app.entrypoint`** — Decorator that registers the handler function for incoming invocations\n- **`app.run()`** — Starts the AgentCore runtime server\n- **Payload-based invocation** — The agent receives a JSON payload with a `prompt` field\n\n**Step 1 — Configure**:\n```bash\nagentcore configure -e 01_agentcore_runtime.py\n```\nThis generates `bedrock_agentcore.yaml` with tool definitions and agent configuration.\n\n**Step 2 — Deploy**:\n```bash\nagentcore launch --env GROQ_API_KEY=your_groq_api_key_here\n```\n\n**Step 3 — Test**:\n```bash\nagentcore invoke '{\"prompt\": \"Explain roaming activation\"}'\n```\n\n**Step 4 — Try more queries**:\n```bash\nagentcore invoke '{\"prompt\": \"What are the data plan options?\"}'\nagentcore invoke '{\"prompt\": \"How do I troubleshoot network issues?\"}'\nagentcore invoke '{\"prompt\": \"Compare prepaid and postpaid plans\"}'\n```\n\n---\n\n### Example 2: AgentCore with Memory (`02_agentcore_memory.py`)\n\n**What it does**: Extends Example 1 with persistent memory — the agent remembers conversation history and user preferences across sessions.\n\n**What's new compared to Example 1**:\n- **`AgentCoreMemorySaver`** — Checkpoints agent state (conversation thread) to AgentCore Memory\n- **`AgentCoreMemoryStore`** — Long-term key-value store for user preferences and cross-session data\n- **`MemoryMiddleware`** — Custom middleware with pre/post-model hooks:\n  - **`pre_model_hook`**: Saves the latest human message and retrieves relevant user preferences before LLM invocation\n  - **`post_model_hook`**: Saves AI responses to long-term memory after LLM invocation\n- **`actor_id` / `thread_id`** — Session and user tracking for personalized memory retrieval\n\n**Step 1 — Configure**:\n```bash\nagentcore configure -e 02_agentcore_memory.py\n```\n\n**Step 2 — Deploy**:\n```bash\nagentcore launch --env GROQ_API_KEY=your_groq_api_key_here\n```\n\n**Step 3 — Test with session context**:\n```bash\n# First message in a session\nagentcore invoke '{\"prompt\": \"I prefer detailed technical explanations\", \"actor_id\": \"user-1\", \"thread_id\": \"session-1\"}'\n\n# Follow-up in the same session — the agent remembers your preference\nagentcore invoke '{\"prompt\": \"Explain roaming activation\", \"actor_id\": \"user-1\", \"thread_id\": \"session-1\"}'\n\n# New session, same user — cross-session preference retrieval\nagentcore invoke '{\"prompt\": \"What data plans are available?\", \"actor_id\": \"user-1\", \"thread_id\": \"session-2\"}'\n```\n\n---\n\n## Project Structure\n\n```\nagentcore-crash-course/\n├── 00_langgraph_agent.py       # Example 0: Standalone LangGraph agent\n├── 01_agentcore_runtime.py     # Example 1: AgentCore runtime deployment\n├── 02_agentcore_memory.py      # Example 2: AgentCore with persistent memory\n├── lauki_qna.csv               # FAQ knowledge base dataset\n├── index.html                  # AgentForge curriculum portal (GitHub Pages)\n├── pyproject.toml              # Python project config and dependencies\n├── uv.lock                     # Locked dependency versions\n├── .sample_env                 # Example environment variables\n├── .gitignore                  # Git ignore rules\n├── .dockerignore               # Docker ignore rules\n└── .github/\n    └── workflows/\n        └── static.yml          # GitHub Pages deployment workflow\n```\n\n---\n\n## Key Concepts\n\n### ReAct Loop (Reason + Act)\n\nAll three examples use the **ReAct pattern**: the agent reasons about the user's question, decides which tool to call, observes the result, and repeats until it has enough information to answer. This is implemented via LangGraph's agent executor.\n\n### Semantic Search with FAISS\n\nThe FAQ knowledge base is loaded from CSV, split into chunks (500 characters, no overlap), embedded using `sentence-transformers/all-MiniLM-L6-v2`, and indexed in a FAISS vector store. Similarity search returns the most relevant entries for any natural language query.\n\n### AgentCore Runtime\n\nAgentCore provides a fully managed execution environment for your agents. Key benefits:\n- **Zero infrastructure management** — no servers, containers, or scaling config\n- **Built-in session handling** — each invocation is isolated and tracked\n- **CLI-driven workflow** — `configure` → `launch` → `invoke`\n- **Production-grade observability** — structured logging and monitoring\n\n### AgentCore Memory\n\nThe memory system in Example 2 has two layers:\n- **Checkpointer (`AgentCoreMemorySaver`)**: Saves full agent state per thread — enables conversation continuity within a session\n- **Store (`AgentCoreMemoryStore`)**: Key-value store for cross-session data — user preferences, long-term facts, and searchable memories\n\n### Middleware Hooks\n\nThe `MemoryMiddleware` class intercepts the agent loop at two points:\n- **Pre-model**: Runs before the LLM is called. Saves the human message and injects retrieved memories into context.\n- **Post-model**: Runs after the LLM responds. Saves the AI message for future retrieval.\n\n---\n\n## Configuration Reference\n\n### `bedrock_agentcore.yaml` (auto-generated)\n\nThis file is created by `agentcore configure` and defines:\n- **Entrypoint**: The Python file and handler function\n- **Tools**: Schemas for `search_faq`, `search_detailed_faq`, `reformulate_query`\n- **Environment variables**: Runtime secrets (passed via `--env` flags)\n- **Memory settings**: Memory ID and region (Example 2 only)\n\n### Environment Variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `GROQ_API_KEY` | Yes | API key for Groq LLM service |\n| `HF_API_KEY` | Optional | HuggingFace API key for gated embedding models |\n| `AWS_DEFAULT_REGION` | Yes (implicit) | AWS region for AgentCore (set via `aws configure`) |\n\n### Memory Configuration (Example 2)\n\n| Setting | Value | Description |\n|---------|-------|-------------|\n| `REGION` | `ap-southeast-2` | AWS region for memory service |\n| `MEMORY_ID` | `lauki_agent_memory-Yrm3JrG0Vz` | Unique identifier for the memory instance |\n\n---\n\n## Troubleshooting\n\n### Python version error\n\n```\nERROR: Requires Python \u003e=3.13\n```\n**Solution**: Install Python 3.13 or newer from [python.org/downloads](https://www.python.org/downloads/). Verify with `python --version`.\n\n### Missing `GROQ_API_KEY`\n\n```\nError: GROQ_API_KEY not found\n```\n**Solution**: Ensure your `.env` file exists in the project root and contains a valid key:\n```bash\ncat .env  # Should show GROQ_API_KEY=gsk_...\n```\n\n### FAISS installation fails\n\n```\nERROR: Could not find a version that satisfies the requirement faiss-cpu\n```\n**Solution**: Install the CPU version explicitly:\n```bash\nuv pip install --upgrade faiss-cpu\n```\nOn Apple Silicon Macs, you may also need:\n```bash\nuv pip install faiss-cpu --no-binary :all:\n```\n\n### AWS credentials not found\n\n```\nbotocore.exceptions.NoCredentialsError: Unable to locate credentials\n```\n**Solution**: Configure AWS credentials:\n```bash\naws configure\n# Or set environment variables:\nexport AWS_ACCESS_KEY_ID=your_key\nexport AWS_SECRET_ACCESS_KEY=your_secret\nexport AWS_DEFAULT_REGION=us-east-1\n```\n\n### AgentCore launch fails\n\n```\nError: Could not connect to AgentCore service\n```\n**Solution**: Verify your region supports AgentCore and your IAM permissions include `bedrock-agentcore:*`. Check:\n```bash\naws sts get-caller-identity  # Verify credentials are valid\n```\n\n### Embedding model download is slow\n\nThe first run downloads the `all-MiniLM-L6-v2` model (~80MB). This is cached after the first download. If it times out, set:\n```bash\nexport HF_HUB_DOWNLOAD_TIMEOUT=300\n```\n\n---\n\n## Additional Resources\n\n### Official Documentation\n\n- [Amazon Bedrock AgentCore — Product Page](https://aws.amazon.com/bedrock/agentcore/?trk=33dad69a-efe5-4eb8-b3eb-bfdc0cf9a3c0\u0026sc_channel=el)\n- [Amazon Bedrock AgentCore — Developer Guide](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/agentcore-get-started-toolkit.html/?trk=33dad69a-efe5-4eb8-b3eb-bfdc0cf9a3c0\u0026sc_channel=el)\n- [Amazon Bedrock AgentCore — Code Samples](https://github.com/awslabs/amazon-bedrock-agentcore-samples)\n\n### Frameworks \u0026 Tools\n\n- [LangGraph Documentation](https://langchain-ai.github.io/langgraph/) — Graph-based agent orchestration\n- [LangChain Documentation](https://python.langchain.com/) — LLM application framework\n- [FAISS Documentation](https://faiss.ai/) — Efficient similarity search library\n- [Groq API Documentation](https://console.groq.com/docs) — Ultra-fast LLM inference\n- [HuggingFace Sentence Transformers](https://www.sbert.net/) — Text embedding models\n- [uv Package Manager](https://docs.astral.sh/uv/) — Fast Python dependency management\n\n### Related Learning\n\n- [Build With AgentCore Challenge](https://aws.amazon.com/bedrock/agentcore/) — AWS community challenge\n- [AgentForge Curriculum Portal](https://kogunlowo123.github.io/agentforge-portal/) — Full 8-category AI agent engineering curriculum\n\n---\n\n## Contributing\n\nContributions are welcome! To contribute:\n\n1. Fork this repository\n2. Create a feature branch: `git checkout -b feature/your-feature`\n3. Make your changes and test locally\n4. Commit with a descriptive message\n5. Push and open a Pull Request\n\nPlease ensure all examples run successfully before submitting.\n\n---\n\n## License\n\nMIT License\n\n---\n\nCopyright Codebasics Inc. All rights reserved.\n\nBuilt by [Kehinde Ogunlowo](https://github.com/kogunlowo123)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcitadel-cloud-management%2Fagentforge-portal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcitadel-cloud-management%2Fagentforge-portal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcitadel-cloud-management%2Fagentforge-portal/lists"}