aws-samples/sample-agentic-platform

AWS에서 에이전틱 플랫폼 (agentic platform)이 어떤 모습일 수 있는지 보여주는 샘플입니다. 이 저장소는 여러 컴퓨팅 계층 (compute layer) 옵션, 공유 코어 라이브러리 (shared core library), 게이트웨이 서비스 (gateway services), 그리고 다양한 프레임워크로 구축된 에이전트 (agents) 모음을 보여주며, 이 모든 것이 작동 가능한 참조 아키텍처 (reference architecture)로 연결되어 있습니다.

에이전트 코딩 도구 (Claude Code, Kiro, Cursor 등)가 한 곳에서 전체 그림을 볼 수 있도록 모노레포 (monorepo) 구조로 구성되었습니다. AGENTS.md 파일 트리 구조는 이러한 도구들이 코드베이스를 탐색하는 데 도움을 줍니다. 루트(root)에 있는 AGENTS.md는 인프라 (infrastructure), Kubernetes, 애플리케이션 코드 (application code), 부트스트랩 (bootstrap), 테스트 (tests), 그리고 실습 (labs)을 위한 도메인별 가이드를 가리키는 목차 역할을 합니다. CLAUDE.md 파일은 단순히 "AGENTS.md를 참조하세요"라고 명시하여, 서로 다른 도구들 사이에서도 동일한 스캐폴딩 (scaffolding)이 작동하도록 합니다.

이 샘플은 활발하게 유지 관리되고 있습니다. 기여 (Contributions)를 환영합니다 — Contributing 파일을 참조하세요.

플랫폼은 필요에 따라 조합할 수 있는 계층화된 인프라 스택 (infrastructure stacks)으로 구성됩니다:

┌─────────────────────────────────────────────────────────────┐
│ 애플리케이션 (Applications) │
│ 에이전트 (Agents) · MCP 서버 (MCP Servers) · 메모리 게이트웨이 (Memory Gateway) · 검색 게이트웨이 (Retrieval Gateway) │
...

스택 (Stack)	경로 (Path)	목적 (Purpose)
Foundation	infrastructure/stacks/foundation/	네트워킹 (VPC, 서브넷 (subnets), NAT 게이트웨이 (NAT gateways), 보안 그룹 (security groups)). 가장 먼저 배포되며 — 다른 모든 요소가 이 위에 구축됩니다.
Platform EKS	infrastructure/stacks/platform-eks/	EKS 클러스터, IRSA 역할 (roles), Cognito, Aurora PostgreSQL, ElastiCache, 배스천 호스트 (bastion host), 그리고 클러스터 내에 배포되는 LiteLLM 게이트웨이 (gateway).
Platform AgentCore	infrastructure/stacks/platform-agentcore/	ECS/Fargate를 사용하는 "Lite" 컴퓨팅 레이어 (compute layer). ECS 내에 LiteLLM 게이트웨이를 Cognito, Aurora, ElastiCache 및 배스천 호스트와 함께 배포합니다.
AgentCore Runtime	infrastructure/stacks/agentcore-runtime/	개별 에이전트 (agents)를 Amazon Bedrock AgentCore Runtime에 배포합니다. 인프라 코드의 중복을 최소화하기 위해 에이전트당 하나의 워크스페이스 (workspace)를 사용하는 Terraform 워크스페이스 (workspaces)를 사용합니다.
Knowledge Layer	infrastructure/stacks/knowledge-layer/	RAG를 위한 Bedrock 지식 기반 (Knowledge Base)을 설정합니다. 더 많은 예시가 추가됨에 따라 더 정교한 검색 레이어 (retrieval layer)로 발전할 계획입니다.

Foundation 스택을 가장 먼저 배포한 다음, 두 가지 경로 중 하나를 선택합니다:

옵션 A — Kubernetes (EKS): 완전한 제어 권한을 가집니다. platform-eks 스택을 배포한 다음, k8s/ 아래의 Helm 차트 (Helm charts)를 통해 에이전트와 서비스를 배포합니다. LLM 게이트웨이, 텔레메트리 수집기 (telemetry collectors), 그리고 기타 플랫폼 심 (platform shims)이 에이전트와 함께 클러스터 내에서 실행됩니다.

옵션 B — AgentCore (ECS + 관리형 런타임 (Managed Runtime)): 운영 오버헤드가 적습니다. platform-agentcore 스택을 배포하여 ECS에서 LLM 게이트웨이가 실행되도록 한 다음, agentcore-runtime 스택을 사용하여 AgentCore Runtime에 에이전트를 배포합니다 (에이전트당 하나의 Terraform 워크스페이스).

두 경로 모두 동일한 에이전트 코드를 공유합니다. 모든 에이전트는 AgentCore 인터페이스 (interface) (포트 8080, /invocations 엔드포인트 (endpoint))를 구현하므로, 어디에 배포할지는 사용자의 선택에 달려 있습니다.

플랫폼은 두 가지 라이프사이클 (lifecycles)을 구분합니다:

플랫폼 인프라 (Platform infrastructure) (LLM 게이트웨이 (LLM gateway), 텔레메트리 (telemetry), 인증 심 (auth shims)) — 변경 빈도가 낮으며, 플랫폼 팀에서 관리합니다.
애플리케이션 코드 (Application code) (에이전트 (agents), MCP 서버 (MCP servers), 지원 서비스 (supporting services)) — 변경 빈도가 높으며, 애플리케이션 팀에 의해 독립적으로 배포됩니다.

이러한 분리는 스택 설계와 Helm 차트 레이아웃에 반영되어 있습니다.

각 에이전트는 타입 (types), 클라이언트 추상화 (client abstractions), 미들웨어 (middleware)를 포함하는 코어 패키지 (core package)를 공유하는 FastAPI 서버로 실행됩니다. 에이전트는 IAM 역할을 직접 보유하지 않으며, IRSA를 사용하는 게이트웨이 서비스 (LLM 게이트웨이 (LLM Gateway), 메모리 게이트웨이 (Memory Gateway), 검색 게이트웨이 (Retrieval Gateway))를 통해 AWS 리소스에 연결합니다. 모든 서비스 간 통신은 IDP의 공개 인증서 (public cert)를 통해 검증되는 JWT 토큰을 통해 인증됩니다. 텔레메트리 (Telemetry)는 OpenTelemetry를 통해 수집되어 X-Ray, CloudWatch 및 OpenSearch로 전송됩니다.

게이트웨이 계층에는 ECS를, 에이전트 실행에는 AgentCore Runtime을 사용하는 Amazon Bedrock AgentCore 프리미티브 (primitives)를 활용한 관리형 접근 방식입니다.

디렉토리	내용
infrastructure/	Terraform 스택 및 20개 이상의 재사용 가능한 모듈
k8s/	EKS 배포를 위한 Helm 차트 및 애플리케이션별 설정 값 (values)
src/agentic_platform/	에이전트 구현, 공유 코어 라이브러리, 게이트웨이 서비스, MCP 서버 및 도구
labs/	25개 이상의 Jupyter 노트북이 포함된 5개의 학습 모듈
bootstrap/	AWS 계정 부트스트래핑을 위한 CloudFormation 템플릿
deploy/	빌드 및 배포 스크립트
tests/	단위 테스트 (Unit tests) 및 통합 테스트 (integration tests)

다양한 프레임워크로 구축된 샘플 에이전트 — 모두 동일한 인터페이스 (포트 8080, /invocations, /health)를 공유합니다:

에이전트	프레임워크	설명
agentic_chat	Strands	범용 채팅 에이전트
agentic_rag	Strands	Bedrock Knowledge Base를 기반으로 하는 RAG 에이전트
langgraph_chat	LangGraph	LangGraph 워크플로 (workflows)를 사용하는 채팅 에이전트
jira_agent	Strands	Jira 통합 에이전트
strands_glue_athena	Strands	AWS Glue 및 Athena 데이터 에이전트

전체 개발 가이드는 AGENTS.md를 참조하세요.

기초부터 프로덕션(Production) 단계까지 안내하는 5가지 단계별 모듈:

모듈	주제	학습 내용
1	프롬프트 엔지니어링 및 평가 (Prompt Engineering & Evaluation)	Bedrock Converse API, 사고의 사슬 (chain-of-thought), 퓨샷 (few-shot), RAG 기초, 함수 호출 (function calling), 평가
2	일반적인 에이전트 패턴 (Common Agentic Patterns)	프롬프트 체이닝 (Prompt chaining), 라우팅 (routing), 병렬화 (parallelization), 오케스트레이션 (orchestration), 평가자-최적화 도구 (evaluator-optimizer)
3	에이전트 애플리케이션 구축 (Building Agentic Applications)	에이전트 메모리 (Agent memory), 도구 (tools), 검색 (retrieval), 프레임워크 상호 운용성 (framework interoperability)
4	멀티 에이전트 시스템 및 MCP (Multi-Agent Systems & MCP)	MCP 서버 및 클라이언트, 멀티 에이전트 위임 (multi-agent delegation), 에이전트 그래프 (agent graphs), AgentCore 도구
5	배포 및 인프라 (Deployment & Infrastructure)	OpenTelemetry, LLM 게이트웨이 (LLM gateway), 메모리 게이트웨이 (memory gateway), 스트리밍 (streaming), 확장 (scaling)

모듈 5만 플랫폼 배포가 필요합니다. 실습(Labs)을 로컬에서 실행하려면:

uv sync
uv run jupyter lab

자세한 지침은 labs/README.md를 참조하세요.

사전 요구 사항: Python 3.12, uv, Docker

# 클론 및 설치
git clone https://github.com/aws-samples/sample-agentic-platform.git
cd sample-agentic-platform
...

사용 가능한 모든 명령어를 확인하려면 make help를 실행하세요.

DEPLOYMENT.md를 참조하세요.

변경 사항을 제출하기 전에 보안 스캔을 실행하세요:

억제된 경고 (Suppressed Warnings): 환경에서 코드를 사용하기 전에 코드베이스에 억제된 경고를 검토하십시오.

자세한 내용은 CONTRIBUTING을 참조하세요.

기여를 환영합니다. 로드맵에 포함된 항목은 다음과 같습니다:

• 부트스트랩(bootstrap) 경험 개선

• 배포를 위한 구조화된 GitOps

• 고급 에이전트 주제에 대한 추가 실습

• 테스트 하네스(Test harness) 및 평가 스위트 (eval suite)

• 실습의 더 많은 에이전트 예제를 샘플 플랫폼으로 통합

• 지식/검색 계층 확장

• Tanner McRae

• Randy DeFauw

• James Levine

이 라이브러리는 MIT-0 라이선스 하에 배포됩니다. LICENSE 파일을 참조하세요.