AWS는 2026년 7월 15일에 Agent Toolkit for AWS를 위한 amazon-opensearch-service 스킬을 발표했습니다. 마케팅 문구에 따르면, 이 스킬은 AI 코딩 에이전트가 "자연어(natural language)로부터 직접 OpenSearch를 구축, 관리 및 쿼리"할 수 있게 해준다고 합니다. 저는 이를 설치하고 실제 작업, 즉 Amazon OpenSearch Serverless NextGen에서 처음부터 RAG (Retrieval-Augmented Generation) 검색 백엔드를 구축하는 과정을 통해 실행해 보았습니다.

이 스킬이 실제로 하는 일, 시간을 절약해 준 부분, 그리고 아예 건너뛰는 것이 더 빨랐을 단 한 가지 영역에 대해 설명하겠습니다.

이 스킬이 무엇인지 (여러분이 생각하는 것과는 다릅니다)

이 스킬은 AWS API를 감싸는 챗봇 래퍼(chatbot wrapper)가 아닙니다. 이것은 OpenSearch 관련 질문을 던질 때 코딩 에이전트의 컨텍스트(context)로 로드되는 **구조화된 지식 패키지 (structured knowledge package)**입니다. 시니어 엔지니어의 노트라고 생각하면 됩니다. 크기 산정 공식(sizing formulas), 엔진 선택 로직, 마이그레이션 체크리스트, 쿼리 DSL 레시피 등이 포함되어 있습니다. 이는 관리형 Amazon OpenSearch Service 도메인과 OpenSearch Serverless 컬렉션(collections)을 모두 다룹니다 (GitHub에서 전체 소스 확인).

이 스킬은 모든 요청을 다음 다섯 가지 기능 중 하나로 라우팅합니다:

프로비저닝(provisioning) 기능은 관리형 도메인(인스턴스 제품군, JVM 힙, OR1 트레이드오프)과 Serverless(컬렉션 그룹, OCU 제한, NextGen vs Classic) 모두에서 작동합니다. 검색(search) 기능에는 배포 방식에 따라 달라지는 크기 산정 수학(sizing math)이 포함되어 있습니다. 즉, 관리형 도메인을 위한 샤드 수(shard count) 공식과 Serverless를 위한 OCU 메모리 규칙이 있습니다. 전체 기능 설명은 공식 문서를 참조하세요.

설치하기

이 스킬은 전체 데이터 라이프사이클(data lifecycle)을 다루는 8가지 스킬이 포함된 aws-data-analytics 플러그인의 일부로 제공됩니다:

스킬 #6에 유의하세요: 이 플러그인에는 Amazon S3 Vectors 스킬도 포함되어 있습니다. 이는 RAG 워크로드(workloads)를 위한 벡터 버킷 생성, 인덱스 설정 및 쿼리 패턴을 다룹니다.

한 번에 설치하기 (Agent Toolkit 문서에서 전체 설정 가이드 확인 가능):

# Claude Code
/plugin install aws-data-analytics@claude-plugins-official
/reload-plugins
...

테스트: "처음부터 RAG 검색 백엔드를 구축해 줘"

저는 제 에이전트에게 다음과 같이 요청했습니다: "scale-to-zero 기능이 있는 OpenSearch Serverless 벡터 검색 컬렉션을 생성하고, 1024차원 Amazon Titan Embeddings G2를 위한 하이브리드 검색 인덱스를 설정하며, 5개의 샘플 문서를 수집(ingest)한 뒤 쿼리를 실행해 줘."

단계별로 진행된 과정은 다음과 같습니다.

1단계: 스킬이 scale-to-zero 기능이 있는 NextGen Serverless를 선택함

스킬은 프로비저닝 (provisioning) 역량을 감지하였고, 최소 OCU가 0인 NextGen 컬렉션 그룹을 추천했습니다. 스킬은 다음과 같이 올바른 순서를 생성했습니다:

# 1. 컬렉션 그룹 (NextGen, scale-to-zero)
aws opensearchserverless create-collection-group \
  --name agent-toolkit-demo \
...

정확했던 부분: 전체 정책 체인(암호화(encryption) → 네트워크(network) → 데이터 액세스(data access) → 컬렉션(collection)), NextGen 생성 플래그, VECTORSEARCH 타입, 그리고 scale-to-zero 용량 제한을 정확히 처리했습니다. 이 스킬이 없다면, 에이전트는 종종 Classic 컬렉션(scale-to-zero 미지원)을 생성하거나 암호화 정책(누락 시 컬렉션 생성을 조용히 차단함)을 잊어버리곤 합니다.

수행하지 못한 것: 저를 대신해 컬렉션을 생성하는 일입니다. 이 스킬은 명령어를 생성하고 순서를 설명해주지만, 실행은 여전히 사용자(또는 MCP Server의 call_aws 도구를 통한 에이전트)가 직접 수행해야 합니다. 컬렉션이 ACTIVE 상태가 되기까지 약 4분이 소요되었습니다.

2단계: 스킬이 벡터 인덱스로 FAISS HNSW를 선택했으나, NextGen에는 맞지 않았습니다

제가 하이브리드 검색 인덱스(hybrid search index)를 요청했을 때, 스킬은 search 기능을 감지하고 다음과 같은 매핑(mapping)을 추천했습니다:

index_body = {
    "settings": {
        "index": {"knn": True, "knn.algo_param.ef_search": 512}
...

이는 NextGen Serverless에서 다음과 같은 오류와 함께 실패합니다: illegal_argument_exception: Field parameter 'engine' is not supported. NextGen 컬렉션은 자체적으로 관리되는 벡터 가속(managed vector acceleration)을 사용하며(컬렉션 생성 시 ServerlessVectorAcceleration: ENABLED로 자동 활성화됨), 엔진을 직접 지정할 수 없습니다.

NextGen을 위한 올바른 매핑은 다음과 같습니다:

index_body = {
    "settings": {"index": {"knn": True}},
    "mappings": {
...

이것이 현재 이 스킬의 가장 큰 격차(gap)입니다. 스킬은 Classic Serverless와 관리형 도메인(FAISS/Lucene 엔진 선택이 중요한 곳)에 대해서는 알고 있지만, NextGen의 단순화된 벡터 API는 아직 참조 파일(reference files)에 포함되지 않았습니다. 이 스킬은 NextGen 발표와 같은 주에 출시되었으므로, 이는 시기적인 문제일 가능성이 높습니다.

3단계: NextGen에서의 데이터 주입(Ingestion)은 놀라울 정도로 빨랐습니다

스킬은 두 가지 Serverless 제한 사항에 대해 경고했습니다:

1. 사용자 정의 문서 ID(custom document IDs) 사용 불가 (자동 생성된 ID 사용)
2. 쓰기 작업에 대한 최종 일관성(eventual consistency)

# 스킬이 'id' 파라미터를 올바르게 생략했습니다
client.index(index="articles", body={
    "title": "Building RAG applications that actually work",
...

클래식 Serverless 환경에서는 문서가 검색 가능해지는 데 30~60초가 걸렸습니다. 하지만 NextGen에서는 제 문서들이 2초 만에 검색 가능했습니다. 이는 AWS가 충분히 강조하지 않은 엄청난 개선점입니다. NextGen의 분리된 컴퓨팅-스토리지 아키텍처 덕분에 쓰기 작업(writes)이 공유 스토리지 레이어에 즉시 커밋되고 거의 즉시 질의(queryable)할 수 있게 됩니다.

4단계: 검색 질의가 별도의 설정 없이 작동함

벡터 검색, 키워드 검색, 필터링된 검색 모두 올바른 결과를 반환했습니다. 이 스킬은 각 모드에 맞는 작동하는 질의 DSL(Domain Specific Language)을 생성해 주었습니다.

하이브리드 검색(BM25 + 벡터)의 경우, 이 스킬은 OpenSearch Serverless가 네이티브 하이브리드 질의를 위해 정규화 프로세서가 포함된 검색 파이프라인을 필요로 하며, 또는 클라이언트 측에서 Reciprocal Rank Fusion (RRF)을 구현할 수 있다고 언급했습니다. 간편성을 위해 클라이언트 측 RRF를 권장하며 다음과 같은 코드를 제시했습니다:

def hybrid_search(query_text, k=3):
    query_embedding = generate_embedding(query_text)

...

이 스킬이 실제 시간을 절약해 준 부분

1. 정책 순서 지정. 컬렉션이 생성되기 전에 세 가지 정책이 존재해야 합니다. 이 스킬은 그 순서와 정확한 권한 집합(개발 과정에서 누락하면 403 에러를 만날 수 있는 aoss:DeleteIndex 포함)을 알고 있습니다.

2. Serverless 전용 경고. 사용자 지정 ID, 인증 서비스 이름 `

3. NextGen을 위한 엔진 선택. 이 스킬은 "engine": "faiss"를 권장했지만, 이는 NextGen에서 illegal_argument_exception 오류를 발생시키며 실패합니다. NextGen은 벡터 가속 (vector acceleration)을 내부적으로 관리하므로, 사용자는 dimension과 space_type만 지정하면 됩니다. 이것이 이 스킬의 가장 큰 격차입니다. 가장 권장되는 배포 대상이 스킬의 기본 매핑을 거부합니다.

4. 쓰기 지연 시간 (Write latency) 기대치. 스킬은 "30-60초의 최종 일관성 (eventual consistency)"에 대해 경고했지만, 이는 Classic에는 해당되나 NextGen에는 틀린 내용입니다 (제 테스트에서는 2초였습니다). NextGen의 분리된 아키텍처 (decoupled architecture) 덕분에 쓰기 작업이 거의 즉시 반영됩니다.

관리형 도메인 질문으로 스킬 테스트하기

이 스킬은 Serverless와 관리형 도메인 (managed domains)을 모두 다룹니다. 저는 기존에 사용 중인 관리형 도메인 (t3.small, 단일 노드, OpenSearch 2.19)을 대상으로 두 가지 질문을 테스트했습니다.

단순한 질문: "내 도메인이 건강한가요? 업그레이드해야 할까요?"

스킬은 기능 (capability)을 **프로비저닝 (provisioning)**으로 감지하고 체크리스트를 생성했습니다:

• 도메인은 사용 가능한 업데이트(R20260626)가 있는 OpenSearch 2.19를 실행 중입니다. 권장 사항: 비피크 시간대(이미 20:00로 설정됨)에 적용하십시오.
• 1개의 노드를 가진 t3.small이며, 전용 마스터 (dedicated masters) 및 가용 영역 인식 (zone awareness)이 없습니다. 프로덕션 워크로드의 경우: 최소 t3.medium (2 GiB RAM 대비 4 GiB RAM)으로 업그레이드하고 고가용성 (HA)을 위해 복제본 (replica)을 활성화하십시오.
• 세밀한 액세스 제어 (Fine-grained access control)가 활성화되어 있고, 저장 시 암호화 (encryption at rest)가 켜져 있으며, 노드 간 암호화 (node-to-node encryption)가 활성 상태입니다. 보안 태세가 견고합니다.
• AutoTune이 비활성화되어 있습니다. 가변적인 워크로드를 가진 관리형 도메인의 경우 이를 활성화하십시오.

이것은 유용했습니다. 스킬은 도메인 구성을 읽고 일반적인 조언이 아닌 실행 가능한 권장 사항을 생성했습니다.

더 어려운 질문: "50만 개의 문서를 사용하는 RAG 유스케이스를 위해 이 도메인에 벡터 검색을 추가하고 싶습니다. 무엇을 변경해야 하나요?"

스킬은 기능 (capability)을 **검색 (search)**으로 감지하고 벡터/k-NN 참조로 라우팅했습니다. 스킬은 다음과 같이 권장했습니다:

• 인스턴스 업그레이드: t3.small로는 500K 벡터를 담을 수 없습니다 (1024d × 4 bytes × 500K = ~2 GB가 순수 벡터 용량이며, HNSW 그래프 오버헤드가 추가됩니다). 최소 사양은 r6g.large (16 GiB RAM) 또는 쿼리 처리량이 많은 경우 c6g.xlarge를 권장합니다.
• 샤드 계산: 500K 벡터는 단일 샤드에 적합합니다. 이중화(redundancy)를 위해 기본 샤드 1개와 복제본(replica) 1개를 구성해야 합니다.
• 엔진 선택: 1024 차원의 500K 벡터를 위해 m=16, ef_construction=256을 사용한 FAISS HNSW가 적절합니다.
• EBS 크기 지정: 현재의 20 GB는 부족합니다. 벡터 인덱스 및 원본 데이터를 포함하여 최소 50GB 이상을 권장합니다.

이후 스킬은 올바른 인덱스 매핑(관리형 도메인에서는 유효하지만 NextGen에서는 유효하지 않은 `

Terraform은 전혀 다루지 않습니다. Agent Toolkit의 어떤 스킬도 HCL을 생성하지 않습니다. Terraform 사용자에게 OpenSearch 스킬의 크기 권장 사항(sizing recommendations)은 여전히 유용하지만, 에이전트의 일반적인 학습 데이터를 사용하여 HCL로 변환해야 합니다.

스킬이 도움이 되지 않았던 부분

애플리케이션 코드 작성. 이 스킬은 쿼리 DSL 스니펫과 CLI 명령어를 생성하지만, 완전한 Python 애플리케이션을 생성하지는 않습니다. Bedrock 임베딩(embedding) 호출, opensearch-py 클라이언트 설정, 데이터 수집(ingestion) 루프, 그리고 검색 로직은 여전히 직접 작성해야 합니다.

비용 추정. 이 스킬은 달러 금액을 산출하는 것을 명시적으로 거부합니다. 만약